claude-cleaner 1.0.0 → 1.1.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 +41 -118
  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
@@ -135,6 +85,41 @@ claude-cleaner --version
135
85
  | `esc` | Go back / cancel |
136
86
  | `q` / `ctrl+c` | Quit (works on every screen) |
137
87
 
88
+ ## Features
89
+
90
+ - Reads project list from `~/.claude.json` — shows all projects Claude Code knows about, even those with no local session files.
91
+ - 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.
92
+ - Status column `●` (session files on disk) / `○` (config only, no local data).
93
+ - Windows path dedup — `d:/foo` and `D:/foo` treated as the same project; higher-token entry wins.
94
+ - Multi-select with `space`, select all with `a`, confirm with `enter`.
95
+ - Three deletion modes: session-files delete, full **purge** (via `claude project purge`), and instant **force-purge** (`x`).
96
+ - Live progress bar during deletion.
97
+ - Claude CLI integration — tries `claude project purge` first, falls back to direct removal.
98
+ - Auto update check against npm registry on startup; `u` to update in-place.
99
+ - Claude CLI presence and version shown in header.
100
+ - `r` to rescan at any time.
101
+ - `q` quits from every screen.
102
+ - Rejects paths outside the Claude `projects` directory.
103
+ - Concurrent filesystem scanning.
104
+ - Supports custom Claude configuration directories via `--claude-dir` or `CLAUDE_CONFIG_DIR`.
105
+
106
+ ## What it deletes
107
+
108
+ Only project session folders directly inside `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR/projects`).
109
+
110
+ These folders contain Claude Code session and conversation history. Source code directories are never touched.
111
+
112
+ ### Deletion modes
113
+
114
+ | Mode | Key | Confirm | Scope | How |
115
+ | --- | --- | --- | --- | --- |
116
+ | Delete | `enter` | ✓ screen | selected items | tries `claude project purge -y <path>`, falls back to `os.RemoveAll` |
117
+ | Purge | `p` | ✓ screen | selected items | same as delete, confirm text emphasises full purge |
118
+ | Force-purge | `x` | ✗ | cursor item only | same deletion chain, no confirm screen |
119
+ | Delete all | `a` then `enter` | ✓ screen | all items | uses `claude project purge --all -y` (single call), then cleans remaining folders |
120
+
121
+ All modes validate that the target path is inside the Claude projects directory before deleting.
122
+
138
123
  ## Configure a custom Claude directory
139
124
 
140
125
  Priority order: `--claude-dir` > `CLAUDE_CONFIG_DIR` > `~/.claude`
@@ -174,71 +159,9 @@ go build -o claude-cleaner.exe .
174
159
  .\claude-cleaner.exe
175
160
  ```
176
161
 
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
162
  ## Contributing
240
163
 
241
- See [CONTRIBUTING.md](CONTRIBUTING.md).
164
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, build, test, and release instructions. For internal data flow diagrams see [ARCHITECTURE.md](ARCHITECTURE.md).
242
165
 
243
166
  ## License
244
167
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-cleaner",
3
- "version": "1.0.0",
3
+ "version": "1.1.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"