English · Tiếng Việt

declutter — free up disk space on a dev machine

A disk cleanup CLI for developers on macOS and Ubuntu. It scans your machine, shows a checkbox list with real sizes, pre-ticks only what is provably safe, and deletes nothing until you press Enter.

CI status MIT license Platforms: macOS and Ubuntu Pure bash 3.2+
View on GitHub Manual cleanup guide

Why another cleaner?

Because the fastest-growing directories on a developer's machine today belong to AI coding tools, and nothing cleans them. Claude Code, Codex and Gemini CLI transcripts. The WebStorage behind AI chat panels in VS Code and Cursor — routinely 3 GB on its own. HuggingFace caches. Ollama weights measured in tens of gigabytes. apt clean and brew cleanup never touch a byte of it.

declutter covers those first, then everything else a dev machine accumulates: npm, Cargo, Gradle, Go, pip, Docker, browser caches, Xcode DerivedData.

Install

One command, same on Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/quytstudio/declutter/main/install.sh | bash

Installs into ~/.local/bin (override with PREFIX). No git on the machine? It falls back to a tarball. Prefer not to install at all — clone it and run ./declutter in place. To remove it: ./install.sh --uninstall.

What it looks like

declutter  —  linux  —  14.1G free on /
o = safe (pre-ticked)   ! = your call   x = manual only, not selectable
──────────────────────────────────────────────────────────────────────────
  [x] o     3.0G  Code: WebStorage (AI webview panels)           ai-ide
> [x] o     1.3G  npx cache                                      pkg-node
  [x] o     430M  Cargo registry cache (re-fetched on build)     pkg-rust
  [ ] !     250M  Claude Code: transcripts older than 60d (bre…  ai-cli
  [ ] !      42M  Code: Copilot Chat history                     ai-ide
    -  x     2.2G  Installed extensions (remove: code --uninst…   ai-ide
──────────────────────────────────────────────────────────────────────────
  Selected: 12 items — 1.8G
  [↑↓/jk] move   [space] toggle   [a] invert all   [o] safe only
  [n] clear   [enter] CLEAN   [q] quit

Three safety tiers

TierMeaningDefault
o safe Caches that provably regenerate. Losing them only makes the next build or install slower. Pre-ticked
! your call You lose history (transcripts, Copilot Chat), or a rebuild takes a long time (Gradle caches, Go modcache). Unticked, you turn it on
x manual only Real data, or something only you know you still need: node_modules, Ollama models, Docker volumes, Xcode Archives, the Maven repo. Not selectable. Size is shown so you can deal with it yourself

--level red is refused on purpose: no flag makes this tool delete a red item for you.

Usage

declutter                  # scan → pick → Enter. Deletes NOTHING by default.
declutter --report         # print the list and exit
declutter --json           # same list as JSON, for scripts and agents
declutter --yes            # skip the list, clean the safe tier
declutter --yes -l yellow  # include the "your call" tier
declutter --dry-run --yes  # rehearse: log what WOULD go, touch nothing
declutter --projects       # list heavy node_modules/target/.venv
declutter --only ai-ide    # clean IDE caches only
declutter --lang vi        # Vietnamese interface (auto-detected from $LANG)

What it never touches

~/.ssh · ~/.gnupg · ~/.aws · .env files · login tokens · ~/.claude/settings.json, skills, agents, memory · VS Code User/settings.json, keybindings.json, snippets, User/History · browser profiles (only cache directories are in scope) · Docker volumes · Xcode Archives · the Maven repo · Timeshift and Time Machine snapshots · node_modules and target/, which are listed but never removed.

JSON output, for scripts and AI agents

declutter --json prints the same list as one JSON object, so an agent can decide what to clean without driving the TUI:

declutter --json | jq -r '.items[] | select(.level=="green")
  | "\(.size_human)\t\(.desc)"' | head -5

Frequently asked questions

Is it safe to run?

It deletes nothing until you say so, and the pre-ticked tier is caches only. The tests assert that a default run leaves ~/.ssh, ~/.claude/settings.json, VS Code settings, workspaceStorage, the Maven repo and every transcript untouched. Run declutter --dry-run --yes first to read the exact list of paths.

Will it delete my Claude Code chat history?

Not at the default tier. Transcripts sit in the ! tier, are never pre-ticked, and only entries older than --days N (60 by default) are ever considered. Settings, skills, agents and memory are in the never-touch list.

How much space does it actually free?

On a working developer machine, typically 5–40 GB. The usual biggest wins are VS Code and Cursor caches, ~/.npm/_npx, the Cargo registry cache, Xcode DerivedData, and the Docker build cache. Run declutter --report to see your own numbers first.

Does it work on macOS?

Yes — macOS and Ubuntu/Debian, from the same script. It runs on the bash 3.2 that macOS ships, and CI exercises macos-latest with /bin/bash for that reason.

How is this different from CleanMyMac, BleachBit or brew cleanup?

Those clean the operating system. declutter cleans the developer toolchain, and in particular the AI tool directories none of them know about. It is also a small bash script with no daemon, no telemetry and no subscription — you can read everything it will ever delete before you run it.

Does it phone home?

No. There is no network call anywhere in the tool. install.sh is the only thing that downloads, and only from GitHub.

Documentation