sweep

Recursively find and delete regenerable dev artifacts to reclaim disk space.

sweep walks a directory, finds the folders that install and build steps regenerate anyway (node_modules, .next, .venv, dist, framework caches, and more), and opens an interactive tree grouped by project so you can pick exactly what to delete, with a live running total.

Everything regenerable starts selected; build output (dist/build/out) starts off. Toggle a project to select all its artifacts, or drill in and pick individual folders. Press enter to delete only what is checked.

Why

I built this late one night when my laptop ran out of space and I was too tired to hunt down every node_modules by hand. I wanted one command that finds the junk, shows me what is big, and clears it fast. That is all sweep is: a quick way to get your disk back.

Install

Run it once (no install)

Point it at a folder and it cleans up after itself — nothing left on your machine.

npx @crafter-station/sweep ~/code     # npm
pnpm dlx @crafter-station/sweep ~/code # pnpm
bunx @crafter-station/sweep ~/code    # bun
yarn dlx @crafter-station/sweep ~/code # yarn

Install it globally

Get the sweep command everywhere. Pick your package manager:

npm  install -g @crafter-station/sweep
pnpm add    -g @crafter-station/sweep
bun  add    -g @crafter-station/sweep
yarn global add @crafter-station/sweep

Install with your AI agent 🤖

Using Claude Code, Cursor, or another coding agent? Paste this and let it do the work:

Install the "sweep" CLI globally from npm (package: @crafter-station/sweep).
Detect my package manager (npm / pnpm / bun / yarn) and use it. After installing,
run `sweep --help` to confirm it works, then show me `sweep -n .` (a dry run that
deletes nothing) so I can see what it would reclaim in this directory.

Want it to actually free space right away? Follow up with:

Run `sweep ~/code` and walk me through the interactive tree so I can pick what to delete.

Usage

sweep [path] [options]

path defaults to the current directory. In a terminal, sweep opens the interactive tree by default; --yes deletes everything found with no prompt, and --no-interactive falls back to a flat list plus a single confirmation.

Options

| Flag | Description | |------|-------------| | -n, --dry-run | List what would be deleted, delete nothing | | -y, --yes | Delete everything found without prompting | | -s, --skip <name> | Skip a category (repeatable, comma-separated) | | --only <name> | Only these categories (repeatable, comma-separated) | | --no-build-output | Keep dist / build / out / coverage folders | | --no-interactive | Skip the tree selector, list and confirm instead | | --min-size <mb> | Only include folders at least this many MB | | --json | Machine-readable output (default when piped) | | -q, --quiet | Suppress progress output | | -v, --version | Print version | | -h, --help | Show help |

Keys (interactive mode)

| Key | Action | |-----|--------| | ↑ / ↓ (or k / j) | Move | | space | Toggle the row (a project toggles all its artifacts) | | → / ← (or l / h) | Expand / collapse a project | | a | Toggle everything | | enter | Delete what is selected | | q / esc | Cancel, delete nothing |

Examples

sweep                      # interactive tree for the current directory
sweep ~/code               # pick what to delete from a project tree
sweep -n ~/code            # dry run, delete nothing
sweep -y ~/code/project    # delete everything found, no prompts
sweep --no-interactive .   # flat list + single confirmation
sweep --no-build-output .  # keep dist/build/out, clean everything else
sweep --only node_modules  # only sweep node_modules
sweep --min-size 100 ~/code   # only folders >= 100 MB
sweep --json ~/code        # JSON output for scripts and agents
sweep categories           # list the categories sweep knows about

What it deletes

Run sweep categories for the live list. There are three groups:

Always deleted — install and build caches that are always regenerable: node_modules, .next, .turbo, .nuxt, .svelte-kit, .output, .astro, .docusaurus, .angular, .expo, .vite, .parcel-cache, .wrangler, .cache, __pycache__, .pytest_cache, .mypy_cache, .ruff_cache, .gradle, DerivedData.

Build output — deleted by default, kept with --no-build-output: dist, build, out, coverage. These are almost always regenerable, but a few projects commit source or store extracted assets under these names, so they are printed in yellow and easy to exclude.

Guarded — names that also occur as real source folders, deleted only when a marker file next to them proves what they are:

| Folder | Deleted only when | |--------|-------------------| | venv / .venv | it contains pyvenv.cfg | | target | there is a Cargo.toml next to it | | Pods | there is a Podfile next to it |

Safety

• .git directories are never touched, and matched folders are never descended into.
• Without --yes, sweep lists everything and waits for confirmation.
• In JSON or non-interactive mode, sweep refuses to delete unless --yes is passed, so it never hangs waiting for input.
• It refuses --yes when pointed at / or your home directory. Review the list first in those cases.

Deletion is still irreversible. Use --dry-run first when in doubt.

JSON output

--json (also the default when stdout is not a terminal) prints a single object. Preview:

{
  "root": "/Users/you/code",
  "dryRun": false,
  "totalBytes": 5691904000,
  "count": 3,
  "items": [
    { "path": "/Users/you/code/app/node_modules", "name": "node_modules", "group": "cache", "bytes": 4724464025 }
  ]
}

After deletion:

{ "root": "/Users/you/code", "dryRun": false, "freedBytes": 5691904000, "deleted": 3, "failed": 0, "failures": [] }

Development

bun run dev -- -n ~/code    # run from source
bun run build               # bundle to dist/ with tsup
bun run typecheck           # tsc --noEmit
bun run lint                # biome check

License

MIT