@asifkibria/claude-code-toolkit 1.0.7 → 1.3.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 (79) hide show
  1. package/README.md +172 -475
  2. package/dist/CLAUDE.md +7 -0
  3. package/dist/__tests__/dashboard.test.d.ts +2 -0
  4. package/dist/__tests__/dashboard.test.d.ts.map +1 -0
  5. package/dist/__tests__/dashboard.test.js +606 -0
  6. package/dist/__tests__/dashboard.test.js.map +1 -0
  7. package/dist/__tests__/mcp-validator.test.d.ts +2 -0
  8. package/dist/__tests__/mcp-validator.test.d.ts.map +1 -0
  9. package/dist/__tests__/mcp-validator.test.js +217 -0
  10. package/dist/__tests__/mcp-validator.test.js.map +1 -0
  11. package/dist/__tests__/security.test.d.ts +2 -0
  12. package/dist/__tests__/security.test.d.ts.map +1 -0
  13. package/dist/__tests__/security.test.js +375 -0
  14. package/dist/__tests__/security.test.js.map +1 -0
  15. package/dist/__tests__/session-recovery.test.d.ts +2 -0
  16. package/dist/__tests__/session-recovery.test.d.ts.map +1 -0
  17. package/dist/__tests__/session-recovery.test.js +230 -0
  18. package/dist/__tests__/session-recovery.test.js.map +1 -0
  19. package/dist/__tests__/storage.test.d.ts +2 -0
  20. package/dist/__tests__/storage.test.d.ts.map +1 -0
  21. package/dist/__tests__/storage.test.js +241 -0
  22. package/dist/__tests__/storage.test.js.map +1 -0
  23. package/dist/__tests__/trace.test.d.ts +2 -0
  24. package/dist/__tests__/trace.test.d.ts.map +1 -0
  25. package/dist/__tests__/trace.test.js +376 -0
  26. package/dist/__tests__/trace.test.js.map +1 -0
  27. package/dist/cli.js +680 -39
  28. package/dist/cli.js.map +1 -1
  29. package/dist/index.js +674 -2
  30. package/dist/index.js.map +1 -1
  31. package/dist/lib/alerts.d.ts +38 -0
  32. package/dist/lib/alerts.d.ts.map +1 -0
  33. package/dist/lib/alerts.js +296 -0
  34. package/dist/lib/alerts.js.map +1 -0
  35. package/dist/lib/dashboard-ui.d.ts +2 -0
  36. package/dist/lib/dashboard-ui.d.ts.map +1 -0
  37. package/dist/lib/dashboard-ui.js +2267 -0
  38. package/dist/lib/dashboard-ui.js.map +1 -0
  39. package/dist/lib/dashboard.d.ts +16 -0
  40. package/dist/lib/dashboard.d.ts.map +1 -0
  41. package/dist/lib/dashboard.js +1571 -0
  42. package/dist/lib/dashboard.js.map +1 -0
  43. package/dist/lib/git.d.ts +29 -0
  44. package/dist/lib/git.d.ts.map +1 -0
  45. package/dist/lib/git.js +124 -0
  46. package/dist/lib/git.js.map +1 -0
  47. package/dist/lib/logs.d.ts +42 -0
  48. package/dist/lib/logs.d.ts.map +1 -0
  49. package/dist/lib/logs.js +166 -0
  50. package/dist/lib/logs.js.map +1 -0
  51. package/dist/lib/mcp-validator.d.ts +109 -0
  52. package/dist/lib/mcp-validator.d.ts.map +1 -0
  53. package/dist/lib/mcp-validator.js +601 -0
  54. package/dist/lib/mcp-validator.js.map +1 -0
  55. package/dist/lib/scanner.d.ts +6 -2
  56. package/dist/lib/scanner.d.ts.map +1 -1
  57. package/dist/lib/scanner.js +120 -19
  58. package/dist/lib/scanner.js.map +1 -1
  59. package/dist/lib/search.d.ts +56 -0
  60. package/dist/lib/search.d.ts.map +1 -0
  61. package/dist/lib/search.js +284 -0
  62. package/dist/lib/search.js.map +1 -0
  63. package/dist/lib/security.d.ts +96 -0
  64. package/dist/lib/security.d.ts.map +1 -0
  65. package/dist/lib/security.js +795 -0
  66. package/dist/lib/security.js.map +1 -0
  67. package/dist/lib/session-recovery.d.ts +60 -0
  68. package/dist/lib/session-recovery.d.ts.map +1 -0
  69. package/dist/lib/session-recovery.js +433 -0
  70. package/dist/lib/session-recovery.js.map +1 -0
  71. package/dist/lib/storage.d.ts +68 -0
  72. package/dist/lib/storage.d.ts.map +1 -0
  73. package/dist/lib/storage.js +503 -0
  74. package/dist/lib/storage.js.map +1 -0
  75. package/dist/lib/trace.d.ts +119 -0
  76. package/dist/lib/trace.d.ts.map +1 -0
  77. package/dist/lib/trace.js +649 -0
  78. package/dist/lib/trace.js.map +1 -0
  79. package/package.json +11 -3
package/README.md CHANGED
@@ -1,589 +1,286 @@
1
1
  # Claude Code Toolkit
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/@asifkibria/claude-code-toolkit.svg)](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@asifkibria/claude-code-toolkit.svg)](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit)
4
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
- [![Tests](https://img.shields.io/badge/tests-70%20passing-brightgreen)](https://github.com/asifkibria/claude-code-toolkit)
6
+ [![GitHub stars](https://img.shields.io/github/stars/nicholasgriffintn/claude-code-toolkit?style=social)](https://github.com/nicholasgriffintn/claude-code-toolkit)
6
7
 
7
- A comprehensive MCP server and CLI toolkit for maintaining, optimizing, and troubleshooting your Claude Code installation.
8
+ **The ultimate maintenance toolkit for Claude Code.** Fix broken sessions, search conversations, detect secrets & PII, manage storage, and monitor everything through a beautiful web dashboard.
8
9
 
9
- ## The Problem This Solves
10
+ > **Love this tool?** Give us a star on GitHub! It helps others discover this project and motivates continued development.
11
+ >
12
+ > [![Star on GitHub](https://img.shields.io/badge/-Star%20on%20GitHub-yellow?style=for-the-badge&logo=github)](https://github.com/nicholasgriffintn/claude-code-toolkit)
10
13
 
11
- When you upload an oversized image, PDF, or document to Claude Code, it gets base64-encoded into your conversation history. That corrupted data then gets sent with **every future request**, causing API errors like:
12
-
13
- - `API Error: 400 - image dimensions exceed max allowed size`
14
- - `PDF too large. Try reading the file a different way...`
15
- - Various timeout and context errors
16
-
17
- **The worst part?** Nothing works anymore. Not your next message. Not `/compact`. Your entire conversation is bricked.
18
-
19
- The "official" fix is to clear your conversation and lose everything. This toolkit offers a better solution.
20
-
21
- ## What It Fixes
22
-
23
- | Content Type | Detection Threshold | Replacement Message |
24
- |-------------|---------------------|---------------------|
25
- | Images | >100KB base64 | `[Image removed - exceeded size limit]` |
26
- | PDFs | >100KB base64 | `[PDF removed - exceeded size limit]` |
27
- | Documents | >100KB base64 | `[Document removed - exceeded size limit]` |
28
- | Large Text | >500KB | `[Large text content removed - exceeded size limit]` |
29
-
30
- The toolkit surgically removes only the problematic content while preserving your entire conversation history, tool results, and context.
31
-
32
- ## Quick Start
14
+ ---
33
15
 
34
- ### Fix Your Broken Session Right Now
16
+ ## Quick Fix
35
17
 
36
18
  ```bash
37
- # Scan for issues
38
- npx @asifkibria/claude-code-toolkit scan
39
-
40
- # Fix them (creates backups automatically)
19
+ # Your session is broken? Fix it in 10 seconds
41
20
  npx @asifkibria/claude-code-toolkit fix
42
- ```
43
21
 
44
- Restart Claude Code. You're back.
22
+ # Restart Claude Code - you're back
23
+ ```
45
24
 
46
- ### Install Globally (Recommended)
25
+ ## Installation
47
26
 
48
27
  ```bash
28
+ # Global install (recommended)
49
29
  npm install -g @asifkibria/claude-code-toolkit
50
30
 
51
- # Use the short alias
31
+ # Use the short alias everywhere
52
32
  cct health
53
- cct scan
54
- cct fix
33
+ cct dashboard
55
34
  ```
56
35
 
57
- ## Installation Options
58
-
59
- ### Option 1: MCP Server (Let Claude Maintain Itself)
36
+ ### Add as MCP Server
60
37
 
61
- Add to Claude Code so you can literally ask Claude to check and fix its own issues:
38
+ Let Claude maintain itself:
62
39
 
63
40
  ```bash
64
41
  claude mcp add --scope user toolkit -- npx -y @asifkibria/claude-code-toolkit claude-code-toolkit-server
65
42
  ```
66
43
 
67
- Then just ask Claude:
68
- - "Check your health"
69
- - "Are there any issues with your conversation files?"
70
- - "Fix any problems you find"
44
+ Then ask Claude: "Check your health" or "Fix any issues"
71
45
 
72
- ### Option 2: CLI Tool
46
+ ---
73
47
 
74
- ```bash
75
- # Global install
76
- npm install -g @asifkibria/claude-code-toolkit
48
+ ## Features Overview
77
49
 
78
- # Or use npx (no install needed)
79
- npx @asifkibria/claude-code-toolkit <command>
80
- ```
50
+ | Category | Features |
51
+ |----------|----------|
52
+ | **Session Recovery** | Fix broken sessions, repair corrupted files, extract content |
53
+ | **Search** | Full-text search across all conversations |
54
+ | **Security** | Secret detection, PII scanning, session auditing |
55
+ | **Storage** | Analytics, cleanup, archiving, snapshots |
56
+ | **Monitoring** | Web dashboard, alerts, quotas, real-time updates |
57
+ | **MCP** | Server validation, performance tracking |
58
+ | **Git** | Link sessions to branches/commits |
59
+ | **Cost** | Token usage and API cost estimation |
81
60
 
82
- ### Option 3: From Source
83
-
84
- ```bash
85
- git clone https://github.com/asifkibria/claude-code-toolkit.git
86
- cd claude-code-toolkit
87
- npm install && npm run build && npm test
88
- ```
61
+ ---
89
62
 
90
- ## CLI Commands
63
+ ## Core Features
91
64
 
92
- ### `cct health` - Quick Health Check
65
+ ### 1. Fix Broken Sessions
93
66
 
94
- Start here. Shows overall status and recommendations.
67
+ When you upload an oversized image/PDF, your entire conversation breaks. This fixes it.
95
68
 
96
69
  ```bash
97
- $ cct health
98
-
99
- Health Check: ⚠ Issues Found
100
-
101
- Conversations: 23
102
- Total size: 156.2 MB
103
- Backups: 5
104
- Oversized content: 3
105
-
106
- Largest: -Users-me-projects-myapp/abc123.jsonl
107
- Size: 45.2 MB
108
-
109
- Recommendation: Run 'cct fix' to fix 3 issue(s)
70
+ cct scan # See what's wrong
71
+ cct fix # Fix it (creates backup automatically)
110
72
  ```
111
73
 
112
- ### `cct scan` - Scan for Issues (Dry Run)
74
+ ### 2. Search All Conversations
113
75
 
114
- Shows exactly what's wrong without making changes.
76
+ Find anything across all your Claude Code conversations - code snippets, discussions, errors, anything.
115
77
 
116
78
  ```bash
117
- $ cct scan
79
+ cct search "API key" # Search all conversations
80
+ cct search "authentication" --role user # Only user messages
81
+ cct search "error" --limit 100 # More results
82
+ ```
118
83
 
119
- Scanning 23 file(s)...
84
+ **Dashboard**: The Search tab provides a visual search interface with filters and highlighted results.
120
85
 
121
- -Users-me-projects-myapp/conversation1.jsonl
122
- Line 142: 🖼️ image (~2.3 MB)
123
- Line 856: 📄 pdf (~1.1 MB)
86
+ ### 3. Web Dashboard
124
87
 
125
- -Users-me-projects-another/conversation2.jsonl
126
- Line 45: 📎 document (~890 KB)
88
+ Visual management of your entire Claude Code installation with **15 tabs**:
127
89
 
128
- Found 3 issue(s) in 2 file(s).
129
- Run 'cct fix' to fix them.
90
+ ```bash
91
+ cct dashboard
130
92
  ```
131
93
 
132
- ### `cct fix` - Fix All Issues
133
-
134
- Removes problematic content and creates backups.
94
+ - **Overview** - Quick health metrics
95
+ - **Search** - Full-text search with filters
96
+ - **Storage** - Usage analytics
97
+ - **Sessions** - All sessions with health status
98
+ - **Security** - Secret & PII scanning
99
+ - **Traces** - Data inventory
100
+ - **MCP** - Server status & tools
101
+ - **Logs** - Debug log viewer
102
+ - **Config** - Settings editor
103
+ - **Analytics** - Usage trends
104
+ - **Backups** - Backup management
105
+ - **Context** - Token estimation
106
+ - **Maintenance** - Automated cleanup
107
+ - **Snapshots** - Storage tracking
108
+ - **About** - Version info
109
+
110
+ ### 4. Security Scanning
111
+
112
+ Find leaked secrets AND personal data (PII) in your conversations.
135
113
 
136
114
  ```bash
137
- $ cct fix
138
-
139
- Processing 23 file(s)...
140
-
141
- ✓ -Users-me-projects-myapp/conversation1.jsonl
142
- Fixed 2 issue(s)
143
- Backup: conversation1.jsonl.backup.2024-01-15T10-30-00
144
-
145
- ✓ -Users-me-projects-another/conversation2.jsonl
146
- Fixed 1 issue(s)
147
- Backup: conversation2.jsonl.backup.2024-01-15T10-30-01
148
-
149
- ✓ Fixed 3 issue(s) in 2 file(s).
150
- Restart Claude Code to apply changes.
115
+ cct security-scan # Scan for secrets (API keys, tokens, passwords)
116
+ cct pii-scan # Scan for PII (emails, phones, SSN, credit cards)
117
+ cct pii-scan --details # Show full unmasked values
118
+ cct audit abc123 # Full audit trail of session
151
119
  ```
152
120
 
153
- ### `cct stats` - Conversation Statistics
121
+ **Dashboard**: Security tab shows secrets and PII with one-click redaction.
154
122
 
155
- See what's using space and resources.
123
+ ### 5. Storage Management
156
124
 
157
125
  ```bash
158
- $ cct stats --limit 5 --sort size
159
-
160
- Conversation Statistics
161
-
162
- Total: 23 conversations, 156.2 MB
163
- Messages: 12,456, Images: 89, Documents: 23
164
- Problematic content: 3
165
-
166
- Top 5 by size:
167
-
168
- -Users-me-projects-myapp/abc123.jsonl
169
- Size: 45.2 MB, Messages: 2,341
170
- Images: 34, Documents: 12 (2 oversized)
171
- Modified: 2024-01-15 10:30:00
172
- ...
126
+ cct clean # Remove debug logs, old snapshots
127
+ cct archive --days 60 # Archive old conversations
128
+ cct trace clean # Selective trace cleanup
173
129
  ```
174
130
 
175
- ### `cct context` - Estimate Context Size
131
+ ### 6. Git Integration
176
132
 
177
- See how much context/tokens your conversations are using.
178
-
179
- ### `cct analytics` - Usage Analytics Dashboard
180
-
181
- Get a comprehensive view of your Claude Code usage with activity trends, top projects, and tool statistics.
133
+ Link your Claude sessions to git branches and commits.
182
134
 
183
135
  ```bash
184
- $ cct analytics
185
-
186
- ╔══════════════════════════════════════════════════════════════╗
187
- ║ USAGE ANALYTICS DASHBOARD ║
188
- ╚══════════════════════════════════════════════════════════════╝
189
-
190
- 📊 OVERVIEW
191
- ──────────────────────────────────────────────────
192
- Conversations: 23
193
- Total Messages: 12,456
194
- Total Tokens: ~2,345,678
195
- Total Size: 156.2 MB
196
- Active Projects: 8
197
- Avg Msgs/Conv: 542
198
- Avg Tokens/Conv: ~102,000
199
-
200
- 📈 ACTIVITY (Last 7 days)
201
- ──────────────────────────────────────────────────
202
- Mon │█████████████████████████│ 234
203
- Tue │████████████████░░░░░░░░░│ 156
204
- Wed │██████████████████░░░░░░░│ 178
205
- ...
206
-
207
- 🏆 TOP PROJECTS (by messages)
208
- ──────────────────────────────────────────────────
209
- -Users-me-myapp │███████████████│ 2,341
210
- -Users-me-another-proj │████████░░░░░░░│ 1,234
211
- ...
212
-
213
- 🔧 TOP TOOLS
214
- ──────────────────────────────────────────────────
215
- Read 1,234 (25%)
216
- Edit 987 (20%)
217
- Bash 654 (13%)
218
- ...
136
+ cct git # Show sessions linked to git repos
219
137
  ```
220
138
 
221
- ### `cct duplicates` - Find Duplicate Content
139
+ ### 7. Cost Estimation
222
140
 
223
- Scan for duplicate conversations and content (images, documents) that waste storage and context.
141
+ Estimate API costs based on token usage.
224
142
 
225
143
  ```bash
226
- $ cct duplicates
227
-
228
- ╔══════════════════════════════════════════════════════════════╗
229
- ║ DUPLICATE DETECTION REPORT ║
230
- ╚══════════════════════════════════════════════════════════════╝
231
-
232
- 📊 SUMMARY
233
- ──────────────────────────────────────────────────
234
- Duplicate groups: 5
235
- Duplicate images: 12
236
- Duplicate documents: 3
237
- Wasted space: 45.2 MB
238
-
239
- 📁 DUPLICATE CONVERSATIONS
240
- ──────────────────────────────────────────────────
241
- [2 copies] Wasted: 12.5 MB
242
- - -Users-me-myapp/conversation1.jsonl
243
- - -Users-me-myapp-backup/conversation1.jsonl
244
-
245
- 🖼️ DUPLICATE CONTENT
246
- ──────────────────────────────────────────────────
247
- 🖼️ image [3 copies] ~2.1 MB wasted
248
- - -Users-me-proj1/conv.jsonl:142
249
- - -Users-me-proj1/conv.jsonl:856
250
- ... and 1 more locations
251
-
252
- 💡 RECOMMENDATIONS
253
- ──────────────────────────────────────────────────
254
- - Review duplicate conversations and consider removing copies
255
- - Same images appear multiple times in your conversations
144
+ cct cost # Show estimated API costs
256
145
  ```
257
146
 
258
- ### `cct archive` - Archive Old Conversations
147
+ ### 8. Alerts & Quotas
259
148
 
260
- Move inactive conversations to an archive directory to free up space.
149
+ Proactive issue detection and usage monitoring.
261
150
 
262
151
  ```bash
263
- $ cct archive --days 60 --dry-run
264
-
265
- ╔══════════════════════════════════════════════════════════════╗
266
- ║ CONVERSATION ARCHIVE REPORT ║
267
- ╚══════════════════════════════════════════════════════════════╝
268
-
269
- 📊 SUMMARY
270
- ──────────────────────────────────────────────────
271
- Eligible conversations: 8
272
- Total size: 45.2 MB
273
-
274
- 📁 ARCHIVE CANDIDATES
275
- ──────────────────────────────────────────────────
276
- ...-Users-me-old-project/abc123.jsonl
277
- 65 days inactive, 234 msgs, 12.5 MB
278
- ...-Users-me-another-old/def456.jsonl
279
- 45 days inactive, 156 msgs, 8.2 MB
280
- ...
281
-
282
- 📋 DRY RUN - No changes made
283
- ──────────────────────────────────────────────────
284
- Would archive: 8 conversations
285
- Would free: 45.2 MB
286
- Archive to: ~/.claude/archive
152
+ cct alerts # Check for issues and notifications
153
+ cct quotas # Show usage quotas with visual bars
287
154
  ```
288
155
 
289
- ### `cct maintenance` - Scheduled Maintenance
156
+ ---
290
157
 
291
- Run automated maintenance checks and actions.
158
+ ## Common Problems & Solutions
292
159
 
160
+ ### Your session is broken
293
161
  ```bash
294
- $ cct maintenance
295
-
296
- ╔══════════════════════════════════════════════════════════════╗
297
- ║ MAINTENANCE REPORT ║
298
- ╚══════════════════════════════════════════════════════════════╝
299
-
300
- 📊 STATUS
301
- ──────────────────────────────────────────────────
302
- ⚠ Needs Attention
303
-
304
- 📋 PENDING ACTIONS (dry run)
305
- ──────────────────────────────────────────────────
306
- 🔧 Oversized content detected
307
- 3 item(s) (~2.3 MB)
308
- 🗑️ Backups older than 7 days
309
- 5 item(s) (~89.3 MB)
310
- 📦 Conversations inactive for 60+ days
311
- 8 item(s) (~45.2 MB)
312
-
313
- 💡 RECOMMENDATIONS
314
- ──────────────────────────────────────────────────
315
- - Run 'cct fix' to remove oversized content
316
- - Run 'cct cleanup --days 7' to remove old backups
317
- - Run 'cct archive --days 60' to archive inactive conversations
318
-
319
- # Show scheduled maintenance setup
320
- $ cct maintenance --schedule
321
-
322
- # Run maintenance automatically
323
- $ cct maintenance --auto
162
+ cct scan && cct fix
324
163
  ```
325
164
 
165
+ ### Find something you discussed
326
166
  ```bash
327
- # Summary of all conversations by context size
328
- $ cct context
329
-
330
- Context Usage Summary
331
-
332
- Total conversations: 23
333
- Combined tokens: ~1,234,567
334
-
335
- Top 10 by context size:
336
-
337
- -Users-me-projects-myapp/abc123.jsonl
338
- ~125,000 tokens (456 messages)
339
- ⚠ Context exceeds 100K tokens - consider archiving older messages
340
-
341
- -Users-me-projects-another/def456.jsonl
342
- ~45,000 tokens (234 messages)
343
- ...
344
-
345
- # Detailed breakdown for a specific file
346
- $ cct context -f ~/.claude/projects/-Users-me-myapp/conversation.jsonl
347
-
348
- Context Size Estimate
349
- ────────────────────────────────────────
350
- Total: ~125,000 tokens
351
- Messages: 456
352
-
353
- Breakdown:
354
- User messages: 12,500 tokens
355
- Assistant messages: 85,000 tokens
356
- Tool calls: 5,000 tokens
357
- Tool results: 20,000 tokens
358
- Images: 2,500 tokens
359
-
360
- Largest message: Line 342 (assistant)
361
- ~8,500 tokens
362
-
363
- Warnings:
364
- ⚠ Context exceeds 100K tokens - consider archiving older messages
167
+ cct search "your query"
365
168
  ```
366
169
 
367
- ### `cct backups` - List Backups
368
-
369
- See all backup files.
370
-
170
+ ### Leaked secrets or PII
371
171
  ```bash
372
- $ cct backups
373
-
374
- Backup Files (5 files, 89.3 MB total)
375
-
376
- conversation1.jsonl.backup.2024-01-15T10-30-00
377
- Size: 23.4 MB, Created: 2024-01-15 10:30:00
378
- ...
172
+ cct security-scan
173
+ cct pii-scan --details
379
174
  ```
380
175
 
381
- ### `cct restore <path>` - Restore from Backup
382
-
383
- Undo a fix if needed.
384
-
176
+ ### Disk space issues
385
177
  ```bash
386
- $ cct restore ~/.claude/projects/-Users-me-myapp/conversation.jsonl.backup.2024-01-15T10-30-00
387
-
388
- ✓ Restored /Users/me/.claude/projects/-Users-me-myapp/conversation.jsonl
389
- Restart Claude Code to apply changes.
178
+ cct stats && cct clean
390
179
  ```
391
180
 
392
- ### `cct cleanup` - Delete Old Backups
393
-
394
- Free up disk space.
395
-
181
+ ### Session crashed
396
182
  ```bash
397
- # Preview what would be deleted
398
- $ cct cleanup --days 7 --dry-run
399
-
400
- Would delete 3 backup(s):
401
- conversation1.jsonl.backup.2024-01-01T00-00-00
402
- conversation2.jsonl.backup.2024-01-02T00-00-00
403
- conversation3.jsonl.backup.2024-01-03T00-00-00
404
-
405
- Run without --dry-run to delete.
406
-
407
- # Actually delete them
408
- $ cct cleanup --days 7
409
-
410
- ✓ Deleted 3 backup(s)
183
+ cct recover abc123 --repair
411
184
  ```
412
185
 
413
- ### `cct export` - Export Conversation
414
-
415
- Export a conversation to markdown or JSON for backup, sharing, or archiving.
416
-
186
+ ### MCP not working
417
187
  ```bash
418
- # Export to markdown (default)
419
- $ cct export -f ~/.claude/projects/-Users-me-myapp/conversation.jsonl
420
-
421
- ✓ Exported 156 messages to conversation.md
422
-
423
- # Export to JSON
424
- $ cct export -f conversation.jsonl --format json -o backup.json
425
-
426
- ✓ Exported 156 messages to backup.json
427
-
428
- # Include tool results in export
429
- $ cct export -f conversation.jsonl --with-tools
430
-
431
- ✓ Exported 156 messages to conversation.md
188
+ cct mcp-validate --test
432
189
  ```
433
190
 
434
- **Export formats:**
435
-
436
- - **Markdown**: Human-readable format with headers, code blocks, and tool summaries
437
- - **JSON**: Structured format with full message metadata for programmatic use
191
+ ---
438
192
 
439
- ## CLI Options Reference
193
+ ## All Commands
194
+
195
+ | Command | What it does |
196
+ |---------|--------------|
197
+ | `cct health` | Quick system health check |
198
+ | `cct scan` | Find issues without fixing |
199
+ | `cct fix` | Fix issues (with backup) |
200
+ | `cct dashboard` | Launch web dashboard |
201
+ | `cct search` | **Search all conversations** |
202
+ | `cct stats` | Conversation statistics |
203
+ | `cct context` | Token/context usage |
204
+ | `cct cost` | **API cost estimation** |
205
+ | `cct analytics` | Usage trends and patterns |
206
+ | `cct duplicates` | Find duplicate content |
207
+ | `cct clean` | Clean .claude directory |
208
+ | `cct archive` | Archive old conversations |
209
+ | `cct maintenance` | Automated maintenance |
210
+ | `cct sessions` | List all sessions |
211
+ | `cct diff` | **Compare two sessions** |
212
+ | `cct recover` | Repair crashed sessions |
213
+ | `cct security-scan` | Find leaked secrets |
214
+ | `cct pii-scan` | **Find personal data (PII)** |
215
+ | `cct audit` | Session audit trail |
216
+ | `cct retention` | Apply data retention |
217
+ | `cct git` | **Link sessions to git** |
218
+ | `cct alerts` | **Check for issues** |
219
+ | `cct quotas` | **Show usage quotas** |
220
+ | `cct mcp-validate` | Validate MCP configs |
221
+ | `cct mcp-perf` | **MCP performance stats** |
222
+ | `cct trace` | Trace inventory |
223
+ | `cct trace clean` | Selective cleanup |
224
+ | `cct trace wipe` | Secure wipe |
225
+ | `cct backups` | List backups |
226
+ | `cct restore` | Restore from backup |
227
+ | `cct cleanup` | Delete old backups |
228
+ | `cct export` | Export conversation |
440
229
 
441
- | Option | Description |
442
- |--------|-------------|
443
- | `-f, --file <path>` | Target a specific file instead of all conversations |
444
- | `-o, --output <path>` | For export: output file path |
445
- | `--format <type>` | For export: `markdown` or `json` (default: markdown) |
446
- | `--with-tools` | For export: include tool results in output |
447
- | `-d, --dry-run` | Preview changes without making them |
448
- | `--no-backup` | Skip creating backups when fixing (not recommended) |
449
- | `--days <n>` | For cleanup: delete backups older than n days (default: 7) |
450
- | `--limit <n>` | For stats: limit number of results (default: 10) |
451
- | `--sort <field>` | For stats: sort by `size`, `messages`, `images`, or `modified` |
452
- | `-h, --help` | Show help message |
453
- | `-v, --version` | Show version |
230
+ ---
454
231
 
455
232
  ## MCP Server Tools
456
233
 
457
- When installed as an MCP server, these tools are available to Claude:
234
+ When installed as MCP server, Claude can use these tools directly:
458
235
 
459
236
  | Tool | Description |
460
237
  |------|-------------|
461
- | `health_check` | Quick health check with recommendations |
462
- | `get_conversation_stats` | Detailed statistics about conversations |
463
- | `estimate_context_size` | Estimate token/context usage of conversations |
464
- | `usage_analytics` | Usage analytics dashboard with trends and breakdowns |
465
- | `find_duplicates` | Find duplicate conversations and content |
466
- | `archive_conversations` | Archive old/inactive conversations |
467
- | `run_maintenance` | Run maintenance checks and actions |
468
- | `scan_image_issues` | Scan for oversized content (images, PDFs, documents) |
469
- | `fix_image_issues` | Fix detected issues with automatic backups |
470
- | `export_conversation` | Export conversation to markdown or JSON format |
471
- | `list_backups` | List all backup files |
472
- | `restore_backup` | Restore a conversation from backup |
473
- | `cleanup_backups` | Delete old backups to free space |
474
-
475
- ## How It Works
476
-
477
- 1. **Locates** your Claude Code data in `~/.claude/projects/`
478
- 2. **Scans** conversation files (`.jsonl`) line by line
479
- 3. **Detects** oversized content:
480
- - Images with base64 data >100KB
481
- - PDFs with base64 data >100KB
482
- - Documents with base64 data >100KB
483
- - Text content >500KB
484
- 4. **Reports** findings with file paths, line numbers, and sizes
485
- 5. **Fixes** by replacing problematic content with placeholder text
486
- 6. **Backs up** original files before any modification
238
+ | `health_check` | System health |
239
+ | `scan_image_issues` / `fix_image_issues` | Content fixes |
240
+ | `security_scan` / `scan_pii` | Security scanning |
241
+ | `search_conversations` | Full-text search |
242
+ | `estimate_cost` | Cost estimation |
243
+ | `git_integration` | Git linking |
244
+ | `check_alerts` / `check_quotas` | Monitoring |
245
+ | `mcp_performance` | MCP stats |
246
+ | `audit_session` | Session auditing |
247
+ | `clean_claude_directory` / `clean_traces` | Cleanup |
248
+ | `list_sessions` / `recover_session` | Session management |
249
+ | `validate_mcp_config` | MCP validation |
250
+ | `start_dashboard` | Launch dashboard |
487
251
 
488
- ## Common Scenarios
489
-
490
- ### My Claude Code session is completely broken
491
-
492
- ```bash
493
- cct scan # See what's wrong
494
- cct fix # Fix it
495
- # Restart Claude Code
496
- ```
497
-
498
- ### I want to prevent issues before they happen
499
-
500
- ```bash
501
- cct health # Quick check
502
- ```
503
-
504
- ### I accidentally uploaded a huge file
505
-
506
- ```bash
507
- cct fix -f ~/.claude/projects/path/to/conversation.jsonl
508
- ```
509
-
510
- ### I want to undo a fix
511
-
512
- ```bash
513
- cct backups # Find your backup
514
- cct restore /path/to/backup # Restore it
515
- ```
516
-
517
- ### My disk is filling up
518
-
519
- ```bash
520
- cct cleanup --days 30 --dry-run # Preview
521
- cct cleanup --days 30 # Delete
522
- ```
523
-
524
- ### I want to save or share a conversation
525
-
526
- ```bash
527
- cct export -f ~/.claude/projects/path/to/conversation.jsonl
528
- # Creates conversation.md in current directory
529
- ```
530
-
531
- ### My conversations are getting slow
532
-
533
- ```bash
534
- cct context # See which conversations are using the most tokens
535
- ```
536
-
537
- ### I want to see my usage patterns
538
-
539
- ```bash
540
- cct analytics # Full usage dashboard with trends and stats
541
- ```
542
-
543
- ### I have duplicate content wasting space
252
+ ---
544
253
 
545
- ```bash
546
- cct duplicates # Find duplicate conversations and content
547
- ```
254
+ ## How It Works
548
255
 
549
- ### I want to clean up old conversations
256
+ 1. Locates Claude Code data in `~/.claude/projects/`
257
+ 2. Scans `.jsonl` conversation files
258
+ 3. Detects oversized content, secrets, PII, and issues
259
+ 4. Provides fixes with automatic backups
260
+ 5. Offers visual dashboard for complete management
550
261
 
551
- ```bash
552
- cct archive --days 60 --dry-run # Preview what would be archived
553
- cct archive --days 60 # Archive conversations inactive for 60+ days
554
- ```
262
+ ---
555
263
 
556
- ### I want automated maintenance
264
+ ## Support This Project
557
265
 
558
- ```bash
559
- cct maintenance # Check what needs attention
560
- cct maintenance --auto # Automatically fix issues
561
- cct maintenance --schedule # Get cron/launchd setup instructions
562
- ```
266
+ If Claude Code Toolkit has helped you:
563
267
 
564
- ## Development
268
+ - **Star the repo** - It really helps! [![GitHub stars](https://img.shields.io/github/stars/nicholasgriffintn/claude-code-toolkit?style=social)](https://github.com/nicholasgriffintn/claude-code-toolkit)
269
+ - **Share with colleagues** - Help others discover this tool
270
+ - **Report bugs** - Open issues on GitHub
271
+ - **Contribute** - PRs welcome!
565
272
 
566
- ```bash
567
- npm install # Install dependencies
568
- npm run build # Build TypeScript
569
- npm test # Run tests (70 tests)
570
- npm run dev # Watch mode
571
- npm run test:coverage # Coverage report
572
- ```
273
+ ---
573
274
 
574
- ## Contributing
275
+ ## Links
575
276
 
576
- Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
277
+ - [npm](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit)
278
+ - [GitHub](https://github.com/nicholasgriffintn/claude-code-toolkit)
279
+ - [Issues](https://github.com/nicholasgriffintn/claude-code-toolkit/issues)
577
280
 
578
281
  ## License
579
282
 
580
- MIT - see [LICENSE](LICENSE)
581
-
582
- ## Links
583
-
584
- - [npm package](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit)
585
- - [GitHub repository](https://github.com/asifkibria/claude-code-toolkit)
586
- - [Original issue #2939](https://github.com/anthropics/claude-code/issues/2939)
283
+ MIT
587
284
 
588
285
  ---
589
286