Context Inspector Claude Code mod: find Claude Code context waste

Context Inspector is a community mod by YeonwooSung (my-claude-code-mods) that looks for Claude Code context waste. It keeps a ledger of everything that enters the conversation (prompts, replies, tool results, attachments) and answers three questions: what is filling the window now, why the same information keeps coming back, and what a compaction kept or lost.

It adds a status line such as ctx 62% · waste≈8.1k, where the percentage is measured and the waste is estimated. It also adds three commands. /context-inspect prints a text report with sections for overview, occupants, rereads, similar, compactions, efficiency and advice. /context-pane opens a live pane. /context-export saves the ledger as JSONL, metadata only.

The analyses are specific. Re-reads of a file are classified, for example unchanged while the earlier copy is still in the window (pure waste), after an edit, or after a compaction. Near-duplicate tool outputs are grouped by a lexical SimHash, not by meaning. After a compaction it checks whether edited and read files, errors and user identifiers still appear in the summary. The author's README requires Claude Code 2.1.287 or later.

The recording starts Claude Code with the mod loaded in the small demo project and asks Claude to read README.md and say what the project is in one sentence. When the turn ends, the footer shows context-inspector: ctx 4% · waste≈0. We then run /context-inspect. The report lists the live tokens (about 6.2k in 17 items), the top occupants by category (the skill listing, MCP instructions and deferred tools attachments), re-reads, similar outputs, compactions, efficiency and advice. In this short session nothing was read twice, so waste is zero and the advice says nothing stands out.

Use any of the methods in the install block; they install straight from the author's own marketplace. The status line appears on the next session start, after the first turn completes.

The module is one register function in hooks/register.tsx that wraps events and hands them on unchanged. Every bookkeeping step goes through a helper that swallows its own errors, so the inspector cannot break a session. A tool call is recorded before and after it runs, and the answer is returned as it came:

on('tool.call', async ($, e, next) => {
  const id = e.tool_use_id
  if (id !== undefined) safe(() => ingestToolCall(ledger, id, String(e.tool), e.agentId, e as unknown as Record<string, unknown>))
  const answer = await next(e)
  if (id !== undefined) safe(() => ingestToolResult(ledger, id, answer))
  return answer
}).catch(($, e, next) => next(e))

That excerpt is from hooks/register.tsx. Rows arrive through session.append, measured request sizes through turn.step, and compactions through session.compact. After each turn, turn.complete queues one repaint that reads $.session.usage() and writes the status line. The analysis code in hooks/core/ is plain TypeScript with only local imports, and the ledger is capped at 20,000 items.

Two options appear in /config. outputDir sets where /context-export writes; empty means ~/.claude/context-inspector. toastAdvice (on by default) shows one toast per session the first time a high-severity recommendation appears. Both commands accept arguments: /context-inspect advice shows one section, and --agents includes subagents.

We read every file the plugin can execute before running it: the manifest, hooks/hooks.json, hooks/register.tsx and all of hooks/core/, including the redaction rules. There is no package.json, install script, binary or bundled code, and the only imports are local files.

• Network, processes, daemons, telemetry: none. No fetch, no shell commands, nothing that keeps running after Claude Code exits.
• Changes the UI: the status line, a toast and the pane. Adds commands: the three above.
• Observes every tool call and row through tool.call, session.append, turn.step and session.compact. These hooks are gating hooks, but each returns the next handler's result unchanged and has a .catch fallback; nothing is blocked or rewritten. validate also notes that session.compact hooks do not run in an installed plugin where an organization manages Claude Code, unless the organization lists it.
• File writes: only on /context-export, through $.fs.write, under <outputDir>/<session id>/context-<load>-<n>.jsonl. The default is inside ~/.claude, in the plugin's own subfolder. It reads HOME to expand ~. File paths are exported as they are, and other targets are masked on a best-effort basis; the author says to review exports before sharing them.
• Prompt influence: none found. It injects no text into prompts or tool results; advice goes only to you.
• External requirements: none. License: Apache-2.0, LICENSE file present at the repo root.

claude plugin validate reported no errors and no warnings, only the notes above. The author's 102 tests passed on Claude Code 2.1.303.

Checked with Claude Code 2.1.303 on macOS (validate and tests). If the status line is missing:

• claude --version is 2.1.287 or later.
• A turn has completed; the line is painted after turn.complete.
• /context-inspect prints the report even without a status line, so use it to check that the mod is loaded.
• In the VS Code chat panel only hooks and command text work, so use /context-inspect there.

Known limits from the README: after a reload, resume or /clear the ledger starts again, and compaction survival is judged by substring match, so a paraphrased fact counts as lost.