Claude Cleaner is an interactive terminal UI — built with Bubble Tea and Lip Gloss — that inspects Claude Code project session history, displays disk usage, and safely deletes only the sessions you select.
Runs on Windows, macOS, and Linux. No runtime required when using a pre-built binary.
See SCREENSHOTS.md for all scenario walkthroughs.
npx claude-cleanernpm install --global claude-cleaner
claude-cleanerThe npm package is a thin wrapper. On install it automatically downloads the correct pre-built binary for your platform from GitHub Releases. No Go required.
Go to Releases, download the archive for your platform, extract, and run.
| Platform | File |
|---|---|
| Linux x64 | claude-cleaner_*_linux_amd64.tar.gz |
| Linux ARM64 | claude-cleaner_*_linux_arm64.tar.gz |
| macOS x64 | claude-cleaner_*_darwin_amd64.tar.gz |
| macOS Apple Silicon | claude-cleaner_*_darwin_arm64.tar.gz |
| Windows x64 | claude-cleaner_*_windows_amd64.zip |
| Windows ARM64 | claude-cleaner_*_windows_arm64.zip |
go install github.com/ePlus-DEV/claude-cleaner@latestclaude-cleaner
claude-cleaner --claude-dir "/path/to/.claude"
claude-cleaner --help
claude-cleaner --version--claude-dir <path> Custom Claude config directory (default: ~/.claude)
--mock-update Simulate a newer version available (for testing the update flow)
-h, --help Show help
-v, --version Show version
| Key | Action |
|---|---|
↑ / ↓ or j / k |
Navigate list |
space |
Toggle selection |
enter |
Proceed — show delete confirm (when items selected) |
a |
Select all / deselect all |
p |
Purge selected (confirm screen, purge mode) |
x |
Force-purge item at cursor — no confirm |
r |
Rescan / refresh project list |
u |
Update claude-cleaner in-place (shown when update available) |
esc |
Go back / cancel |
q / ctrl+c |
Quit (works on every screen) |
- Reads project list from
~/.claude.json— shows all projects Claude Code knows about, even those with no local session files. - Displays token usage per project — reads
lastTotal*fields from~/.claude.jsonwhen available, otherwise aggregatesmessage.usagefrom session.jsonlfiles. Formatted as K / M / B / T / P / E. - Status column
●(session files on disk) /○(config only, no local data). - Windows path dedup —
d:/fooandD:/footreated as the same project; higher-token entry wins. - Multi-select with
space, select all witha, confirm withenter. - Three deletion modes: session-files delete, full purge (via
claude project purge), and instant force-purge (x). - Live progress bar during deletion.
- Claude CLI integration — tries
claude project purgefirst, falls back to direct removal. - Auto update check against npm registry on startup;
uto update in-place. - Claude CLI presence and version shown in header.
rto rescan at any time.qquits from every screen.- Rejects paths outside the Claude
projectsdirectory. - Concurrent filesystem scanning.
- Supports custom Claude configuration directories via
--claude-dirorCLAUDE_CONFIG_DIR.
Only project session folders directly inside ~/.claude/projects (or $CLAUDE_CONFIG_DIR/projects).
These folders contain Claude Code session and conversation history. Source code directories are never touched.
| Mode | Key | Confirm | Scope | How |
|---|---|---|---|---|
| Delete | enter |
✓ screen | selected items | tries claude project purge -y <path>, falls back to os.RemoveAll |
| Purge | p |
✓ screen | selected items | same as delete, confirm text emphasises full purge |
| Force-purge | x |
✗ | cursor item only | same deletion chain, no confirm screen |
| Delete all | a then enter |
✓ screen | all items | uses claude project purge --all -y (single call), then cleans remaining folders |
All modes validate that the target path is inside the Claude projects directory before deleting.
Priority order: --claude-dir > CLAUDE_CONFIG_DIR > ~/.claude
# macOS / Linux
export CLAUDE_CONFIG_DIR="/mnt/data/claude"
claude-cleaner# Windows PowerShell
$env:CLAUDE_CONFIG_DIR = "D:\ClaudeData"
claude-cleanerClaude directory not found — Run Claude Code at least once so the directory is created, or point to the correct path:
claude-cleaner --claude-dir "/correct/path/.claude"Permission denied — Run as the same OS user that owns the Claude config directory.
Binary not found after npx — Try reinstalling:
npm install --global claude-cleanerWindows: Access is denied when running go run . — Windows locks the temp executable while it's in use. Kill any other running instances, or build once and run the binary directly:
go build -o claude-cleaner.exe .
.\claude-cleaner.exeSee CONTRIBUTING.md for setup, build, test, and release instructions. For internal data flow diagrams see ARCHITECTURE.md.
MIT © ePlus.DEV