claude-crusts: Instructions file for Claude Code

CLAUDE.md — claude-crusts: Context Window Analyzer for Claude Code

Identity

You are working on claude-crusts (the npm package name and CLI binary). The framework is called CRUSTS (always uppercase). It analyzes Claude Code's context window by classifying every token into 6 categories: Conversation, Retrieved, User, System, Tools, State. It tells users WHY their context is filling up and WHAT to do about it. Fully offline, zero API calls.

CLI Commands

Binary name: claude-crusts. Entrypoint: src/index.ts.

Slash command: /crusts inside Claude Code (via .claude/commands/crusts.md) — runs analyze and gives actionable advice.

claude-crusts analyze [session-id]              — 6-category breakdown + waste detection + recommendations
claude-crusts waste [session-id]                — Detailed waste report with per-file analysis + top 5 consumers
claude-crusts fix [session-id]                  — 3 pasteable prompt blocks (session, CLAUDE.md, /compact)
claude-crusts timeline [session-id]             — Message-by-message context growth with compaction markers
claude-crusts list                              — All discovered sessions (age, size, project)
claude-crusts compare <session-a> <session-b>   — Side-by-side comparison with per-category deltas + insights
claude-crusts lost [session-id]                 — What was lost during compaction (files, conversations, tools, instructions)
claude-crusts watch [session-id]                — Live-monitor a session with compact dashboard
claude-crusts report [session-id]               — Generate standalone report (HTML or Markdown)
claude-crusts calibrate                         — Cross-reference against /context output
claude-crusts trend                              — Cross-session trends (sparkline, averages, direction)
claude-crusts tui [session-id]                   — Interactive REPL shell with tab completion + clipboard copy
claude-crusts status [session-id] [--hook]       — One-line context health (fast path); --hook is the Stop hook body (payload on stdin, one {"systemMessage"} object out)
claude-crusts hooks enable|disable|status        — Manage the Stop status hook (enable moves the old Notification entry)
claude-crusts statusline                         — Render statusline glyph (reads Claude Code JSON on stdin)
claude-crusts statusline install|uninstall|status — Manage Claude Code statusline integration
claude-crusts optimize [session-id]              — Ranked actionable fixes with token-savings ROI (--apply to write changes)
claude-crusts models [session-id]                — Per-session model usage snapshot (one row per contiguous same-model segment)
claude-crusts doctor                             — Sanity-check the install (Claude Code, hooks, statusline, backups)
claude-crusts diff [session-id] --from <n> --to <n>  — Intra-session diff: per-category delta between two message cutpoints
claude-crusts trend --format csv [--output <path>]   — Export trend history as CSV for external analysis
claude-crusts hooks auto-inject enable|disable|status|log — Manage hook-triggered fix injection (UserPromptSubmit); `log` shows history at ~/.claude-crusts/auto-inject.log; `status` also counts the session summaries in ~/.claude-crusts/sessions
claude-crusts auto-inject                        — Internal hook target (reads stdin; emits additionalContext when hot)
claude-crusts bench compact [session-id]         — Tail the session JSONL for a /compact event; write before/after delta to JSON
claude-crusts bench reextract <result.json>      — Re-run the file-ref extractor against an existing bench result (no recompact)
claude-crusts bench compare <a.json> <b.json>    — Diff two bench-compact results (survivor file-ref set + token metrics)
claude-crusts completion <bash|zsh|pwsh>         — Emit a shell completion script (TAB completes subcommands + session IDs)