<p align="left">
  <img src="assets/icon-128.png" width="96" height="96" alt="Claude Code Toolkit logo"/>
</p>

# Claude Code Toolkit

[![npm](https://img.shields.io/npm/v/@asifkibria/claude-code-toolkit.svg)](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit)
[![npm downloads](https://img.shields.io/npm/dm/@asifkibria/claude-code-toolkit.svg)](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit)
[![license](https://img.shields.io/badge/license-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Maintenance, recovery, and observability for Claude Code. CLI + MCP server + dashboard.

---

## TL;DR — fix, monitor, manage

```bash
# 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:

```bash
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`](docs/slash-commands.md).

---

## 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 →](docs/commands.md)

---

## Dashboard

```bash
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](https://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 →](docs/mcp-tools.md)

---

## 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

- [npm](https://www.npmjs.com/package/@asifkibria/claude-code-toolkit) · [GitHub](https://github.com/asifkibria/claude-code-toolkit) · [Issues](https://github.com/asifkibria/claude-code-toolkit/issues)

MIT