Claude Code Toolkit
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Claude Code Toolkit show my usage report"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Claude Code Toolkit
Maintenance, recovery, and observability for Claude Code. CLI + MCP server + dashboard.
TL;DR — fix, monitor, manage
# 1. install
npm i -g @asifkibria/claude-code-toolkit
# 2. one-shot diagnose + fix
cct doctor # full integrity check (corruption, indices, oversized, orphans)
cct doctor --repair # auto-fix everything safe
cct unstick # rescue a session stuck on "PDF too large" (#13518)
# 3. know your spend
cct usage # real token usage + cost from JSONL records
cct usage --days 7 # last week only
# 4. prevent the next break (run forever)
cct hooks scaffold auto-fix-on-start # auto-scrub oversized content on session start
cct watch --auto-fix --daemon # also watch live in the background
# 5. multi-account
cct profile save work # snapshot ~/.claude.json as 'work'
cct profile switch personal # swap accounts (auto-backup + restart Claude Code)
# 6. visual dashboard
cct dashboard # web UI on :1405 — Usage, Doctor, Hooks, Profiles tabsAdd it as an MCP server so Claude can do all of this from inside chat:
claude mcp add --scope user toolkit -- npx -y @asifkibria/claude-code-toolkit claude-code-toolkit-serverThen in Claude: "Run the doctor" / "Show my usage report" — or use the slash commands at docs/slash-commands.md.
Related MCP server: self-claude-mcp
What it actually does
You have… | Run this |
A session stuck on |
|
Anything weird with your install |
|
Oversized images bloating disk |
|
Need to know your real API spend |
|
Multiple accounts (work / personal / clients) |
|
Need lifecycle automation |
|
A leaked secret you need to find |
|
PII in old conversations |
|
A session that crashed |
|
MCP servers that won't connect |
|
Dashboard
cct dashboard # opens http://localhost:1405
cct dashboard --daemon # background
cct dashboard --stop # stop background21 tabs including the v2.0 additions: 💸 Usage, 🩺 Doctor, ⚙ Hooks, 👤 Profiles, 📬 Queue, plus Overview · Search · Storage · Sessions · Security · Traces · MCP · Logs · Config · Analytics · Backups · Context · Maintenance · Snapshots · Starred · About.
Cost numbers are upper-bound PAYG estimates. They do not reflect Pro/Max plan flat rates, enterprise contracts, or free credits. Use console.anthropic.com for authoritative billing.
MCP integration
Once registered (claude mcp add ...), Claude can call these tools directly: health_check, fix_image_issues, unstick_session, search_conversations, security_scan, scan_pii, audit_session, start_dashboard, and ~20 more. Full MCP tool list →
Issue #13518: "PDF too large" wedge
The cct unstick command is the dedicated fix. It scrubs the oversized base64 from the JSONL and clears the per-session warning state files that keep Claude Code in the bad state. After running it, run /clear in chat or open a new conversation to flush in-memory state.
cct install-hook makes this preventative — every session start runs cct fix quietly, so oversized content never gets a chance to wedge a session.
Links
MIT
Available Tools
40 toolsarchive_conversationsA
Archive old/inactive conversations to free up space. Moves conversations that haven't been modified in a specified number of days to an archive directory.
Inputs: days, dry_run.
audit_sessionA
Generate an audit report for a session showing all files read/written, commands executed, MCP tools used, and URLs fetched.
Inputs: session_id (required).
check_alertsB
Check for issues and notifications: disk space warnings, corrupted sessions, quota violations.
Inputs: no named parameters.
check_quotasA
Show usage quotas and limits: storage, sessions, retention age.
Inputs: no named parameters.
clean_claude_directoryC
Analyze and clean the .claude directory. Removes debug logs, empty todos, old snapshots, and orphaned data to free disk space.
Inputs: dry_run, days, category.
clean_tracesA
Selectively clean Claude Code traces by category, age, or project.
Inputs: categories, days, project, dry_run.
cleanup_backupsC
Delete old backup files to free up disk space.
Inputs: older_than_days, dry_run.
enforce_retentionC
Apply data retention policy by deleting sessions older than specified days.
Inputs: days, dry_run.
estimate_context_sizeA
Estimate the context/token usage of a Claude Code conversation. Shows breakdown by message type, images, documents, and tool usage.
Inputs: path.
estimate_costA
Estimate API costs based on token usage across all conversations.
Inputs: no named parameters.
export_conversationB
Export a Claude Code conversation to markdown or JSON format for backup or sharing.
Inputs: path (required), format, include_tool_results.
find_duplicatesA
Scan for duplicate content across Claude Code conversations. Finds duplicate conversations, images, and documents that waste storage and context space.
Inputs: no named parameters.
fix_image_issuesA
Fix oversized images in Claude Code conversations by replacing them with placeholder text. Creates backups before changes.
Inputs: path, no_backup.
generate_trace_guardB
Generate hook configurations for ongoing trace prevention. Outputs JSON ready to add to settings.
Inputs: mode.
get_conversation_statsB
Get detailed statistics about Claude Code conversations including message counts, tool usage, image counts, and file sizes.
Inputs: path, sort_by, limit.
git_integrationA
Link sessions to git branches and commits. Shows which sessions are tied to which repositories.
Inputs: no named parameters.
health_checkA
Quick health check of Claude Code conversations. Reports total issues, largest files, and recommendations.
Inputs: no named parameters.
inventory_tracesA
Show complete inventory of all traces Claude Code has stored on disk, categorized by sensitivity level (critical/high/medium/low).
Inputs: project.
list_backupsB
List all backup files created by the image fixer, with size and date information.
Inputs: sort_by.
list_hooksA
List Claude Code hooks across user/project/local scopes, with validation warnings for unknown events, missing binaries, and duplicates. Optionally include the catalog of installable templates.
Inputs: include_templates, cwd.
list_profilesA
List saved ~/.claude.json profiles and the currently active one. Profiles let you switch between work/personal accounts or different orgs.
Inputs: no named parameters.
list_sessionsA
List all Claude Code sessions with health status. Shows session ID, project, size, message count, and whether the session is healthy, corrupted, empty, or orphaned.
Inputs: project.
mcp_performanceB
Track MCP server performance: call counts, error rates, most used tools.
Inputs: no named parameters.
recover_sessionA
Diagnose, repair, or extract content from a Claude Code session. Use for corrupted or crashed sessions.
Inputs: session_id (required), repair, extract.
restore_backupB
Restore a conversation file from a backup.
Inputs: backup_path (required).
run_doctorA
Full integrity check: detects corrupted JSONL lines, truncated thinking blocks, oversized images/PDFs, sessions over 50 MB, sessions-index drift, orphaned subagent directories, and stale per-session warning state files (the #13518 culprit). Set repair=true to auto-fix everything that's safely repairable.
Inputs: repair, allow_deletes.
run_maintenanceB
Run maintenance checks on Claude Code installation. Identifies issues, old backups, and archive candidates. Can optionally perform fixes automatically.
Inputs: auto.
save_profileA
Snapshot the current ~/.claude.json as a named profile so it can be restored later via switch_profile.
Inputs: name (required), overwrite.
scaffold_hookA
Install a Claude Code hook from the toolkit's template catalog. Templates: auto-fix-on-start, block-claude-md-write, log-bash-commands, redact-secrets-on-stop, delete-old-traces, snapshot-pre-compact.
Inputs: template_id (required), scope, cwd.
scan_image_issuesA
Scan all Claude Code conversation files for oversized images that cause API errors. Returns detailed report of issues found without making changes.
Inputs: path.
scan_piiC
Scan conversations for Personal Identifiable Information (PII) like emails, phone numbers, SSNs, credit cards.
Inputs: file.
search_conversationsA
Full-text search across all Claude Code conversations. Find where you discussed specific topics.
Inputs: query (required), limit, role, project.
security_scanB
Scan conversation files for leaked secrets (AWS keys, API tokens, passwords, private keys, connection strings, JWTs).
Inputs: file.
start_dashboardA
Start the web dashboard on a local port. Returns the URL to open in a browser.
Inputs: port.
switch_profileA
Swap the active ~/.claude.json with a saved profile. Auto-creates a backup of the previous active config. The user must restart Claude Code for the new config to take effect.
Inputs: name (required).
unstick_sessionA
Unstick a Claude Code session that's wedged on 'PDF too large' / 'Image too large' style errors. Scrubs oversized base64 content from the JSONL, drops per-session warning state files, and reports what was changed. After running this, the user must start a new conversation in Claude Code so it reloads the cleaned JSONL.
Inputs: session_id, no_backup.
usage_analyticsA
Generate a usage analytics dashboard showing conversation statistics, activity trends, top projects, tool usage breakdown, and media stats.
Inputs: days.
usage_reportA
Generate a real (not estimated) token usage and cost report from Claude Code's JSONL records. Returns per-model, per-project, per-day breakdowns plus a 24h/7d/30d burn rate and projected monthly spend.
Inputs: days.
validate_mcp_configA
Validate MCP server configurations. Checks JSON syntax, command existence, and optionally tests server connectivity.
Inputs: test.
wipe_tracesA
Securely wipe ALL Claude Code traces. Overwrites files with zeros before deletion. Requires explicit confirmation.
Inputs: confirm (required), keep_settings.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 40 tools
Each tool targets a distinct function with well-defined descriptions, avoiding overlap. For example, multiple trace-related tools (clean_traces, inventory_traces, wipe_traces) are clearly differentiated by purpose.
All tool names follow a consistent snake_case pattern with imperative verbs (archive, audit, check, clean, etc.) and descriptive nouns. No mixed conventions or ambiguous names.
With 40 tools, the toolkit is significantly above the typical 3-15 well-scoped range. While the breadth of functionality justifies many tools, the sheer number feels heavy and may overwhelm an agent.
The toolkit covers an extensive range of management tasks (conversations, sessions, security, backups, maintenance, MCP, profiles, hooks). Minor gaps exist, such as the absence of a direct session deletion tool, but overall the surface is comprehensive.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Shared memory and mail for your AI agents. Verified with Claude Code; other MCP clients in testing.
Monitoring + status pages set up by talking to Claude. Auto-detects 30+ SDKs and your URLs.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceThe self-hosted MCP bridge between Claude Chat and Claude Code.46AGPL 3.0
- AlicenseCqualityDmaintenanceMCP server for Claude Code self-management, enabling hot restart and context compaction commands.12MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for project planning inside Claude. It tracks progress, knows your codebase, and resumes exactly where you left off every session.9 npm5-
- AlicenseAqualityDmaintenanceMCP server that lets any agent or MCP host delegate tasks to Claude Code running headless, with tools for review, validation, analysis, and autonomous work.42MIT