Skip to main content
Glama
Claude Code Toolkit

Claude Code Toolkit

by AsifKibria

Claude Code Toolkit

npm npm downloads license

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 tabs

Add 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-server

Then 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 PDF too large / Image too large

cct unstick

Anything weird with your install

cct doctor

Oversized images bloating disk

cct fix

Need to know your real API spend

cct usage (PAYG estimate — see disclaimer)

Multiple accounts (work / personal / clients)

cct profile save/switch

Need lifecycle automation

cct hooks list / cct hooks scaffold <id>

A leaked secret you need to find

cct security-scan

PII in old conversations

cct pii-scan

A session that crashed

cct recover <id> --repair

MCP servers that won't connect

cct mcp-validate --test

Full command reference →


Dashboard

cct dashboard                    # opens http://localhost:1405
cct dashboard --daemon           # background
cct dashboard --stop             # stop background

21 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.


MIT

Available Tools

40 tools
archive_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

    A3.5/5.0

    Scored across 40 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      The self-hosted MCP bridge between Claude Chat and Claude Code.
      46
      AGPL 3.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for project planning inside Claude. It tracks progress, knows your codebase, and resumes exactly where you left off every session.
      9 npm
      5
      -