Ccaudit

ccaudit

~5-10% of your Opus 4.7 1M-token context is gone before you type a word. (~50-108k tokens of ghost inventory - almost half a Sonnet 4.6 200k context. See snapshot below.)

Unused agents, skills, MCP servers, commands, hooks, and memory files (call them ghosts) load into context every session. ccaudit finds them, shows you the cost, and moves them to ~/.claude/ccaudit/archived/ in one command. Undo any time with ccaudit restore.

TL;DR

Solution: paste this into your terminal

claude -p "please spawn a haiku subagent to use the web tool, \
fetch the readme of this opensource project and explain to me, in very simple terms, \
what it does in 3 sentences and why I should use it (all using bullet points): \
https://github.com/fabio-dee/ccaudit"

Enough talk. Just tell me how to use it now:

npx ccaudit-cli@latest                    # full report of what's loading vs. what's used
npx ccaudit-cli --interactive             # pick exactly which ghosts to archive (TUI)
npx ccaudit-cli --dry-run                 # see the archive plan for ALL ghosts, no files touched
npx ccaudit-cli --dangerously-bust-ghosts # archive ALL ghosts (nothing deleted, undo with restore)

---

Native alternatives (and where ccaudit fits)

Claude Code ships three first-party tools that overlap with parts of what ccaudit does. None of them cover the full picture:

| Tool | Covers | Doesn't cover | | ----------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | | /skills t-sort | Skills only - list, reorder. | Agents, MCP servers, hooks, memory, commands. No token math. No archive / rollback. | | /usage | Aggregate token + cost reporting per session. | Per-component ghost identification. Doesn't tell you what to remove or move anything. | | claude plugin disable | Plugin-level on/off. | Granular agent / skill / MCP / hook visibility. No token cost. No manifest of what was disabled. |

ccaudit's differentiator: cross-component scope (agents + skills + MCP + memory + commands + hooks in one pass), regime-aware token math (eager vs deferred-tools once cc ≥ 2.1.7 flips the ToolSearch threshold), and archive-with-rollback - every action is manifest-logged and reversible via ccaudit restore.

> ccusage tells you what you spent. ccaudit tells you what's wasting it.

Current release: v1.5.1 - interactive archive picker, interactive restore picker, fuzzy-match restore by name, archive purge. See [CHANGELOG.md](./CHANGELOG.md).

The --interactive picker (v1.5) lets you tab through every category, toggle individual ghosts, and confirm before any disk write:

AGENTS │ SKILLS │ MCP SERVERS │ MEMORY │ COMMANDS
AGENTS (9/179 · 743 tok)
    ── Ungrouped ──
  ◯ brand-guardian                             65 tok  ~/.claude/agents/design/b…
  ◉ image-prompt-engineer                      97 tok  ~/.claude/agents/design/i…
› ◉ inclusive-visuals-specialist               64 tok  ~/.claude/agents/design/i…
  ◉ ui-designer                                85 tok  ~/.claude/agents/design/u…
  ◉ ux-architect                               64 tok  ~/.claude/agents/design/u…
  ◉ ux-researcher                              84 tok  ~/.claude/agents/design/u…
  ◉ visual-storyteller                        101 tok  ~/.claude/agents/design/v…
  ◉ whimsy-injector                            83 tok  ~/.claude/agents/design/w…
  ◉ ai-engineer                                95 tok  ~/.claude/agents/engineer…
  ◉ autonomous-optimization-architect          70 tok  ~/.claude/agents/engineer…
  ◯ backend-architect                          82 tok  ~/.claude/agents/engineer…
  ◯ data-engineer                              96 tok  ~/.claude/agents/engineer…
  ◯ devops-automator                           59 tok  ~/.claude/agents/engineer…
  ◯ embedded-firmware-engineer                 69 tok  ~/.claude/agents/engineer…
  ◯ frontend-developer                         66 tok  ~/.claude/agents/engineer…
↓ 165 more below
Tab ← → tabs · ↑↓ nav · / search · ? help · Space toggle · a tab-all · Enter → · q cancel
14 of 323 selected across all tabs · ≈ 3k tokens saved

> "But doesn't /context already do this?" > /context shows what's loaded right now in the current session. ccaudit shows what's been ghost-loading for weeks - agents, skills, MCP servers, and memory files you forgot you installed, silently eating your context budget every session. One is a live snapshot; the other is the longitudinal audit.

---

Upgrading from 1.3.x

Token totals will change. v1.4.0 replaces the old file-size / 4 wave with evidence-based, per-category formulas derived from Anthropic's published loading documentation and measured session logs.

Most users will see lower totals. The old formula over-counted skills and agents whose descriptions are shorter than the full file. A small number of users with many hooks may see a higher total if they pass --include-hooks (see below).

What's new

| Change | Detail | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | New category: commands | Slash commands in ~/.claude/commands/ and .claude/commands/ are now inventoried and estimated. | | New category: hooks | PreToolUse / PostToolUse / SessionStart hooks from .claude/settings.json are now surfaced. | | Hooks are advisory by default | Hook token costs are not added to the grand total unless you pass --include-hooks. The upper-bound is shown in the summary as advisory. | | New flag: --regime eager\|deferred | Override MCP regime detection (auto by default). In deferred mode a single ToolSearch overhead (~8.7k tokens) replaces per-server costs. | | New flag: --include-hooks | Add hook upper-bound tokens to the reported grand total. | | Auto-memory + import chains | ~/.claude/projects//memory/MEMORY.md auto-memory files are now surfaced. @-import chains are resolved recursively (depth ≤ 5) and each imported file appears as a separate memory row with importDepth set. |

For the full migration guide with before/after formula table see [CHANGELOG.md § 1.4.0](./CHANGELOG.md).

---

Example snapshot

A typical audit looks like this (default mode, hooks advisory, not included in total):

┌──────────────────────────────────────────────────────────────────────────────┐
│ CCAUDIT - ~64k tokens/session wasted                                         │
│ 👻 Ghost Inventory - Last 7 days                                             │
├──────────────┬──────────────┬─────────────┬──────────────────────────────────┤
│ Agents       │ Defined: 177 │ Used: 12    │ Ghost: 165 ~24k tokens/session   │
│              │              │             │ (70 in frameworks above)         │
├──────────────┼──────────────┼─────────────┼──────────────────────────────────┤
│ Skills       │ Defined: 81  │ Used: 15    │ Ghost: 66 ~2.7k tokens/session   │
│              │              │             │ (61 in frameworks above)         │
├──────────────┼──────────────┼─────────────┼──────────────────────────────────┤
│ MCP Servers  │ Defined: 5   │ Used: 1     │ Ghost: 4 ~7.0k tokens/session    │
├──────────────┼──────────────┼─────────────┼──────────────────────────────────┤
│ Memory Files │ Loaded: 12   │ Active: 1   │ Stale: 11 ~55k tokens/session    │
├──────────────┼──────────────┼─────────────┼──────────────────────────────────┤
│ Commands     │ Defined: 45  │ Used: 8     │ Ghost: 37 ~1.4k tokens/session   │
│              │              │             │ (36 in frameworks above)         │
├──────────────┴──────────────┴─────────────┴──────────────────────────────────┤
│                                                                              │
│ Total ghost overhead: ~64k tokens (~32% of 200k context window)              │
│ (global: ~62k tokens + worst project ~/projects/my-project: ~2.1k tokens)   │
│ Health grade: D (Poor)                                                       │
│ Hooks (advisory - not included in total): ~18k tokens upper-bound (9 hooks) │
│ Pass --include-hooks to add to grand total.                                  │
│ 💡 Potential savings after ccaudit --dangerously-bust-ghosts: ~64k           │
│ tokens/session reclaimed                                                     │
│ [████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 32%                    │
└──────────────────────────────────────────────────────────────────────────────┘

Show your ghost score

Share your audit results in the GitHub Discussion

---

With --include-hooks the hooks row is promoted into the main table and added to the grand total:

├──────────────┼──────────────┼─────────────┼──────────────────────────────────┤
│ Hooks        │ Defined: 9   │ Used: 2     │ Ghost: 7 ~18k tokens/session     │
├──────────────┴──────────────┴─────────────┴──────────────────────────────────┤
│ Total ghost overhead: ~81k tokens (~41% of 200k context window)              │

Numbers will vary by setup, but the pattern is the same: defined inventory, actual usage, wasted tokens, and the worst-case overhead that would hit a single session.

---

After --dangerously-bust-ghosts:

----------------------------------------------
  ccaudit --dangerously-bust-ghosts

  Before (from dry-run 2026-04-13T08:19:58Z): ~108k tokens loaded per session
  After:   ~12k tokens
  Freed:   ~96k tokens (48% of context window)

  Health:  23/100 --> 91/100

  Archived: 116 agents, 74 skills
  Disabled: 4 MCP servers
  Flagged:  6 memory files

  npx ccaudit-cli@latest
----------------------------------------------

Manifest: ~/.claude/ccaudit/manifests/2026-04-06T14:26:00Z.json
Restore anytime: ccaudit restore

---

Interactive mode

ccaudit ghost --interactive (short: -i) opens a TUI picker for selective archival. Instead of archiving every ghost in one shot, you scroll six category tabs, pick exactly what to archive, and confirm on a single screen. Requires a TTY; non-TTY sessions fall back to --dry-run and --interactive combined with --json is a hard error.

npx ccaudit-cli ghost --interactive

The picker

┌─ Archive ghosts ─────────────────────────────────────────────────────┐
│ [ agents (3/12) ] [ skills (0/8) ] [ mcp (1/2) ] [ memory (0/4) ]    │
│ [ commands (0/5) ]                                                    │
├──────────────────────────────────────────────────────────────────────┤
│ ◉ code-reviewer          agent    ~1.2k  28d stale                   │
│ ◯ pencil-dev             agent    ~0.9k  44d stale                   │
│ ◉ doc-writer             agent    ~1.5k  91d stale                   │
│ [🔒] gsd-planner         agent    ~2.1k  Part of GSD (3 used,        │
│                                          9 ghost). --force-partial   │
│ ◉ playwright  ⚠          mcp      ~3.8k  Also in: ./project-b/.mcp   │
│ ↓ 2 more                                                             │
├──────────────────────────────────────────────────────────────────────┤
│ 5 of 32 · ≈ 8.4k tokens saved   Space toggle  /  filter  ?  help     │
└──────────────────────────────────────────────────────────────────────┘

> Hook archival deferred - selectable archive coming in a future phase.

The confirmation screen

┌─ Confirm archive ────────────────────────────────────────────────────┐
│                                                                      │
│  Archive the following 5 ghosts?                                     │
│                                                                      │
│    agents:    3  (code-reviewer, doc-writer, +1 more)                │
│    mcp:       1  (playwright)                                        │
│    skills:    1  (my-skill)                                          │
│                                                                      │
│  Estimated savings: ≈ 8.4k tokens per session                        │
│  Manifest:          ~/.claude/ccaudit/manifests/bust-*.jsonl         │
│                                                                      │
│  [ Archive ]   [ Cancel ]                                            │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

Keybinds

| Key | Action | | ---------------------- | ----------------------------------------------- | | Space | Toggle selection of focused row | | a | Toggle-all within the active tab | | / | Filter by case-insensitive substring | | s | Cycle sort (staleness → tokens → name) | | ? | Help overlay (canonical full keybind list) | | Tab / Shift-Tab | Cycle tabs forward / back with wrap | | ← / → | Same as Tab / Shift-Tab | | 1–6 | Jump directly to a visible tab | | Enter | Confirm selection and proceed to confirm screen | | Esc / Ctrl+C / q | Cancel with "No changes made." (exit 0) |

Framework-protected rows render dimmed with a [🔒] glyph and are not selectable by default - pass --force-partial to unlock them for the current run (a --force-partial active: framework protection DISABLED. Partial framework splits may corrupt dependent setups. banner appears at the top of the picker). See CLAUDE.md's Safety invariants section for the full rationale behind framework-as-unit protection.

Rollback: ccaudit restore moves everything back. v1.5 adds restore --interactive, a mirror of the archive picker listing every archived item across all manifests (deduplicated, newer-wins) so you can restore a subset. restore --name and restore --all-matching add fuzzy single-match and bulk-match restore by name. See the restore section below.

---

Commands

| Command | What it does | Notable options | | --------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fabio-dee
• Source: fabio-dee/ccaudit
• License: MIT

Install and usage instructions live in the source repository linked above.