claude-cleaner 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +59 -122
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -6,6 +6,7 @@
6
6
  [![Go version](https://img.shields.io/github/go-mod/go-version/ePlus-DEV/claude-cleaner)](go.mod)
7
7
  [![Go Report Card](https://goreportcard.com/badge/github.com/ePlus-DEV/claude-cleaner)](https://goreportcard.com/report/github.com/ePlus-DEV/claude-cleaner)
8
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
9
+ [![Known Vulnerabilities](https://snyk.io/test/github/ePlus-DEV/claude-cleaner/badge.svg)](https://snyk.io/test/github/ePlus-DEV/claude-cleaner)
9
10
 
10
11
  **Claude Cleaner** is an interactive terminal UI — built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) and [Lip Gloss](https://github.com/charmbracelet/lipgloss) — that inspects Claude Code project session history, displays disk usage, and safely deletes only the sessions you select.
11
12
 
@@ -13,49 +14,7 @@ Runs on Windows, macOS, and Linux. No runtime required when using a pre-built bi
13
14
 
14
15
  ![Full demo](demo/full.gif)
15
16
 
16
- ## Demos
17
-
18
- | Scenario | Preview |
19
- | --- | --- |
20
- | `--help` | ![Help](demo/help.gif) |
21
- | Delete a session | ![Full flow](demo/full.gif) |
22
- | Cancel confirmation | ![Cancel](demo/cancel.gif) |
23
- | In-place update | ![Update](demo/update.gif) |
24
-
25
- ## Features
26
-
27
- - Reads project list from `~/.claude.json` — shows all projects Claude Code knows about, even those with no local session files.
28
- - Displays **token usage** per project (from `lastTotal*` fields in `~/.claude.json`), formatted as K / M / B / T / P / E.
29
- - Status column `●` (session files on disk) / `○` (config only, no local data).
30
- - Windows path dedup — `d:/foo` and `D:/foo` treated as the same project; higher-token entry wins.
31
- - Multi-select with `space`, select all with `a`, confirm with `enter`.
32
- - Three deletion modes: session-files delete, full **purge** (via `claude project purge`), and instant **force-purge** (`x`).
33
- - Live progress bar during deletion.
34
- - Claude CLI integration — tries `claude project purge` first, falls back to direct removal.
35
- - Auto update check against npm registry on startup; `u` to update in-place.
36
- - Claude CLI presence and version shown in header.
37
- - `r` to rescan at any time.
38
- - `q` quits from every screen.
39
- - Rejects paths outside the Claude `projects` directory.
40
- - Concurrent filesystem scanning.
41
- - Supports custom Claude configuration directories via `--claude-dir` or `CLAUDE_CONFIG_DIR`.
42
-
43
- ## What it deletes
44
-
45
- Only project session folders directly inside `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR/projects`).
46
-
47
- These folders contain Claude Code session and conversation history. Source code directories are never touched.
48
-
49
- ### Deletion modes
50
-
51
- | Mode | Key | Confirm | Scope | How |
52
- | --- | --- | --- | --- | --- |
53
- | Delete | `enter` | ✓ screen | selected items | tries `claude project purge -y <path>`, falls back to `os.RemoveAll` |
54
- | Purge | `p` | ✓ screen | selected items | same as delete, confirm text emphasises full purge |
55
- | Force-purge | `x` | ✗ | cursor item only | same deletion chain, no confirm screen |
56
- | Delete all | `a` then `enter` | ✓ screen | all items | uses `claude project purge --all -y` (single call), then cleans remaining folders |
57
-
58
- All modes validate that the target path is inside the Claude projects directory before deleting.
17
+ > See [SCREENSHOTS.md](SCREENSHOTS.md) for all scenario walkthroughs.
59
18
 
60
19
  ## Install
61
20
 
@@ -65,7 +24,7 @@ All modes validate that the target path is inside the Claude projects directory
65
24
  npx claude-cleaner
66
25
  ```
67
26
 
68
- ### Install globally
27
+ ### npm (global)
69
28
 
70
29
  ```bash
71
30
  npm install --global claude-cleaner
@@ -74,7 +33,7 @@ claude-cleaner
74
33
 
75
34
  > The 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.
76
35
 
77
- ### Download binary directly
36
+ ### Download binary
78
37
 
79
38
  Go to [Releases](https://github.com/ePlus-DEV/claude-cleaner/releases), download the archive for your platform, extract, and run.
80
39
 
@@ -87,21 +46,12 @@ Go to [Releases](https://github.com/ePlus-DEV/claude-cleaner/releases), download
87
46
  | Windows x64 | `claude-cleaner_*_windows_amd64.zip` |
88
47
  | Windows ARM64 | `claude-cleaner_*_windows_arm64.zip` |
89
48
 
90
- ### Install with Go
49
+ ### Go
91
50
 
92
51
  ```bash
93
52
  go install github.com/ePlus-DEV/claude-cleaner@latest
94
53
  ```
95
54
 
96
- ### Build from source
97
-
98
- ```bash
99
- git clone https://github.com/ePlus-DEV/claude-cleaner.git
100
- cd claude-cleaner
101
- go build -o claude-cleaner .
102
- ./claude-cleaner
103
- ```
104
-
105
55
  ## Usage
106
56
 
107
57
  ```bash
@@ -115,6 +65,7 @@ claude-cleaner --version
115
65
 
116
66
  ```text
117
67
  --claude-dir <path> Custom Claude config directory (default: ~/.claude)
68
+ --dry-run Preview deletions without modifying any files
118
69
  --mock-update Simulate a newer version available (for testing the update flow)
119
70
  -h, --help Show help
120
71
  -v, --version Show version
@@ -125,16 +76,64 @@ claude-cleaner --version
125
76
  | Key | Action |
126
77
  | --- | --- |
127
78
  | `↑` / `↓` or `j` / `k` | Navigate list |
79
+ | `g` / `G` | Jump to top / bottom |
128
80
  | `space` | Toggle selection |
129
- | `enter` | Proceed — show delete confirm (when items selected) |
130
- | `a` | Select all / deselect all |
131
- | `p` | Purge selected (confirm screen, purge mode) |
81
+ | `a` | Select / deselect all visible items |
82
+ | `n` | Unselect all |
83
+ | `o` | Select orphaned projects only |
84
+ | `enter` | Delete selected session-history directories (confirm screen) |
85
+ | `p` | Full purge selected projects through Claude CLI when available |
132
86
  | `x` | Force-purge item at cursor — no confirm |
87
+ | `s` | Cycle sort: recent / size / tokens / name |
88
+ | `f` | Cycle filter: all / has data / orphaned |
89
+ | `e` | Cycle expiry filter: off / 7 / 14 / 30 / 60 / 90 days |
90
+ | `/` | Search by project name or path |
91
+ | `c` | Open category cleanup |
133
92
  | `r` | Rescan / refresh project list |
134
93
  | `u` | Update claude-cleaner in-place (shown when update available) |
135
- | `esc` | Go back / cancel |
94
+ | `?` | Show key bindings |
95
+ | `esc` | Go back / clear search and filters / cancel |
136
96
  | `q` / `ctrl+c` | Quit (works on every screen) |
137
97
 
98
+ ## Features
99
+
100
+ - Reads project list from `~/.claude.json` — shows all projects Claude Code knows about, even those with no local session files.
101
+ - Displays **token usage** per project — reads `lastTotal*` fields from `~/.claude.json` when available, otherwise aggregates `message.usage` from session `.jsonl` files. Formatted as K / M / B / T / P / E.
102
+ - Status column `●` (session files on disk) / `○` (config only, no local data).
103
+ - Windows path dedup — `d:/foo` and `D:/foo` treated as the same project; higher-token entry wins.
104
+ - Multi-select with `space`, select all with `a`, confirm with `enter`.
105
+ - Separate deletion backends: normal **Delete** removes only the selected Claude session-history directory; **Purge** uses `claude project purge` when available and falls back to session-directory removal.
106
+ - `--dry-run` previews exactly which projects/categories would be cleaned without touching files.
107
+ - Search, sort, orphan filters, and age/expiry filters for large project lists.
108
+ - Category cleanup for disposable Claude data such as debug logs, telemetry, history, backups, and plugin **cache** while preserving plugin installation state.
109
+ - Live progress bar during deletion.
110
+ - Claude CLI integration is used only for explicit purge operations.
111
+ - Auto update check against npm registry on startup; `u` to update in-place.
112
+ - Claude CLI presence and version shown in header.
113
+ - `r` to rescan at any time.
114
+ - `q` quits from every screen.
115
+ - Rejects paths outside the Claude `projects` directory.
116
+ - Concurrent filesystem scanning.
117
+ - Supports custom Claude configuration directories via `--claude-dir` or `CLAUDE_CONFIG_DIR`.
118
+
119
+ ## What it deletes
120
+
121
+ Only project session folders directly inside `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR/projects`).
122
+
123
+ These folders contain Claude Code session and conversation history. Source code directories are never touched.
124
+
125
+ ### Deletion modes
126
+
127
+ | Mode | Key | Confirm | Scope | How |
128
+ | --- | --- | --- | --- | --- |
129
+ | Delete | `enter` | ✓ screen | selected items | removes only the matching directory under `~/.claude/projects`; never invokes `claude project purge` |
130
+ | Purge | `p` | ✓ screen | selected items | runs `claude project purge -y <path>` when available; falls back to the matching session directory |
131
+ | Force-purge | `x` | ✗ | cursor item only | same purge chain as `p`, without a confirm screen |
132
+ | Delete all | `a` then `enter` | ✓ screen | all visible/selected items | deletes selected session directories individually; does not call `purge --all` |
133
+ | Purge all | `a` then `p` | ✓ screen | all projects | may use `claude project purge --all -y` for efficiency |
134
+
135
+ All modes validate that the target path is inside the Claude projects directory before deleting.
136
+
138
137
  ## Configure a custom Claude directory
139
138
 
140
139
  Priority order: `--claude-dir` > `CLAUDE_CONFIG_DIR` > `~/.claude`
@@ -174,71 +173,9 @@ go build -o claude-cleaner.exe .
174
173
  .\claude-cleaner.exe
175
174
  ```
176
175
 
177
- ## Development
178
-
179
- See [CONTRIBUTING.md](CONTRIBUTING.md) for full setup, build, and release instructions.
180
-
181
- ### Requirements
182
-
183
- - [Go 1.22+](https://go.dev/dl/)
184
- - [Node.js 20+](https://nodejs.org/) (only for seed data / demo GIFs)
185
-
186
- ### Quick start
187
-
188
- ```bash
189
- git clone https://github.com/ePlus-DEV/claude-cleaner.git
190
- cd claude-cleaner
191
- go mod tidy
192
- ```
193
-
194
- ### Run in dev (without installing Claude)
195
-
196
- Use the included seed script to create fake session data for testing:
197
-
198
- ```bash
199
- # macOS / Linux
200
- node demo/seed.js /tmp/claude-demo
201
- go run . --claude-dir /tmp/claude-demo
202
- ```
203
-
204
- ```powershell
205
- # Windows
206
- node demo/seed.js $env:TEMP\claude-demo
207
- go run . --claude-dir $env:TEMP\claude-demo
208
- ```
209
-
210
- This creates 5 fake project sessions of various sizes — enough to test all TUI flows (navigate, select, delete, cancel) without touching any real Claude data.
211
-
212
- ### Common commands
213
-
214
- ```bash
215
- go mod tidy # install / tidy dependencies
216
- go build -o claude-cleaner . # build binary
217
- go run . # run without building
218
- go test -v ./... # run tests
219
- go run . --version # smoke test
220
- ```
221
-
222
- ## CI / CD
223
-
224
- | Workflow | Trigger | What it does |
225
- | --- | --- | --- |
226
- | [ci.yml](.github/workflows/ci.yml) | push / PR | Go tests on 1.22, 1.23, 1.24 × Windows, macOS, Linux |
227
- | [release.yml](.github/workflows/release.yml) | push `v*` tag | GoReleaser builds binaries → GitHub Release → npm publish |
228
- | [demo.yml](.github/workflows/demo.yml) | push to main (Go / tape files) | Regenerates demo GIFs via VHS |
229
-
230
- ### Publishing a release
231
-
232
- ```bash
233
- npm version patch # or minor / major
234
- git push --follow-tags
235
- ```
236
-
237
- `npm version` automatically syncs the version to `main.go` and creates a git tag. Pushing the tag triggers GoReleaser and npm publish.
238
-
239
176
  ## Contributing
240
177
 
241
- See [CONTRIBUTING.md](CONTRIBUTING.md).
178
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, build, test, and release instructions. For internal data flow diagrams see [ARCHITECTURE.md](ARCHITECTURE.md).
242
179
 
243
180
  ## License
244
181
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-cleaner",
3
- "version": "1.0.0",
3
+ "version": "1.2.0",
4
4
  "description": "Safely inspect and delete selected Claude Code project session history from an interactive cross-platform TUI.",
5
5
  "bin": {
6
6
  "claude-cleaner": "scripts/run.js"