CRUSTS

Your Claude Code context has crusts. CRUSTS trims them.

Stale file reads, duplicate tool schemas, resolved exchanges nobody needs,
oversized CLAUDE.md files, unused MCP servers — the crusts of your session.
CRUSTS finds them, ranks them by token savings, and trims them for you.

Quickstart · Before/After · Commands · Why · Framework

Fully offline. Zero API calls. Zero token cost.

Before / After

Same work session. Same files read, same tools loaded, same conversation. One claude-crusts optimize --apply + one /compact focus "..." command it generated.

TOTAL:  143,507 / 200,000  (71.8%)
  Tools         86,460  (60%)
  Retrieved     35,996  (25%)
  Conversation   7,616   (5%)
  System         7,319   (5%)
  User           4,217   (3%)
  State          1,899   (1%)

"index.ts" read 9 times
"types.ts" read 6 times
11 of 22 loaded tool schemas unused
Auto-compaction in ~12 msgs

Context health: HOT

TOTAL:   92,108 / 200,000  (46.1%)
  Retrieved     33,801  (37%)
  Tools         18,204  (19%)
  Conversation   7,616   (8%)
  System         7,319   (8%)
  User           3,421   (4%)
  State          1,747   (2%)

No duplicate reads
Stale reads trimmed
Tool schemas pruned (.claudeignore)
Auto-compaction in ~180 msgs

Context health: HEALTHY

Same session. 51K tokens reclaimed. Same work. Fewer crusts.

┌──────────────────────────────────────────────┐
│  CONTEXT FRESHNESS      ████████ CRISP       │
│  DUPLICATE FILE READS   ░░░░░░░░ PURGED      │
│  UNUSED TOOL SCHEMAS    ░░░░░░░░ REMOVED     │
│  SELF-HEALING HOOK      ████████ LIVE        │
│  OFFLINE / API-FREE     ████████ 100%        │
│  VIBES                  ████████ TOASTY      │
└──────────────────────────────────────────────┘

Three commands cover 90% of day-to-day use. You can stop reading right there if those do what you need — the rest of this README is the deep dive.

# 1. SELF-HEAL — install the hook. Your context silently self-heals from
#    now on: when usage crosses the threshold, CRUSTS writes the perfect
#    /compact focus command and surfaces it in Claude's reply. You paste.
claude-crusts hooks auto-inject enable

# 2. ACTIVE FIX — write .claudeignore + CLAUDE.md rules for you.
#    Atomic backups under ~/.claude-crusts/backups/, per-fix confirmation.
claude-crusts optimize --apply

# 3. TUI — the REPL shell where every other command lives.
#    This is the recommended day-to-day entry point. No flags to memorise.
claude-crusts tui

Start with the TUI. It's the smoothest way to use CRUSTS — an interactive shell with tab completion, clipboard copy for fix blocks, and every analysis / management command in one place. Everything below is for scripting, CI, and power-user flows.

What CRUSTS does. Slices your Claude Code context window into 6 categories — Conversation, Retrieved, User, System, Tools, State/memory — finds the crusts (what's gone stale or never got used), and trims them for you.

Real output from a real session (a 1M-window Fable 5 run with one compaction behind it):

╔══════════════════════════════════════════════════════════════╗
║  CRUSTS Context Window Analysis                              ║
║  Session: 34ac6b07 | Model: claude-fable-5                   ║
║  Messages: 281 | Duration: 216h 43m                          ║
║  1 compaction(s) detected — showing current context          ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  C  Conversation       17,873 tkns  (14.7%)  ██░░░░░░░░░░░░░░║
║  R  Retrieved           4,034 tkns   (3.3%)  █░░░░░░░░░░░░░░░║
║  U  User Input             39 tkns   (0.0%)  ░░░░░░░░░░░░░░░░║
║  S  System             40,004 tkns  (33.0%)  █████░░░░░░░░░░░║
║  T  Tools              55,295 tkns  (45.6%)  ███████░░░░░░░░░║
║  S  State/Memory        4,066 tkns   (3.4%)  █░░░░░░░░░░░░░░░║
║  ──────────────────────────────────────────────────────────  ║
║  TOTAL: 121,311 / 1,000,000 tokens (12.1%)                   ║
║  FREE:  878,689 tokens                                       ║
║                                                              ║
║  Session lifetime: 237,324 tokens across 281 messages        ║
║                                                              ║
║  RECOMMENDATIONS:                                            ║
║     MCP: 7 server(s) connected, none invoked                 ║
║     Messages until auto-compaction: ~801                     ║
║     Run `claude-crusts waste` for full details               ║
║                                                              ║
║  Context health: HEALTHY                                     ║
║                                                              ║
║  Derived from this session's API data:                       ║
║    Internal system prompt: ~20,389 tokens                    ║
║    Message framing: ~23 tokens/msg (11 samples)              ║
║  Run `claude-crusts calibrate` for ground truth comparison.  ║
╚══════════════════════════════════════════════════════════════╝

The category buckets are reconciled to the API's own window total, so they sum to the TOTAL line exactly. Note the window: CRUSTS resolved 1,000,000 tokens from the session's own signals, not a hardcoded 200K.

Fully offline. Zero API calls. Zero token cost.

Core capabilities:

• Auto-inject — hooks auto-inject enable installs a hook that writes a session-specific /compact focus command and surfaces it in Claude's next reply when the window nears Claude Code's auto-compaction trigger (or your configured threshold). You paste, Claude runs it, context drops. Every fire logged to ~/.claude-crusts/auto-inject.log for audit.
• Active optimization — optimize --apply writes .claudeignore and CLAUDE.md rules for you, with confirmation prompts and backups under ~/.claude-crusts/backups/.
• 6-category context breakdown — Conversation, Retrieved, User, System, Tools, State/Memory. See exactly where your tokens are going.
• Waste detection — duplicate file reads, unused tool schemas, stale content, resolved exchanges, cache overhead, unused tool results.
• Past-session analysis — Claude Code forgets everything when you exit. The JSONL logs don't. Analyze any session from days or weeks ago.
• Cross-session trends — sparklines, direction (improving / worsening / flat), recent-session table.
• Interactive TUI — claude-crusts tui drops you into a REPL shell with tab completion for commands and session IDs.
• Reports — standalone HTML/Markdown reports you can screenshot or share.
• Other: cross-session comparison, calibration against /context, install sanity check (doctor), intra-session diff, per-model usage snapshot (models), statusline glyph integration, per-MCP-server token accounting, CSV trend export, configurable waste thresholds, /compact measurement harness (bench compact / bench compare).

Table of Contents

Get started

• The fastest way to start — drop into the TUI
• Installation — npx, npm, bun
• Quick Start — every command in one glance
• Use inside Claude Code — /crusts slash command

CLI reference (all 23 commands)

• Interactive: tui
• Analysis: analyze · waste · fix · optimize · models · timeline · lost · diff · compare · trend · status
• Live: watch · report · list
• Auto-fix + active rules: hooks auto-inject · optimize --apply
• Claude Code integration: hooks · statusline · calibrate
• Install management: doctor
• Measurement harness: bench compact · bench compare · bench reextract
• Config: Customising waste thresholds

Under the hood

• The CRUSTS framework — what the 6 categories mean
• How it works — offline parsing, derived overhead, token estimation
• What the Claude Code leak revealed — the architectural insights CRUSTS uses
• CRUSTS vs /context — when to use which
• Why CRUSTS? — the questions behind the number
• Recommendations in action — example outputs
• Accuracy and limitations — what's exact vs estimated

Meta

• Contributing · Feedback · License

The Fastest Way to Start

If you're new to CRUSTS, skip the flag-heavy CLI and just run:

claude-crusts tui

This drops you into an interactive shell that:

• Auto-selects your most recent Claude Code session
• Tab-completes both commands and session IDs
• Runs every analysis / management command by name — no flags to remember
• Copies fix blocks to your clipboard with copy 1|2|3
• Type help for the full command list, quit to exit

Once you're inside, here's everything you can type:

  CRUSTS Interactive Shell
  Type a command, or "help" for a list of commands.

  ID        Age   Size     Project
  a1b2c3d4  2m    1.2 MB   my-project
  e5f6a7b8  1h    856 KB   another-project
  ...

  Auto-selected most recent session: a1b2c3d4 (my-project)
  Use "select <id>" to switch, or type a command.

crusts:a1b2c3d4> analyze                  # full 6-category breakdown
crusts:a1b2c3d4> waste                    # waste detection report
crusts:a1b2c3d4> fix                      # pasteable fix prompts
  Tip: use "copy 1", "copy 2", or "copy 3" to copy a block to clipboard.

crusts:a1b2c3d4> copy 2                   # copy CLAUDE.md snippet to clipboard
  Copied CLAUDE.md snippet to clipboard.

crusts:a1b2c3d4> optimize                 # ranked fixes with ROI (dry-run)
crusts:a1b2c3d4> models                   # per-model usage snapshot
crusts:a1b2c3d4> timeline                 # message-by-message growth
crusts:a1b2c3d4> diff 40 120              # intra-session delta
crusts:a1b2c3d4> lost                     # what was lost in compaction
crusts:a1b2c3d4> status                   # one-line health check
crusts:a1b2c3d4> compare e5f6a7b8         # compare with another session
crusts:a1b2c3d4> doctor                   # sanity-check the install
crusts:a1b2c3d4> hooks status             # hook install state
crusts:a1b2c3d4> auto-inject status       # self-healing state
crusts:a1b2c3d4> bench compare a.json b.json
crusts:a1b2c3d4> bench reextract blind.json
crusts:a1b2c3d4> trend                    # cross-session trends
crusts:a1b2c3d4> list                     # show all sessions
crusts:a1b2c3d4> select e5f6              # Tab completes session IDs
crusts:a1b2c3d4> help                     # show available commands
crusts:a1b2c3d4> quit                     # exit

CLI-only commands (don't fit the REPL model): optimize --apply (spawns its own readline confirmation dialog), bench compact (blocks for minutes tailing a JSONL), watch, calibrate, report. Run those from a separate shell.

The rest of this README documents the standalone CLI for scripting, CI, and advanced use. But for day-to-day use, tui is the recommended entry point.

Installation

# Run directly without installing
npx claude-crusts analyze

# Or install globally
npm install -g claude-crusts

# With bun
bunx claude-crusts analyze
bun install -g claude-crusts

Shell completion (optional)

Tab-completes subcommands and session IDs at your prompt. One-time install, per shell:

# bash
claude-crusts completion bash >> ~/.bashrc && source ~/.bashrc

# zsh
claude-crusts completion zsh  >> ~/.zshrc  && source ~/.zshrc

# PowerShell — append to $PROFILE to persist across sessions
claude-crusts completion pwsh >> $PROFILE
. $PROFILE

After installing: claude-crusts an<TAB> → analyze, claude-crusts analyze 9b2<TAB> → expands to the full session ID.

Quick Start

Start with the TUI — the other commands are here for scripting, CI, and power users.

# Friction reducers (install once, benefit every session):
claude-crusts hooks auto-inject enable        # self-healing context
claude-crusts optimize --apply                 # writes .claudeignore + CLAUDE.md
claude-crusts statusline install               # ambient health glyph

# Day-to-day:
claude-crusts tui                              # interactive shell (recommended)
claude-crusts analyze                          # 6-category breakdown
claude-crusts waste                            # waste detection report
claude-crusts status                           # one-line health check

# Analysis & forensics:
claude-crusts fix                              # pasteable fix prompts
claude-crusts timeline                         # message-by-message growth
claude-crusts lost                             # what was lost in compaction
claude-crusts diff --from 40 --to 120          # intra-session delta
claude-crusts models                           # per-model usage snapshot
claude-crusts compare <a> <b>                  # side-by-side session diff
claude-crusts trend                            # cross-session trends
claude-crusts watch                            # live-monitor a running session
claude-crusts report                           # standalone HTML or Markdown report
claude-crusts calibrate                        # ground-truth against /context

# Measurement (for A/B experiments around /compact):
claude-crusts bench compact                    # tail JSONL, capture before/after
claude-crusts bench compare a.json b.json      # diff two bench results

# Management:
claude-crusts doctor                           # install sanity check (9 checks)
claude-crusts hooks enable                     # one-line health after every response

Use Inside Claude Code

The easiest way to use CRUSTS — type this inside any Claude Code session:

/crusts

That's it. Claude Code runs the analysis and tells you what to do — which files to stop re-reading, whether to /compact now or wait, and the exact command to paste. No copy-paste, no switching terminals.

This works automatically when you clone or install claude-crusts, because the slash command lives at .claude/commands/crusts.md in the repo.

Two ways to use CRUSTS — they complement each other:

Use /crusts when you want a quick answer without leaving your session. Use the CLI when you want the full picture without spending tokens on it.

CLI Commands

claude-crusts tui [session-id]

Interactive REPL shell. Browse sessions, run analysis commands, switch sessions, and compare — all without leaving the app. Features Tab completion for both commands and session IDs, plus clipboard copy for fix blocks.

claude-crusts tui                    # launch, auto-selects latest session
claude-crusts tui a1b2c3d4           # launch with a specific session pre-selected

See The Fastest Way to Start at the top for the full walkthrough of every command you can type inside the shell. Below are the details that don't belong in a quickstart:

Tab completion works for both commands and session IDs. Type sel + Tab to complete select, then type the first few characters of a session ID and press Tab to auto-fill it. Works with select and compare commands.

Clipboard copy lets you quickly grab fix blocks after running fix. Each block is numbered — use copy 1 (session prompt), copy 2 (CLAUDE.md snippet), or copy 3 (/compact command). Works on Windows (clip), macOS (pbcopy), and Linux (xclip/xsel).

claude-crusts analyze [session-id]

Full CRUSTS breakdown of a session. Shows token counts per category, waste detection, and actionable recommendations.

claude-crusts analyze              # most recent session
claude-crusts analyze a1b2c3d4     # by session ID prefix
claude-crusts analyze --json       # machine-readable output

If no session ID is provided, analyzes the most recent session.

claude-crusts waste [session-id]

Deep dive into waste detection. Groups issues by severity and shows estimated reclaimable tokens.

claude-crusts waste
claude-crusts waste e5f6a7b8       # any past session

Real output from the same session as the analyze example above:

  Waste Detection Report
  Session: 34ac6b07 | Messages: 281

  11 issue(s) found — ~6,850 tokens reclaimable (5.6%)

  ── LOW (10) ──

  [LOW] Bash result at message #113 (~1503 tokens) appears unused by assistant ~1,503 tkns
    → Consider whether this tool call was necessary. Unused results waste context space.

  [LOW] Bash result at message #85 (~1128 tokens) appears unused by assistant ~1,128 tkns
    → Consider whether this tool call was necessary. Unused results waste context space.

  ── INFO (1) ──

  [INFO] Cache reads are 89.3% of total input — system prompt + tool schemas are re-sent every turn ~0 tkns
    → Reduce CLAUDE.md size and disable unused MCP servers to lower per-turn cache cost.

  ── RECOMMENDATIONS ──

  P3 Top 5 context consumers:
          1. Tool schemas (22 loaded, 11 used) — 22,500 tokens
          2. System prompt (CLAUDE.md 1,294 + internal 20,389) — 21,683 tokens
          3. Compaction summary (compressed context from 199,326 tokens) — 3,413 tokens
          4. Memory files (56 file(s)) — 2,345 tokens
     These items consume the most context window space in your current session.

  P5 MCP: 7 server(s) connected, none invoked
     MCP tools are loaded on-demand — no upfront token cost for connected but unused servers.

  Context health: HEALTHY
  Messages until auto-compaction: ~801

Detects:

• Duplicate file reads — which files, how many times, which messages, estimated wasted tokens
• Unused tools — which of the loaded tool schemas (core plus any ToolSearch-loaded deferred tools) were never invoked; deferred tools that were never loaded cost nothing and are never counted against you
• Cache overhead — what percentage of your input is re-reading the same cached content every message
• Oversized system prompt — when CLAUDE.md is large enough to consider splitting
• Compaction patterns — how often you're hitting auto-compaction and what to do about it

claude-crusts fix [session-id]

The headline feature. Generates three pasteable text blocks — one for your current session, one for your CLAUDE.md, and one /compact command — all tailored to your session's actual waste patterns. No LLM involved.

claude-crusts fix                  # fix for most recent session
claude-crusts fix e5f6a7b8         # fix for any past session

CRUSTS Fix — Session a1b2c3d4

1. Paste this into your current Claude Code session:

┌────────────────────────────────────────────────────────────────┐
│ Important: these files are already in your context from        │
│ earlier reads. Do NOT re-read them. Reference your earlier     │
│ reads instead:                                                 │
│ - renderer.ts (already read, at messages #5, #160, #180)       │
│ - classifier.ts (already read, at messages #4, #38, #41, #46)  │
│ - recommender.ts (already read, at messages #149, #210)        │
│                                                                │
│ If you need to check something in these files, say "based on   │
│ [filename] that you already read" instead of reading the file  │
│ again.                                                         │
└────────────────────────────────────────────────────────────────┘

2. Add this to your CLAUDE.md for future sessions:

┌────────────────────────────────────────────────────────────────┐
│ ## Key Project Files                                           │
│ These files are frequently referenced. Read each once at the   │
│ start of a session, then reference from memory:                │
│ - renderer.ts: [describe what this file does]                  │
│ - classifier.ts: [describe what this file does]                │
│ - recommender.ts: [describe what this file does]               │
│                                                                │
│ ## Session Management                                          │
│ - Keep sessions under 200 messages when possible               │
│ - Use /clear between distinct tasks                            │
│ - Run /compact proactively at 60% context usage                │
└────────────────────────────────────────────────────────────────┘

3. Run this command now:

┌────────────────────────────────────────────────────────────────┐
│ /compact focus on the renderer.ts, classifier.ts, types.ts     │
│ changes                                                        │
└────────────────────────────────────────────────────────────────┘

Every output is generated from your session data — different sessions produce different files, different urgency levels, and different CLAUDE.md advice.

claude-crusts optimize [session-id]

Closes the last-mile friction of fix. Instead of three generic blocks to copy-paste, optimize generates a ranked list of fixes with token-savings ROI, and the safe ones can be applied directly with --apply (backed up to ~/.claude-crusts/backups/).

claude-crusts optimize                           # dry-run, ranked report
claude-crusts optimize --apply                   # apply with per-fix confirmation
claude-crusts optimize --apply --yes             # apply without prompting (use with care)
claude-crusts optimize --min-savings 500         # hide fixes below 500 tokens
claude-crusts optimize --filter claudeignore,compact-focus

CRUSTS Optimize — session a1b2c3d4
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total saveable: 1