PKM

Claude Code — Token Optimization Stack

3 min read

Claude Code — Token Optimization Stack

A layered system for reducing Claude Code token consumption: RTK (Read Tool Kit) for file reading compression, a code-review-graph for structural navigation, and bash output filtering via hooks.

Why / When to Use

When running Claude Code intensively on a large codebase and hitting context limits or high token costs. RTK alone can save millions of tokens per session. Most impactful on codebases with many large files.

Core Concept / Commands

Layer 1 — RTK (Read Tool Kit)

RTK intercepts file reads and returns compressed, structurally relevant output instead of raw file contents. The standout result: 14.6M tokens saved across 641 calls in a single session.

# RTK reads a file and returns compressed representation
rtk read src/components/Button.tsx
 
# Check current savings
rtk gain --short

Add RTK statusline badge to settings.json:

"statusLine": {
  "type": "command",
  "command": "rtk gain --short 2>/dev/null || echo ''"
}

Layer 2 — Code Review Graph

A pre-built dependency graph of the codebase (3629 nodes / 32489 edges in one measured session). Updated incrementally on every Edit or Write tool call.

  • Guides Claude to touch only files it needs (no wasteful full-codebase dumps)
  • Incremental update keeps overhead manageable (watch for 30s timeout lag on large codebases)
  • The graph is the skeleton; RTK provides compressed flesh

Layer 3 — Bash Output Filter Hook

A PostToolUse hook (filter_bash_output.py) that compresses bash command output before it enters Claude’s context. Acts as a safety net for commands RTK doesn’t cover.

"hooks": {
  "PostToolUse": [
    {
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "python ~/.claude/hooks/filter_bash_output.py"}]
    }
  ]
}

Key Options / Variants

ComponentTokens SavedMechanism
RTK rtk read~14.6M (641 calls)Compressed file output
Code-review-graphStructuralTargeted file selection
filter_bash_output.pyResidualBash output compression

Gotchas

  • Missing statusline badge: Without the rtk gain statusline entry, you won’t see live savings in the Claude Code status bar.
  • Session resumption gap: After /clear, context about the codebase is lost. A custom slash command ~/.claude/commands/catchup.md should re-orient Claude to the graph and RTK setup. (Open task: build this.)
  • Graph timeout: If the code-review-graph update takes >30s on PostToolUse, it can slow the interactive session. Monitor with time rtk update.
  • RTK and filter_bash_output.py overlap slightly — RTK handles most file reads; the Python hook covers edge cases.

Source

Conversation: “CC-Token optimization” — 2026-05-16

Updates — 2026-05-17

Statusline badge fix (RTK gain display)

The RTK gain statusline badge was flagged as missing. Add to settings.json:

"statusLine": {
  "type": "command",
  "command": "rtk gain --short 2>/dev/null || echo ''"
}

This shows live token savings in the Claude Code status bar. Without it, RTK is saving tokens silently — you just can’t see the running total.

Open task: /catchup slash command

After /clear, Claude loses all context about the codebase, RTK setup, and code-review-graph. A custom slash command at ~/.claude/commands/catchup.md should re-orient Claude to the graph, RTK, and current project state — saving the 5–10 minutes of manual re-explanation currently needed after each reset.

Status: not yet built.

Graph View