context-audit

name

context-audit

description

Analyze Claude Code session transcripts for repeated full-file reads, large re-derived tool output, and other context-cost waste; recommend small scripts (like .claude/scripts/extract-section.sh) and, where a waste pattern is a repeated bypass of an existing convention, propose a list of concrete fixes (a hook, a convention edit) rather than a script alone. Use when the user asks to "audit context cost", "reduce context bloat", "what scripts should we add", "analyze tool usage", or invokes /context-audit.

Context cost audit

Concise, compact, facts only.

Read-only. Never write a script — recommend, user decides (a script is a maintenance commitment; same "ask before" spirit as AGENTS.md's scope boundaries).

1. Find the transcripts

~/.claude/projects/<project-slug>/*.jsonl, one per session, JSON Lines. <project-slug> = cwd with / → -. Ask scope — this session, last N, all — default last 5.

2. Tally tool usage

Per session: every Read input.file_path, Bash input.command, Grep input.pattern/input.path. jq only:

jq -r 'select(.message.content != null) | .message.content[]?
  | select(.type=="tool_use" and .name=="Read") | .input.file_path' \
  ~/.claude/projects/<slug>/*.jsonl | sort | uniq -c | sort -rn

Same for Bash (.input.command) and Grep (.input.pattern).

2b. Rank cost by tool

Which tool's results eat most context, not which is called most. Join each tool_result to its tool_use by id, sum result size per tool, sort descending:

jq -s '
  ( [.[] | .message.content[]? | select(.type=="tool_use") | {key: .id, value: .name}] | from_entries ) as $names
  | [.[] | .message.content[]? | select(.type=="tool_result") | {name: ($names[.tool_use_id] // "unknown"), size: ((.content | tostring) | length)}]
  | group_by(.name) | map({name: .[0].name, calls: length, chars: (map(.size) | add)})
  | sort_by(-.chars)[]
  | "\(.name)\t\(.calls) calls\t~\(.chars/4|floor) tokens"
' ~/.claude/projects/<slug>/*.jsonl

chars/4 is rough, good enough for ranking. Bash near the top → drill into which commands (section 2) drive it; that's section 3's script-candidate list.

3. Flag waste patterns

• Full-file re-read, same file, ≥3 times in one session, no Edit between two of them. Check the file's structure (headings, JSON keys, log sections) against what was quoted after each Read — only one part ever used = extract-section.sh candidate (or jq/awk slice for JSON/log). .claude/scripts/token-rank.sh <file>... (if present) ranks repeat offenders by cost.
• Large file (wc -l) read whole when the same heading/keyword recurs across sessions — same pattern over time.
• Repeated identical Bash command — deterministic output (git log, version check) re-run instead of reasoned from context. Behavioral fix, not a script; note separately.
• Grep with a large match count, re-run later with -l/path filter — narrowing came a call too late.
• Bash dominates section 2b — a raw gh/git/curl/API command dumping full JSON/log when only a few fields get used is a script candidate shaped like .claude/scripts/failed-workflow.sh/issue-view.sh (compact, pre-filtered). Require repetition across sessions before recommending.

4. Report

Ranked table: file/pattern, count, rough cost (lines × occurrences for Reads), proposed fix. One line each, no praise, no summary. Precede with section 2b's per-tool ranking, unabridged. .claude/scripts/extract-section.sh (if present) already covers markdown-heading slicing — recommend extending its use, never a duplicate. New script only when the data shape doesn't fit (JSON, log tail, CSV column).

5. Propose enforcement when the pattern is a bypassed convention

A recurring waste pattern that AGENTS.md/AGENTS.core.md Conventions already forbid (e.g. raw Bash cat of a whole .md/large file when extract-section.sh/sed -n/Read exist) is not a missing script — the fix exists and is routed around. For each, propose as a numbered list, most costly first:

• A PreToolUse hook detecting the exact bypass shape at the tool-call boundary and denying with a message pointing at the intended path — shape of .claude/scripts/hook-guard-shell.sh if present (ls .claude/scripts/hook-guard-*.sh; extend an existing guard covering an overlapping shape before adding one). State matcher (tool name), detection condition, redirect message.
• A convention-wording gap, if the bypass happened because the bullet didn't cover the observed shape (wrong tool, file type, ambiguous wording) — quote current bullet and proposed edit.

One line each: pattern → proposed fix → which file changes (.claude/settings.json + new/edited .claude/scripts/hook-guard-*.sh, or the Conventions bullet). Create or edit nothing; list, let the user approve.