chaff

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/gulsahsarsilmaz/chaff/main/assets/banner-dark.svg"> <img alt="chaff — separate the live work from the dead weight" src="https://raw.githubusercontent.com/gulsahsarsilmaz/chaff/main/assets/banner-light.svg" width="100%"> </picture> </p> <p align="center"> <a href="https://www.npmjs.com/package/@gulsahsarsilmaz/chaff"><img alt="npm" src="https://img.shields.io/npm/v/@gulsahsarsilmaz/chaff?color=f0b545&label=npm"></a> <a href="https://github.com/gulsahsarsilmaz/chaff/actions/workflows/test.yml"><img alt="tests" src="https://github.com/gulsahsarsilmaz/chaff/actions/workflows/test.yml/badge.svg"></a> <img alt="zero dependencies" src="https://img.shields.io/badge/dependencies-0-7ee787"> <img alt="node 20+" src="https://img.shields.io/badge/node-%E2%89%A520-79c0ff"> <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-d7dde3"></a> <a href="https://buymeacoffee.com/gulsahsarsilmaz"><img alt="Buy me a coffee" src="https://img.shields.io/badge/buy%20me%20a%20coffee-support-f0b545?logo=buymeacoffee&logoColor=white"></a> </p> <p align="center"> <a href="#quick-start">Quick start</a> · <a href="#install-as-a-claude-code-plugin">Claude Code plugin</a> · <a href="#use-it-from-any-agent-mcp">MCP for any agent</a> · <a href="#safety-model">Safety model</a> · <a href="https://github.com/users/gulsahsarsilmaz/projects/1">Roadmap</a> · <a href="#contributing">Contributing</a> · <a href="#support-chaff">Support</a> </p>

---

Welcome. If your laptop fans are screaming, your disk is mysteriously full, and you have a dozen agent worktrees you're afraid to delete — chaff is for you. It looks at everything your toolchains leave behind, works out what is still alive, and tells you exactly what each cleanup would cost before it touches anything.

Quick start

You need macOS, Linux or Windows and Node 20 or newer (platform notes). No config, no dependencies.

Just want a look? This runs it without installing anything, and changes nothing:

cd ~/code/your-project      # run it from inside a project, not your home folder
npx @gulsahsarsilmaz/chaff plan

Keeping it:

npm install -g @gulsahsarsilmaz/chaff

chaff plan     # see what's reclaimable, sorted by tier. Changes nothing.
chaff reap     # reclaim tier 1 only: things whose owner no longer exists

Or with Homebrew (macOS and Linux):

brew install gulsahsarsilmaz/chaff/chaff

The npm package name includes the scope: npm install chaff finds nothing.

Run from inside a project, chaff scans that repo and its siblings. Run from your home folder, it scans no projects at all. To cover your whole machine from anywhere, point it at your code folders once with chaff config --set=roots=~/code (several: --set=roots=~/code,~/work). If it doesn't work first time, see Troubleshooting.

<p align="center"> <img alt="Example output of chaff plan, grouped into tier 1 dead, tier 2 idle and tier 3 live" src="https://raw.githubusercontent.com/gulsahsarsilmaz/chaff/main/assets/plan.svg" width="100%"> </p>

Like what you see? Add it to Claude Code for a live statusline, or wire it into any MCP agent. Everything it deletes goes to a trash you can restore from.

How it works

chaff finds every build process, daemon, cache, build output, package store and git worktree across your projects — JS/TS, Rust, Go, .NET, JVM, Python, Unity, Unreal — works out which are still alive, and sorts the rest into three tiers by how much it would hurt to reclaim.

Built for the case where you have a dozen agent worktrees in flight, half a dozen build daemons you didn't know were running, and no way to tell which is safe to kill.

Why

nx reset clears one workspace at a time. cargo clean clears one crate. ps | grep node tells you a process exists but not which project owns it or whether anything still needs it. du -sh * takes five minutes and doesn't know what's regenerable. Orphan-process reapers don't understand build tools, and none of them can tell an idle daemon from one with a build in flight.

chaff attributes every process to a project by walking the process tree in both directions, sizes every regenerable artifact in one batched pass, ages every worktree by its last commit, and tells you what each cleanup would actually cost you.

The three tiers

| Tier | Meaning | What it costs | | --- | --- | --- | | 1 — dead | The project, worktree, or parent process it belongs to no longer exists | Nothing. It is already garbage. | | 2 — idle | Nothing running against it, nothing touched it recently | One cold rebuild, or a re-download. | | 3 — live | Touches a running task, an active build, or uncommitted work | Potentially real work. Never automatic. |

Entries marked [locked], [in use], or [building] are shown but never executed, even with --force.

What it found on the machine it was built for

One laptop, mid-afternoon, during ordinary parallel agent work:

load average    713          →  7
nx daemons      6 (one at 646% CPU for 88 min, unnoticed)
node processes  68           →  11
git worktrees   111          →  50      (76 of them hidden in .claude/worktrees/)
disk free       36.5 GB      →  59 GB

And the things nothing was reporting at all:

76.5 GB   Cargo target dirs — 53.7 GB of it six copies of the same src-tauri/target
77.1 GB   node_modules across 40 installs, with a 0.1 GB pnpm store (not hardlinked)
14.2 GB   one iOS build directory
 4.1 GB   npm cache

What it tracks

Processes — nx daemons and workers, turbo daemons, tsserver, watchman, metro, esbuild, swc, tsc, jest/vitest/playwright/cypress, next/vite/webpack/nodemon/storybook/wrangler, eslint/prettier/biome, plus JVM/Gradle daemons, dotnet/MSBuild/OmniSharp, Go, Cargo, Python, Unity and Unreal editors. Each is attributed to the project that owns it.

Build artifacts, by ecosystem

| | cache | output | | --- | --- | --- | | JS/TS | .nx .turbo .angular .parcel-cache .vite .rollup.cache .rspack-cache .webpack-cache .cache | .next .svelte-kit .astro .output .expo dist build coverage storybook-static | | Rust / JVM | .gradle | target | | .NET | | obj | | Python | __pycache__ .pytest_cache .mypy_cache .ruff_cache .tox | | | Unity | Library Temp | | | Unreal | Intermediate DerivedDataCache | Binaries | | Xcode / iOS | | build next to *.xcodeproj, *.xcworkspace or Podfile (labelled xcode) | | Dart / Flutter | .dart_tool | build next to pubspec.yaml (labelled flutter) | | Zig | .zig-cache zig-cache | zig-out |

target, obj, Library, Temp, Intermediate, Binaries, .dart_tool and the Zig directories are gated on a project marker in the same directory — Cargo.toml, *.csproj, ProjectSettings + Assets, *.uproject, pubspec.yaml, build.zig. Without the marker they are never counted, never mind deleted. bin/ is excluded outright: too many repos keep real scripts there.

Shared stores — pnpm, npm, yarn, Go module + build cache, NuGet, pip (all safely prunable); Cargo registry, Gradle, Maven, Playwright and Puppeteer browsers, Xcode DerivedData, the Dart pub cache and Zig's global cache (surfaced, never auto-pruned, because re-downloading or rebuilding them is expensive or offline-hostile; each is offered only at tier 3, with its real cost stated). Bazel output bases are listed too but never offered at all: Bazel makes them read-only and tracks them per workspace, so reclaim them with bazel clean --expunge inside each one. The bazel-out/bazel-bin links in a workspace point into that output base; deleting them frees nothing, so chaff ignores them.

Dependencies — node_modules, counted once per install. Slow to measure, so it is opt-in via --full, kept in its own 24-hour cache so an ordinary scan never destroys it, and reported as not measured when absent rather than silently undercounting.

Worktrees — every git worktree, aged by last commit, with merged / dirty / locked / in-use state. Primary checkouts are never proposed for removal.

Projects are found by marker: nx.json, turbo.json, pnpm-workspace.yaml, lerna.json, rush.json, Cargo.toml, go.mod, *.sln, *.csproj, build.gradle, pom.xml, pyproject.toml, ProjectSettings, *.uproject, or plain .git.

What chaff doctor tells you

Not just what is big — what is wrong, and the command that fixes it:

• nx below 22.7, where every worktree duplicates the whole cache
• node_modules far larger than the pnpm store, meaning installs are not hardlinked
• the same Cargo target/ compiled into N sibling checkouts, when CARGO_TARGET_DIR would share one
• daemon count, worktree count, the largest regenerable artifact, oversized shared stores

Use it from any agent (MCP)

chaff speaks MCP over stdio, so anything that speaks the protocol — Codex, Cursor, Zed, Windsurf, Claude Code — gets the same tools. Install it once, point your client at it.

npm install -g @gulsahsarsilmaz/chaff

Codex — ~/.codex/config.toml:

[mcp_servers.chaff]
command = "chaff"
args = ["mcp"]

Claude Code — claude mcp add chaff -- chaff mcp, or the standard shape below in .mcp.json.

Cursor (~/.cursor/mcp.json), Zed, Windsurf and anything else taking the standard shape:

{
  "mcpServers": {
    "chaff": { "command": "chaff", "args": ["mcp"] }
  }
}

From a checkout instead of a global install, use "command": "node" and "args": ["/path/to/chaff/scripts/chaff.mjs", "mcp"].

| Tool | Does | Safe? | | --- | --- | --- | | chaff_status | Memory, disk, cache, output, stores, daemons, worktrees | read-only | | chaff_plan | What it would clean, by tier, with sizes | read-only | | chaff_doctor | What is misconfigured, and the fix for each | read-only | | chaff_worktrees | Every worktree, staleness, uncommitted work | read-only | | chaff_reap | Reclaim tier 1 only — provably dead | safe | | chaff_clean | Tier 1-2, to trash. Needs your OK — see below | recoverable |

A skill to go with it. skills/chaff/SKILL.md tells an agent when to reach for chaff — a full disk, ENOSPC, a swapping machine — and how to use it safely. The Claude Code plugin loads it for you; for other agents that read skills, copy the skills/chaff folder into their skills directory.

Tier 3 is not reachable over MCP. It touches running processes and uncommitted code, and a model deciding that on its own — possibly auto-approved — is not a tradeoff worth making. Tier 3 stays a person at a terminal: chaff clean --tier=3 --yes --force.

chaff_clean asks you, not the model. Its confirm: true argument is set by the model, so chaff does not treat it as consent:

• If your client supports MCP elicitation, chaff asks you directly, naming what it will remove. Decline, cancel or don't answer, and nothing runs.
• Otherwise it needs the planId that chaff_plan printed: proof the model fetched the plan it should have shown you. A planId lasts 10 minutes and works once. Without one, chaff_clean only dry-runs.
• Either way, chaff applies exactly the plan that was agreed to. If anything has been added or changed since, it refuses and asks for a fresh plan (chaff apply --expect does the check).

Deleted build output and caches go to the chaff trash, recoverable with chaff restore until the TTL expires; stopped processes, removed worktrees and pruned stores are not.

Install as a Claude Code plugin

/plugin marketplace add gulsahsarsilmaz/chaff
/plugin inst