Stow

A careful reset for the projects you are not using today.

Stow reviews regenerable developer artifacts and helps you reclaim space with intention. It is deliberately not a one-command “clean everything” tool: it shows what it found, asks about each folder, and asks once more before it removes anything. It works on macOS, Windows, and Linux.

Install

npm install --global stow-cli
stow clean

Or run it once without installing:

npx stow-cli clean

With no path, Stow looks through your home directory. Supply a path when you want a narrower review:

stow scan ~/Documents
stow clean ~/monorepo
stow clean ~/monorepo --dry-run

The Stow approach

Stow is designed around a simple principle: disk cleanup should feel reversible in your head, even when it is not reversible on disk.

• Review every artifact. In normal clean mode, answer y or n for each individual folder—not an entire project.
• One final decision. Nothing is removed until a final confirmation names the number of selected items and total space.
• Respect shared tools. Home-level tool folders are not scanned, listed, or removed. Project-local artifacts still are.
• Protect source. Git-tracked folders are excluded, and ambiguous generic names such as dist, build, and vendor are never cleanup candidates.
• Stay inside the boundary. Stow does not follow symbolic links, revalidates every path component before removal, and refuses deletion outside the directory that was scanned.
• Be honest about scope. Missing paths are errors, never an empty “clean” result. JSON mode never prompts or emits terminal decoration.
• Keep the screen quiet. The dashboard answers the only questions that matter: where, what, how much, and when it was last touched.

What Stow can review

Stow recognizes folders that development tools can recreate:

| Kind | Examples | | --- | --- | | Dependencies | node_modules, .venv, Pods | | Build output | .next, .nuxt, .svelte-kit, DerivedData | | Project caches | .turbo, .vite, .parcel-cache, __pycache__ | | Test output | .nyc_output, storybook-static | | IDE data | .idea, .vscode, .cursor with --ide |

Stow does not intentionally target source files, lockfiles, project manifests, Git data, or home-level tool folders.

Commands

stow scan [path]                 Inspect without deleting
stow clean [path]                Review artifacts one at a time
stow clean [path] --all          Select all found artifacts, then confirm once

Filters and automation

-s, --min-size <size>    Minimum size, such as 100m or 1g (default: 1m)
-d, --depth <number>     Maximum directory depth (default: 6)
    --category <list>    deps, build, cache, test, ide
    --older-than <age>   12h, 30d, 2w, 6m, 1y
    --ide                Include IDE folders
    --dry-run            Preview selected removal
    --json               Stable machine-readable scan output

Stow always requires an interactive confirmation before deletion.

Development

npm run check
npm test
npm run build

Requirements

• Node.js 22 or later
• A modern terminal: Terminal, iTerm, PowerShell, Windows Terminal, or an IDE terminal
• TypeScript 7 is included as a development dependency for contributors

License

MIT