How Wipecraft works

In daily use

Your work stays where it is

Rows that hold work in progress are locked. You can see them, but you cannot select them.

• While Claude Code or Codex runs: the sessions it has open, anything it changed in the last 24 hours, and the worktree it works in.
• Cursor's caches while Cursor is open.
• A worktree with uncommitted changes, one that changed in the last 7 days, or one whose commits are not on the main branch or a remote.
• A booted simulator.
• Claude Desktop's live sandbox image.

Nothing comes selected. "Select recommended" picks only items in "Safe to remove" and "Comes back", and never an item in "Your call".

Scanning only reads. A test compares every file under a test home before and after a full scan, and again after the command-line scan and status.

7 days to change your mind

Files that no app rebuilds go to Quarantine on the same disk when you remove them. Each row shows "days left" and a Restore button. After 7 days, Quarantine empties itself the next time Wipecraft opens or runs its daily check. If you need the space today, "Empty Now" frees it after a second confirmation.

Three kinds of action skip Quarantine.

• Caches, logs and temporary files that their app rebuilds on its own are removed directly. They cannot be restored, and the row or card says so before you confirm. Wipecraft does this only for folders and files that it knows an app recreates. Anything without a known rebuilder goes to Quarantine.
• Worktrees are removed with git; their branch stays in the repository.
• A few tool commands are marked "Irreversible", and Wipecraft names them and asks a second time.

Some caches stay in Quarantine because their tool does not get them back on its own: JetBrains and Android Studio caches (they also hold the IDE's Local History), Maven and Go modules, and tool data in Library/Caches such as Poetry environments, Playwright and Cypress browsers and llama.cpp models.

Session histories are not deleted. They move to a compressed Archive that you can restore.

It tells you when something grows

Monitoring is off until you turn it on. When it is on, a menu bar icon shows it, and Wipecraft checks once a day at the hour you choose. It notifies you when:

• one item grows by 2 GB or more in 7 days,
• less than 10% of the disk is free,
• a worktree or simulator of 1 GB or more has not been touched for 7 days,
• your last Time Machine backup is more than 7 days old.

Quit the app and everything stops.

Rules you set, and filters

Cleanup rules are optional. There are none until you add one in Settings > Automatic cleanup.

• A rule names the sources, how many days an item must have gone unused (7 to 365) and a minimum size.
• After the daily check, items that match a rule move to Quarantine or to the Archive, and a notification says how many.
• Rules skip locked rows. They never run a command, never remove a worktree and never do anything that cannot be undone. Caches that are removed directly are not part of scheduled cleanup; rules take only items that go to Quarantine or the Archive.
• Rules run only while monitoring is on.
• Without a license, a rule moves nothing. If a rule would have moved something, Wipecraft tells you once a day that cleanup did not run.

Every list of findings can be filtered by how long an item has gone untouched, by source and by safety level. A filter hides rows and takes them out of the selection.

Never touches unpushed work

A worktree whose git repository is still there is offered for removal only when its commits exist somewhere else too. The one exception is a worktree whose repository is gone; see the last point.

• Its commits must be on the main branch or on a remote branch. If they are not, the row is locked with the reason "Its commits are not on the main branch or a remote yet."
• Commits made after the last push keep it locked.
• A squash merge puts new commits on the main branch, so the branch's own commits never appear there. If GitHub lists the branch's pull request as merged, Wipecraft lifts that one lock. It asks through your own gh login, only when gh is installed and signed in, and you can switch it off in Settings > Privacy. Uncommitted changes still lock the worktree.
• Wipecraft checks again right before it removes a worktree. If the commits are no longer on the main branch or a remote, or the pull request no longer shows as merged, it removes nothing.
• A worktree whose main repository was moved or deleted cannot be checked by git. Wipecraft offers it only after 30 days without changes (the default), and moves the whole folder to Quarantine, where Restore brings it back.

Keeps your .env when it removes a worktree

git worktree remove deletes the folder, including files git ignores: .env, local databases and editor settings. Wipecraft moves those files out first.

• Before it removes a worktree, Wipecraft moves its ignored files that are not build output to Quarantine, for 7 days. Build output, such as node_modules and target, is deleted with the worktree.
• The row says how many files go to Quarantine before you confirm.
• If git refuses to remove the worktree, Wipecraft puts the files back where they were.
• Restore recreates the folders those files sat in.
• These files are never offered on their own. Build output is offered as a separate row, also for a worktree that is locked.

Works from the terminal and inside Claude Code

Command line. Wipecraft includes a wipecraft command inside the app. Settings > General > Command-line tool shows the one line that links it into your PATH.

• wipecraft scan and wipecraft status list what can be freed, and print versioned JSON with --json. They change nothing.
• wipecraft clean shows what it would do. Nothing changes until you add --apply.
• With --apply, wipecraft clean does for each item you name what the app does: caches, logs and temporary files that their app rebuilds are removed directly and cannot be restored (the plan says "Would remove directly"), other files move to Quarantine, session histories go to the Archive, and a finished worktree is removed with git worktree remove after its ignored files that are not build output move to Quarantine. The deletion log records each action. --all-safe picks only items that move to Quarantine. It needs the same license as the app.
• It refuses locked rows and rows that changed since the scan. It does not run actions marked "Irreversible"; it tells you to open the app.
• wipecraft quarantine list shows what is in Quarantine, and wipecraft quarantine restore <id> puts an entry back. Neither needs a license.
• If the app or another terminal is moving files, the command stops with a message that Wipecraft is busy, and moves nothing.
• It prints completion scripts for zsh, bash and fish.

Claude Code plugin. The plugin adds two commands and two session hooks.

• /wipecraft:status summarizes wipecraft scan --json. /wipecraft:tidy shows the dry run first and runs --apply only after you say yes in the chat.
• When a session starts and more than 1 GB can be freed, it adds one line to the session. The line comes from a summary saved at the last refresh, so a session never waits for a scan. Without a summary from the last 24 hours it prints nothing, and it refreshes the summary in the background.
• When a session ends inside a linked worktree, it prints that worktree's state in one line.
• Tidying a finished worktree is off by default. It is a switch in Settings > Agents.
• With the switch on, wipecraft clean runs in the background after a short delay once the session ends, for that session's worktree only. It goes through the same checks as the command, and a worktree that is still locked stays.

Other agents (MCP). wipecraft mcp is a server that Claude Code, Codex, Cursor and other agents can start on your Mac. It talks only over standard input and output; its source uses no network connection and listens on no port.

• An agent can read the totals, list and explain items, and see what is in Quarantine. These requests change nothing.
• Cleaning through an agent is off until you turn on "Allow agents to clean through MCP" in Settings > Agents.
• When it is on, a request shows the plan unless the agent asks to apply. Applying needs a license and skips locked rows. For each id the agent names it does what wipecraft clean --apply does: caches, logs and temporary files that their app rebuilds are removed directly and cannot be restored, other files move to Quarantine, session histories go to the Archive, and a finished worktree is removed with git. The tool description tells the agent which items cannot be restored, so it can say so before it applies. Actions marked "Irreversible", such as removing a Time Machine local snapshot, are still refused.
• Settings > Agents lists the setup text for Claude Code, Codex and Cursor. Wipecraft shows the text and does not change any agent's settings.

What it finds

Every row says what it is, how big it is and what happens if you remove it. Where something can come back, it also says how.

Claude Code, Codex, worktrees and the developer tools below appear when Developer mode is on. See the FAQ.

AI agents and AI apps

• Claude Code. Session histories, grouped by project and month. They are archived, not deleted. Also file history, shell snapshots, debug logs and plugins.
• Codex. Sessions, archived sessions, and the thread history and log databases. All of these are archived, not deleted. Also generated images and cache.
• Claude Desktop. VM bundles. The live sandbox image is shown and locked. Its compressed copies and leftover warm-start data are offered only while Claude Desktop is closed. Caches too.
• Cursor. Its caches.
• Local models. Ollama, LM Studio, the Hugging Face cache, the PyTorch cache and Whisper models, with size and last use.
• Git worktrees. From any agent, or from you: the worktrees of the git repositories in your home folder, and folders in .claude/worktrees. Each shows its branch, size, last change, and the files git ignores, listed separately. Worktrees are grouped by the tool that made them: Claude Code, Codex, Cursor or Other. The group comes from the folder or the branch name.
• Worktree leftovers. Folders whose main repository was moved or deleted are listed, and so are git's records of worktrees whose folders no longer exist. Removing the records runs git worktree prune, which deletes no files. A record whose folder was moved, not deleted, stays locked, and the row says to run git worktree repair.

Developer tools

• Xcode. Build data per project, archives, device support files, previews and the module cache. A project that Xcode has open is locked.
• Simulators. Each device with its size and last use. "Remove device" and "erase contents" are separate actions. Runtime images are offered only when no simulator uses them.
• Package caches. npm, pnpm, Yarn, pip, Homebrew, CocoaPods, Swift Package Manager, Gradle and Cargo, and also Bun, uv, conda, Go and Maven.
• Build output. node_modules in projects that have not changed for 30 days. Also folders such as .venv, target, .next, build, dist, Pods and .build, only when the project has its marker file (for example Cargo.toml or package.json), git ignores the folder, and the project has not changed for 30 days. You can change the 30 days. A coding agent or editor started in the project's folder locks it while it runs.
• Editors. Caches and logs of VS Code, the JetBrains IDEs and Android Studio. They are locked while that editor runs. A folder of an older IDE version says so.
• Android. Emulators (virtual devices) and SDK system images. An emulator moves to Quarantine and is locked while an emulator runs or its lock file exists. A system image is locked while a device uses it, and also when Wipecraft cannot read a device's settings.
• Docker. Images and volumes, while Docker is running. An image or volume that a container uses is locked. Also the build cache that no build uses now; removing it runs docker builder prune --all --force, which cannot be undone. OrbStack's data folder is shown with its size and Wipecraft does not remove it.

System Data

The Storage panel in System Settings shows one number for System Data. Wipecraft starts from the used space of the disk and splits every used byte into four parts: macOS, Apps, Your files and System Data. The parts add up to the used space.

System Data is split again into five buckets. Each one has a colour and a one-sentence explanation.

• Your Mac needs this. Swap, system databases and the data that apps keep for themselves. Shown, never offered for removal.
• Safe to remove. Caches, logs and temporary files that their app rebuilds on its own.
• Comes back. Removable, but it fills up again with use, such as browser and package caches.
• Your call. The only copy of something that does not come back by itself, such as local models, emulators, simulators, worktrees, Docker images and session histories. The card says what each one is and when you last used it. These go to Quarantine, where you can undo them for 7 days, or to the Archive, which you can restore.
• Not shown by macOS. What is left after everything Wipecraft can name, with a reason: Full Disk Access is off, folders only an administrator can read, or APFS overhead and clones.

The trash on a card removes only what is safe: items in Safe to remove and Comes back that are not locked. It never takes an item from Your call, and an item that an app has open stays locked. The card turns over first and says what will happen and whether it can be undone.

Time Machine local snapshots are listed one by one, with their dates, outside the buckets. macOS does not report the size of a local snapshot, so Wipecraft does not guess one. Removing a snapshot is marked "Irreversible" and asks for your administrator password each time.

Some of these folders need Full Disk Access. Without it, your user folders are still scanned, and the overview says which folders could not be counted.

How undo works

Caches that their tool does not get back on its own are not in the first row. They go to Quarantine: JetBrains and Android Studio caches, Maven and Go modules, and tool data in Library/Caches such as Poetry environments, Playwright and Cypress browsers and llama.cpp models.

The irreversible actions are: removing a Time Machine local snapshot, deleting a simulator runtime, erasing a simulator's contents, removing a Docker image or volume, and removing the Docker build cache.

Wipecraft offers a worktree whose repository is present for removal only when it is clean: no changed tracked files, no untracked files that git doesn't ignore, no changes for 7 days (the default; you can change it in Settings), and its commits on the main branch or a remote. A worktree whose main repository is gone cannot be checked by git. It is offered after 30 days without changes (the default) and goes to Quarantine as a whole folder. Its git-ignored files (build output, dependencies) are also a separate row, which goes to Quarantine. That row can be offered even when the worktree itself is locked, for example for uncommitted changes.

Quarantine moves files on the same disk, so space comes back when it empties. The Quarantine screen shows both numbers: "In quarantine" and "Frees if emptied now".

Every action is written to a local deletion log: when, what, how much, and which kind of action. You can export it as CSV from Settings.

Privacy in 10 principles

1. No account.
2. No telemetry and no analytics in the app.
3. Wipecraft sends no file name or path anywhere. A coding agent that you connect yourself receives scan results on your Mac, over a local connection. What that agent does with them is its own provider's matter.
4. The scan reads sizes, dates and tool status (git, simctl, Docker) on this Mac. It uploads nothing.
5. The app makes network calls for two things: your license, if you activate one (with your Mac's name as the activation label), and update checks. One optional check goes through your own gh login, only when gh is installed and signed in. You can switch it off in Settings, and then gh never runs.
6. Crash reports are off by default. If you turn them on, they go only when the app crashes, with no file names or paths (Sentry, EU region).
7. Nothing runs in the background unless you turn on monitoring, and its menu bar icon shows that it is on. The one other case is the Claude Code plugin, if you install it: its hooks run wipecraft when a session starts or ends.
8. No admin helper is installed. The administrator password is asked for only to remove a snapshot, each time. The wipecraft command runs with your own rights and does not run administrator commands.
9. The deletion log stays on your Mac. You export it yourself.
10. Your license key is kept in your Keychain. The wipecraft command reads it from there to check the license.

Full details: wipecraft.app/privacy