Prompt Cache Audit

Trigger: /cache-audit or "audit my caching" or "check my cache setup"

What it does: Reads your live Claude Code configuration and measures it against prompt caching best practices. Returns a scored report with specific, actionable fixes ranked by token savings.

Background: The API caches the prefix of each request (system prompt, tool definitions, CLAUDE.md, rules, skill registry, MEMORY.md). An identical prefix between turns = ~90% cost reduction on those tokens. ANY change to the prefix invalidates everything after the change point.

When Invoked

Run ALL 8 checks automatically. Do NOT ask for confirmation. Read the relevant files, measure sizes, and produce the full report in one pass.

Use $PROJECT to refer to the current working directory throughout.

The 8 Checks

Check 1 — Prefix Ordering (Static Before Dynamic)

Read: ~/.claude/CLAUDE.md , $PROJECT/CLAUDE.md , ~/.claude/rules/.md , $PROJECT/.claude/rules/.md , and the MEMORY.md file for the current project (find it under ~/.claude/projects/*/memory/MEMORY.md — match by project path).

Flag any dynamic content in these files:

• Timestamps, new Date() , hardcoded dates that go stale

• Git refs, commit hashes, branch names

• Session IDs, task IDs, "currently working on X"

• File counts, line counts, or any computed metrics

• currentDate entries in MEMORY.md

These files are part of the static prefix. Dynamic data here means cache misses on every turn where it changes.

Scoring:

• PASS: All prefix files contain only static instructions and conventions

• WARNING: Low-frequency dynamic data (e.g., a date updated daily)

• FAIL: High-churn content (timestamps, computed values) in any prefix file

Check 2 — Hook Injection Pattern

Read: ~/.claude/settings.json and $PROJECT/.claude/settings.json to find all hook commands. Then read each referenced hook file.

For each hook, verify:

• Hooks that inject context MUST use additionalContext in their JSON output (this becomes a <system-reminder> message — part of the message history, NOT the prefix)

• Hooks that only log/backup should produce no hookSpecificOutput at all

Specifically flag:

• Any hook that opens and writes to CLAUDE.md, MEMORY.md, or rule files mid-session

• Any hook that modifies tool definitions or the system prompt directly

• Any hook that uses hookSpecificOutput keys other than additionalContext

Check each hook and report its pattern:

Hook Event Expected Pattern

SessionStart additionalContext with compact git context OR no output

UserPromptSubmit Logging only, no additionalContext

PreCompact Logging/backup only, no context injection

All others (Stop, SessionEnd, Notification, etc.) No prefix modification

Scoring:

• PASS: All hooks use additionalContext or no-inject patterns

• FAIL: Any hook modifies prefix files (CLAUDE.md, rules, MEMORY.md) mid-session

Check 3 — Tool Stability

Read: ~/.claude.json for global MCP servers, $PROJECT/.mcp.json for project MCP servers (if exists).

Measure and report:

• Total MCP server count (global + project-level)

• Each server name and whether it's deduplicated across levels

Flag:

• Same MCP server name at both global and project level (tool schema loaded twice?)

• Any skill that explicitly adds or removes tools when invoked

8 total MCP servers (each adds tool schema tokens to the prefix)

Note: MCP tools use deferred loading via ToolSearch by default — this is the correct pattern. Stubs are lightweight; full schemas load on demand.

Scoring:

• PASS: Fixed tool set at session start, no conditional loading

• WARNING: > 8 MCP servers (consider if all are needed per-project)

• FAIL: Dynamic tool add/remove detected mid-conversation

Check 4 — Model Consistency

Read: ~/.claude/settings.json for model or alwaysThinkingEnabled fields.

Check:

• Is there a stable model configuration? (Default model is fine if consistent)

• Do any agent definitions (.claude/agents/*.md ) specify different model: in frontmatter for inline use?

• Subagent model delegation (Task tool with model: parameter) is FINE — separate conversations don't break parent cache

Scoring:

• PASS: Consistent model per conversation, subagents handle model switching

• FAIL: Evidence of inline model switching in same conversation thread

Check 5 — Dynamic Content Size

Measure actual injection sizes. For each source, read the hook code and estimate output:

Source How to Measure PASS WARNING FAIL

SessionStart hook Read code — estimate additionalContext output chars < 200 200–2K

2K

UserPromptSubmit hook Read code — does it emit additionalContext ? No output < 500

500

Built-in git status Run git status --porcelain | wc -c

< 2K 2–10K

10K

Use ~4 chars per token as the conversion estimate.

Also report:

• Total hook count across all events (each hook = execution latency per trigger)

• Any hook with timeout > 10 seconds

Overall scoring:

• PASS: All per-turn injections total < 2K chars

• WARNING: 2–10K chars per turn

• FAIL: > 10K chars injected per turn into the main conversation

Check 6 — Fork Safety (Compaction & Subagents)

Read: PreCompact hook code.

Verify:

• PreCompact hook does NOT modify the prefix (logging/backup only is correct)

• No custom compaction logic that rebuilds the system prompt differently

• Claude Code's built-in compaction preserves system prompt + tools by default

Scoring:

• PASS: Using built-in compaction + additionalContext -only hook injection

• FAIL: Any hook modifies prefix during compaction or subagent spawn

Check 7 — Static Prefix Budget

This is the most actionable check. Measure every component of the static prefix.

Read and measure (report in chars AND estimated tokens at ~4 chars/token):

Component How to Find

CLAUDE.md (global) ~/.claude/CLAUDE.md

CLAUDE.md (project) $PROJECT/CLAUDE.md

Rules (global) Each file in ~/.claude/rules/*.md

Rules (project) Each file in $PROJECT/.claude/rules/*.md

MEMORY.md Match current project under ~/.claude/projects/*/memory/MEMORY.md

Use wc -c via Bash to measure file sizes. Measure EACH file individually.

Calculate:

• Grand total chars across all measured files

• Estimated tokens (chars / 4)

• Percentage of 200K context window consumed by static prefix

Report the top 5 largest individual files.

Scoring:

• PASS: Total static prefix < 60K chars (~15K tokens, ~7.5% of context)

• WARNING: 60–120K chars (~15–30K tokens, 7.5–15% of context)

• FAIL: > 120K chars (~30K tokens, > 15% of context)

Check 8 — Rule Layer Efficiency

Read: List filenames in ~/.claude/rules/ and $PROJECT/.claude/rules/ .

Key fact: Rules at both levels are additive — Claude Code loads ALL of them. This means duplicate filenames = duplicate content = wasted tokens.

Check for:

• Any filename that exists at BOTH ~/.claude/rules/ and $PROJECT/.claude/rules/ — these load twice

• For each duplicate, read both versions and estimate content overlap

• Whether the project uses a single project-implementation.md for overrides (correct pattern) vs. many files that duplicate user-level rules

The correct pattern:

• User-level (~/.claude/rules/ ): Generic patterns — the WHAT (applies to all projects)

• Project-level ($PROJECT/.claude/rules/ ): Single project-implementation.md — the HOW (framework-specific overrides)

Scoring:

• PASS: No duplicate filenames, project uses project-implementation.md only

• WARNING: 1–3 duplicate files

• FAIL: > 3 duplicate files — significant token waste from additive loading

Output Format

After running all 8 checks, output this exact report format:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PROMPT CACHE AUDIT ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Score: X/8

[✅/⚠️/❌] Check 1 — Prefix Ordering: [PASS/WARNING/FAIL] → [finding]

[✅/⚠️/❌] Check 2 — Hook Injection: [PASS/WARNING/FAIL] → [each hook and its pattern]

[✅/⚠️/❌] Check 3 — Tool Stability: [PASS/WARNING/FAIL] → [N global + N project MCP servers, any issues]

[✅/⚠️/❌] Check 4 — Model Consistency: [PASS/WARNING/FAIL] → [model config]

[✅/⚠️/❌] Check 5 — Dynamic Content: [PASS/WARNING/FAIL] → [size breakdown per injection point]

[✅/⚠️/❌] Check 6 — Fork Safety: [PASS/WARNING/FAIL] → [compaction + subagent pattern]

[✅/⚠️/❌] Check 7 — Prefix Budget: [PASS/WARNING/FAIL] → Total: XX,XXX chars (~X,XXX tokens, X.X% of 200K) → Top 5 largest: 1. filename — X,XXX chars (~X,XXX tokens) 2. filename — X,XXX chars (~X,XXX tokens) 3. ...

[✅/⚠️/❌] Check 8 — Rule Efficiency: [PASS/WARNING/FAIL] → [duplicate count + wasted tokens]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ TOKEN BUDGET SUMMARY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Static prefix: ~XX,XXX tokens (X.X% of 200K window) Per-turn injection: ~XXX tokens Per-builder spawn: ~X,XXX tokens Per-lightweight spawn: ~XX tokens

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ TOP FIXES (ranked by token savings) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. [Most impactful fix — exact steps]
2. [Second most impactful — exact steps]
3. [Third — if applicable]

If all checks pass: confirm the setup is well-optimised and estimate cost savings vs a naive configuration (no caching awareness).

Prompt Caching Cheatsheet

Rule Do Don't

Ordering Static CLAUDE.md + rules, dynamic in messages Timestamps/dates/git refs in prefix files

Updates additionalContext → <system-reminder>

Edit CLAUDE.md or rules mid-session

Tools Fixed tool set + deferred MCP stubs Add/remove tools per turn

Models One model per conversation, subagents for switches Inline model switching

Size Trim injections to minimum needed Dump full git status (40K+ chars)

Forks Built-in compaction, additionalContext only Custom prefix rebuilds

Budget Static prefix < 15K tokens Bloated CLAUDE.md, massive rule files

Layers User-level generic + project-level project-implementation.md

Same rule files at both levels