@asifkibria/claude-code-toolkit 1.0.2 → 1.2.0

package/README.md

@@ -2,321 +2,272 @@
 
 [![npm version](https://img.shields.io/npm/v/@asifkibria/claude-code-toolkit.svg)](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://img.shields.io/badge/tests-38%20passing-brightgreen)](https://github.com/asifkibria/claude-code-toolkit)
 
-A comprehensive MCP server and CLI toolkit for maintaining, optimizing, and troubleshooting your Claude Code installation.
+Maintain, optimize, secure, and troubleshoot your Claude Code installation. Fix broken sessions, manage storage, detect secrets, and monitor everything through a web dashboard.
 
-## The Problem This Solves
-
-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:
-
-- `API Error: 400 - image dimensions exceed max allowed size`
-- `PDF too large. Try reading the file a different way...`
-- Various timeout and context errors
-
-**The worst part?** Nothing works anymore. Not your next message. Not `/compact`. Your entire conversation is bricked.
-
-The "official" fix is to clear your conversation and lose everything. This toolkit offers a better solution.
-
-## What It Fixes
-
-| Content Type | Detection Threshold | Replacement Message |
-|-------------|---------------------|---------------------|
-| Images | >100KB base64 | `[Image removed - exceeded size limit]` |
-| PDFs | >100KB base64 | `[PDF removed - exceeded size limit]` |
-| Documents | >100KB base64 | `[Document removed - exceeded size limit]` |
-| Large Text | >500KB | `[Large text content removed - exceeded size limit]` |
-
-The toolkit surgically removes only the problematic content while preserving your entire conversation history, tool results, and context.
-
-## Quick Start
-
-### Fix Your Broken Session Right Now
+## Quick Fix
 
 ```bash
-# Scan for issues
-npx @asifkibria/claude-code-toolkit scan
-
-# Fix them (creates backups automatically)
+# Your session is broken? Fix it in 10 seconds
 npx @asifkibria/claude-code-toolkit fix
-```
 
-Restart Claude Code. You're back.
+# Restart Claude Code - you're back
+```
 
-### Install Globally (Recommended)
+## Installation
 
 ```bash
+# Global install (recommended)
 npm install -g @asifkibria/claude-code-toolkit
 
-# Use the short alias
+# Use the short alias everywhere
 cct health
-cct scan
-cct fix
+cct dashboard
 ```
 
-## Installation Options
-
-### Option 1: MCP Server (Let Claude Maintain Itself)
+### Add as MCP Server
 
-Add to Claude Code so you can literally ask Claude to check and fix its own issues:
+Let Claude maintain itself:
 
 ```bash
 claude mcp add --scope user toolkit -- npx -y @asifkibria/claude-code-toolkit claude-code-toolkit-server
 ```
 
-Then just ask Claude:
-- "Check your health"
-- "Are there any issues with your conversation files?"
-- "Fix any problems you find"
+Then ask Claude: "Check your health" or "Fix any issues"
 
-### Option 2: CLI Tool
+---
 
-```bash
-# Global install
-npm install -g @asifkibria/claude-code-toolkit
+## Core Features
 
-# Or use npx (no install needed)
-npx @asifkibria/claude-code-toolkit <command>
-```
+### 1. Fix Broken Sessions
 
-### Option 3: From Source
+When you upload an oversized image/PDF, your entire conversation breaks. This fixes it.
 
 ```bash
-git clone https://github.com/asifkibria/claude-code-toolkit.git
-cd claude-code-toolkit
-npm install && npm run build && npm test
+cct scan        # See what's wrong
+cct fix         # Fix it (creates backup automatically)
 ```
 
-## CLI Commands
+### 2. Web Dashboard
 
-### `cct health` - Quick Health Check
-
-Start here. Shows overall status and recommendations.
+Visual management of your entire Claude Code installation.
 
 ```bash
-$ cct health
+cct dashboard
+```
 
-Health Check: ⚠ Issues Found
+14 tabs: Overview, Storage, Sessions, Security, Traces, MCP, Logs, Config, Snapshots, Analytics, Backups, Context, Maintenance, About
 
-Conversations: 23
-Total size: 156.2 MB
-Backups: 5
-Oversized content: 3
+### 3. Security Scanning
 
-Largest: -Users-me-projects-myapp/abc123.jsonl
-  Size: 45.2 MB
+Find leaked secrets in your conversations.
 
-Recommendation: Run 'cct fix' to fix 3 issue(s)
+```bash
+cct security-scan     # Scan all conversations
+cct audit abc123      # Full audit trail of session
 ```
 
-### `cct scan` - Scan for Issues (Dry Run)
-
-Shows exactly what's wrong without making changes.
+### 4. Storage Management
 
 ```bash
-$ cct scan
-
-Scanning 23 file(s)...
-
--Users-me-projects-myapp/conversation1.jsonl
-  Line 142: 🖼️  image (~2.3 MB)
-  Line 856: 📄 pdf (~1.1 MB)
-
--Users-me-projects-another/conversation2.jsonl
-  Line 45: 📎 document (~890 KB)
-
-Found 3 issue(s) in 2 file(s).
-Run 'cct fix' to fix them.
+cct clean             # Remove debug logs, old snapshots
+cct archive --days 60 # Archive old conversations
+cct trace clean       # Selective trace cleanup
 ```
 
-### `cct fix` - Fix All Issues
-
-Removes problematic content and creates backups.
-
-```bash
-$ cct fix
+---
 
-Processing 23 file(s)...
+## Common Problems & Solutions
 
-✓ -Users-me-projects-myapp/conversation1.jsonl
-  Fixed 2 issue(s)
-  Backup: conversation1.jsonl.backup.2024-01-15T10-30-00
+### 🚨 Out of Memory / API Error
 
-✓ -Users-me-projects-another/conversation2.jsonl
-  Fixed 1 issue(s)
-  Backup: conversation2.jsonl.backup.2024-01-15T10-30-01
+Uploaded a large image or PDF and now Claude won't respond? The conversation file is too big for the API.
 
-✓ Fixed 3 issue(s) in 2 file(s).
-Restart Claude Code to apply changes.
+```bash
+cct scan                    # Identify oversized content
+cct fix                     # Remove problematic content (creates backup)
+# Restart Claude Code - you're back
 ```
 
-### `cct stats` - Conversation Statistics
+### 🔐 Leaked Secrets
 
-See what's using space and resources.
+Accidentally pasted API keys, passwords, or tokens in chat? Find and audit them before they're exposed.
 
 ```bash
-$ cct stats --limit 5 --sort size
-
-Conversation Statistics
-
-Total: 23 conversations, 156.2 MB
-Messages: 12,456, Images: 89, Documents: 23
-Problematic content: 3
-
-Top 5 by size:
-
--Users-me-projects-myapp/abc123.jsonl
-  Size: 45.2 MB, Messages: 2,341
-  Images: 34, Documents: 12 (2 oversized)
-  Modified: 2024-01-15 10:30:00
-...
+cct security-scan           # Scan for AWS keys, tokens, passwords
+cct audit abc123            # Full audit trail of what was accessed
 ```
 
-### `cct backups` - List Backups
+### 🛑 Broken Sessions
 
-See all backup files.
+Claude crashed mid-conversation and `--resume` doesn't work? Recover and repair corrupted session files.
 
 ```bash
-$ cct backups
-
-Backup Files (5 files, 89.3 MB total)
-
-conversation1.jsonl.backup.2024-01-15T10-30-00
-  Size: 23.4 MB, Created: 2024-01-15 10:30:00
-...
+cct sessions                # List all sessions with health status
+cct recover abc123          # Diagnose the session
+cct recover abc123 --repair # Fix corrupted lines
+cct recover abc123 --extract # Extract salvageable content
 ```
 
-### `cct restore <path>` - Restore from Backup
+### 💾 Disk Space
 
-Undo a fix if needed.
+Months of conversation history eating up GBs? Clean old traces and archive inactive sessions.
 
 ```bash
-$ cct restore ~/.claude/projects/-Users-me-myapp/conversation.jsonl.backup.2024-01-15T10-30-00
-
-✓ Restored /Users/me/.claude/projects/-Users-me-myapp/conversation.jsonl
-Restart Claude Code to apply changes.
+cct stats                   # See what's using space
+cct clean --dry-run         # Preview cleanup
+cct clean                   # Remove debug logs, old snapshots
+cct archive --days 30       # Archive old conversations
 ```
 
-### `cct cleanup` - Delete Old Backups
+### 👁 Privacy / Trace Cleanup
 
-Free up disk space.
+Corporate security requires clearing Claude traces? Full inventory of 18 trace categories with secure wipe.
 
 ```bash
-# Preview what would be deleted
-$ cct cleanup --days 7 --dry-run
-
-Would delete 3 backup(s):
-  conversation1.jsonl.backup.2024-01-01T00-00-00
-  conversation2.jsonl.backup.2024-01-02T00-00-00
-  conversation3.jsonl.backup.2024-01-03T00-00-00
+cct trace                           # Full inventory of stored data
+cct trace clean --days 7            # Remove traces older than 7 days
+cct trace wipe --confirm            # Secure wipe everything
+cct trace guard --mode paranoid     # Auto-delete going forward
+```
 
-Run without --dry-run to delete.
+### 📦 Backup & Restore
 
-# Actually delete them
-$ cct cleanup --days 7
+Need to undo a fix or restore a conversation? Automatic backups before every change.
 
-✓ Deleted 3 backup(s)
+```bash
+cct backups                 # List available backups
+cct restore /path/to/backup # Restore original
+cct cleanup --days 30       # Delete old backups
 ```
 
-## CLI Options Reference
-
-| Option | Description |
-|--------|-------------|
-| `-f, --file <path>` | Target a specific file instead of all conversations |
-| `-d, --dry-run` | Preview changes without making them |
-| `--no-backup` | Skip creating backups when fixing (not recommended) |
-| `--days <n>` | For cleanup: delete backups older than n days (default: 7) |
-| `--limit <n>` | For stats: limit number of results (default: 10) |
-| `--sort <field>` | For stats: sort by `size`, `messages`, `images`, or `modified` |
-| `-h, --help` | Show help message |
-| `-v, --version` | Show version |
+### 📷 Storage Snapshots
 
-## MCP Server Tools
+Track how Claude's storage grows over time. Compare snapshots to see what changed.
 
-When installed as an MCP server, these tools are available to Claude:
+```bash
+cct dashboard               # Snapshots tab in web UI
+# Or via MCP: snapshot, compare, delete-snapshot actions
+```
 
-| Tool | Description |
-|------|-------------|
-| `health_check` | Quick health check with recommendations |
-| `get_conversation_stats` | Detailed statistics about conversations |
-| `scan_image_issues` | Scan for oversized content (images, PDFs, documents) |
-| `fix_image_issues` | Fix detected issues with automatic backups |
-| `list_backups` | List all backup files |
-| `restore_backup` | Restore a conversation from backup |
-| `cleanup_backups` | Delete old backups to free space |
+### 📜 Debug Logs
 
-## How It Works
+Something went wrong but you don't know what? Search and filter debug logs by level, component, or text.
 
-1. **Locates** your Claude Code data in `~/.claude/projects/`
-2. **Scans** conversation files (`.jsonl`) line by line
-3. **Detects** oversized content:
-   - Images with base64 data >100KB
-   - PDFs with base64 data >100KB
-   - Documents with base64 data >100KB
-   - Text content >500KB
-4. **Reports** findings with file paths, line numbers, and sizes
-5. **Fixes** by replacing problematic content with placeholder text
-6. **Backs up** original files before any modification
+```bash
+cct dashboard               # Logs tab with search and filtering
+# Filter by level (DEBUG, INFO, WARN, ERROR)
+# Search by component or message text
+```
 
-## Common Scenarios
+### 🔌 MCP Servers Not Connecting
 
-### My Claude Code session is completely broken
+MCP servers aren't working? Validate configs and test connectivity.
 
 ```bash
-cct scan    # See what's wrong
-cct fix     # Fix it
-# Restart Claude Code
+cct mcp-validate            # Check all MCP configs
+cct mcp-validate --test     # Test actual connectivity
+cct dashboard               # MCP tab shows tools/resources per server
 ```
 
-### I want to prevent issues before they happen
+### 📊 Visual Dashboard
+
+Want a visual overview of everything? 14 tabs for complete management.
 
 ```bash
-cct health  # Quick check
+cct dashboard               # Opens web UI at localhost:1405
+cct dashboard --port 9000   # Custom port
+cct dashboard --daemon      # Run in background
 ```
 
-### I accidentally uploaded a huge file
+### 📤 Export Conversations
+
+Need to export a conversation for backup or sharing?
 
 ```bash
-cct fix -f ~/.claude/projects/path/to/conversation.jsonl
+cct export -f /path/to/conversation.jsonl
+cct export -f conversation.jsonl --format json
 ```
 
-### I want to undo a fix
+---
 
-```bash
-cct backups                    # Find your backup
-cct restore /path/to/backup    # Restore it
-```
+## All Commands
+
+| Command | What it does |
+|---------|--------------|
+| `cct health` | Quick system health check |
+| `cct scan` | Find issues without fixing |
+| `cct fix` | Fix issues (with backup) |
+| `cct dashboard` | Launch web dashboard |
+| `cct stats` | Conversation statistics |
+| `cct context` | Token/context usage |
+| `cct analytics` | Usage trends and patterns |
+| `cct duplicates` | Find duplicate content |
+| `cct clean` | Clean .claude directory |
+| `cct archive` | Archive old conversations |
+| `cct maintenance` | Automated maintenance |
+| `cct sessions` | List all sessions |
+| `cct recover` | Repair crashed sessions |
+| `cct security-scan` | Find leaked secrets |
+| `cct audit` | Session audit trail |
+| `cct retention` | Apply data retention |
+| `cct trace` | Trace inventory |
+| `cct trace clean` | Selective cleanup |
+| `cct trace wipe` | Secure wipe |
+| `cct mcp-validate` | Validate MCP configs |
+| `cct backups` | List backups |
+| `cct restore` | Restore from backup |
+| `cct cleanup` | Delete old backups |
+| `cct export` | Export conversation |
+
+## Common Options
+
+| Option | Used with | Description |
+|--------|-----------|-------------|
+| `--dry-run` | Most commands | Preview without changes |
+| `--days N` | clean, archive, retention | Age threshold |
+| `-f, --file` | scan, fix, export | Target specific file |
+| `--port N` | dashboard | Custom port (default: 1405) |
+| `--test` | mcp-validate | Test connectivity |
+| `--repair` | recover | Attempt repair |
+| `--extract` | recover | Extract content |
+| `--confirm` | trace wipe | Required for wipe |
 
-### My disk is filling up
+---
 
-```bash
-cct cleanup --days 30 --dry-run  # Preview
-cct cleanup --days 30            # Delete
-```
+## MCP Server Tools
 
-## Development
+When installed as MCP server, Claude can use these tools directly:
 
-```bash
-npm install        # Install dependencies
-npm run build      # Build TypeScript
-npm test           # Run tests (38 tests)
-npm run dev        # Watch mode
-npm run test:coverage  # Coverage report
-```
+- `health_check` - System health
+- `scan_image_issues` / `fix_image_issues` - Content fixes
+- `security_scan` / `audit_session` - Security
+- `clean_claude_directory` / `clean_traces` - Cleanup
+- `list_sessions` / `recover_session` - Session management
+- `validate_mcp_config` - MCP validation
+- `start_dashboard` - Launch dashboard
 
-## Contributing
+---
 
-Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
+## How It Works
 
-## License
+1. Locates Claude Code data in `~/.claude/projects/`
+2. Scans `.jsonl` conversation files
+3. Detects oversized content (images >100KB, PDFs, large text)
+4. Replaces problematic content with placeholders
+5. Creates backups before any modification
 
-MIT - see [LICENSE](LICENSE)
+---
 
 ## Links
 
-- [npm package](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit)
-- [GitHub repository](https://github.com/asifkibria/claude-code-toolkit)
-- [Original issue #2939](https://github.com/anthropics/claude-code/issues/2939)
+- [npm](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit)
+- [GitHub](https://github.com/asifkibria/claude-code-toolkit)
+- [Website](https://asifkibria.github.io/claude-code-toolkit)
+
+## License
+
+MIT
 
 ---
 

package/dist/CLAUDE.md

@@ -0,0 +1,7 @@
+<claude-mem-context>
+# Recent Activity
+
+<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
+
+*No recent activity*
+</claude-mem-context>

package/dist/__tests__/dashboard.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dashboard.test.d.ts.map

package/dist/__tests__/dashboard.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/dashboard.test.ts"],"names":[],"mappings":""}