Every time your AI coding agent executes a terminal command, your context window is being quietly looted. Running a simple repository status check or inspecting build logs dumps hundreds of lines of pure garbage into the session. Decorative headers, alignment padding, redundant commit metadata, and repeated path strings exist entirely for human eyes, not for large language models. In a production TypeScript and Next.js codebase, tracking 26,779 CLI commands and 2,246 API calls over a single month revealed that billions of tokens vanish on raw terminal output that never alters the model's downstream reasoning.
When your Anthropic API bill escalates from command-line noise filling the context buffer, engineering a lean pipeline becomes mandatory. To solve this, developers have split into two distinct paths: a two-layer local architecture combining RTK and Headroom, or replacing default tooling using the WOZCODE plugin.
┌──────────┐ ┌─────────────┐ ┌─────────┐ ┌──────────────┐ ┌──────────────┐
│ Agent │────▶│ RTK hook │────▶│ Bash │────▶│ Headroom │────▶│ Anthropic │
│ │ │ (rewrite) │ │ (runs) │ │ (compress) │ │ API │
└──────────┘ └─────────────┘ └─────────┘ └──────────────┘ └──────────────┘
Layer: PreToolUse Shell API proxy Provider
Savings: 60-90% 16-59%
Layer 1: Sifting Terminal Noise with RTK
Rust Token Killer (RTK) is a compiled Rust binary designed to eliminate boilerplate at the terminal boundary. It operates as a PreToolUse hook inside Claude Code. When the agent initiates a Bash tool call, RTK intercepts the command and modifies it transparently before execution.
bash# How RTK intercepts execution # 1. Agent calls: git status # 2. PreToolUse hook triggers # 3. Hook rewrites command to: rtk git status # 4. RTK runs git status and filters output # 5. Compressed output enters context window (up to 80% smaller)
RTK cuts token overhead between 60% and 90% per command through four core mechanisms:
- Smart Filtering: Discards irrelevant boilerplate syntax and decorative terminal artifacts.
- Grouping: Combines similar lines and entities into compact representations.
- Truncation: Cuts off massive log dumps while preserving key failure details, such as isolating error traces in build logs.
- Deduplication: Drops identical repeating lines that offer zero semantic value.
RTK adds sub-10ms execution overhead per invocation. The agent retains the exact same tool interface and receives identical semantic context without noticing the interceptor.
Layer 2: Session Compression and Cache Preservation with Headroom
Where RTK prunes the terminal output before it reaches the context window, Headroom operates downstream at the network layer. Headroom runs as a local proxy on localhost:8787, sitting directly in the request path between the coding agent and the Anthropic API.
Headroom inspects payloads dynamically. JSON arrays see an 83% to 90% size reduction, shell logs shrink by 85%, and build outputs compress up to 94%. Source code files and grep results are intentionally passed through uncompressed to prevent lossy compression from damaging the model's analytical capabilities.
Headroom's primary architectural advantage is its protection of the Anthropic Prefix Cache. Anthropic applies a 90% discount on input tokens when the prompt prefix matches previous requests. By pruning tool output data without altering the system prompt or early conversation history, Headroom keeps the prefix stable, sustaining cache hit rates up to 96%.
The Alternative Path: WOZCODE Plugin
Instead of wiring hooks and proxies, WOZCODE embeds directly into Claude Code as a plugin. It replaces the default file tools with pre-optimized native alternatives.
WOZCODE splits tasks across two dedicated agents:
woz:code: The primary agent handling code modifications, file operations, search routines, and SQL operations.woz:explore: A read-only exploration agent running on the lightweight Haiku model, designed to navigate codebases at high speed and minimal cost.
Installation runs straight through Claude Code's plugin interface:
bash/plugin marketplace add WithWoz/wozcode-plugin /plugin install woz@wozcode-marketplace
Once installed and authenticated via /woz-login, the plugin operates automatically. It provides native cost monitoring through /woz-savings and supports integrations with environments such as Conductor.
Architecture Breakdown: RTK + Headroom vs. WOZCODE
Choosing between a proxy pipeline and a native plugin comes down to how you manage local infrastructure.
| Parameter | RTK + Headroom Combination | WOZCODE Plugin |
|---|---|---|
| Operating Layer | PreToolUse Hook & Local API Proxy (localhost:8787) | Plugin Marketplace & Tool Replacement |
| Compression Strategy | Regex/AST CLI filtering & JSON/log payload compression | Core tool replacement & Haiku model delegation |
| Model Optimization | Anthropic Prefix Cache stability (up to 96% hit rate) | Specialized woz:explore agent powered by Haiku |
| Authentication | Fully transparent, zero third-party accounts required | Requires Woz account registration and token login |
| Tool Surface | Intercepts standard Bash commands (git, read, etc.) | Optimizes file manipulations and codebase search |
| Observability | Real-time local TUI dashboard (tui.py) | In-session metrics via /woz-savings |
Technical Traps and Configuration Pitfalls
Setting up custom hooks often creates silent failures where token reduction drops to 0% despite the agent appearing to work normally.
1. Minimal PATH Resolution in Claude Code Hooks
Claude Code executes hooks in a restricted shell environment containing a bare-minimum PATH (/usr/bin:/bin:/usr/sbin:/sbin). When RTK is installed via Homebrew, the hook fails silently with exit code 0. The test suite passes, no warnings fire, and commands run completely unfiltered. You must export the full PATH explicitly at the start of your wrapper script.
2. File Overwrites from rtk init -g
Running rtk init -g replaces your hook configuration and removes any manual PATH modifications. RTK also validates its hook script integrity with a SHA-256 checksum, refusing to execute if the file was modified in place. To avoid this, maintain an independent wrapper script like rtk-wrapper.sh outside RTK's self-managed directory.
3. The permissionDecision: "allow" Bypass
RTK emits a JSON payload containing "permissionDecision": "allow". If your Claude Code setup enables skipDangerousModePermissionPrompt or skipAutoPermissionPrompt, the runtime bypasses the permission engine entirely. This causes Claude Code to drop the transformed command and run the original, uncompressed input instead. The wrapper script must strip these fields using jq.
bash#!/bin/bash export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH" # Strip permissionDecision so the compressed command executes properly if .hookSpecificOutput then .hookSpecificOutput |= del(.permissionDecision, .permissionDecisionReason) fi
4. macOS Sequoia Extended Attributes (com.apple.provenance)
On macOS Sequoia, the operating system assigns the com.apple.provenance extended attribute to downloaded scripts, throwing a Permission denied error when Claude Code spawns the hook through /bin/sh. Because this crash generates a non-zero exit code that is not 2, Claude Code classifies it as a non-blocking error and falls back to executing the original raw command.
To bypass this attribute check, configure the hook within ~/.claude/settings.json using an explicit bash command prefix:
json{ "hooks": { "PreToolUse": [ { "command": "bash /Users/username/.claude/hooks/rtk-wrapper.sh" } ] } }
Pragmatic Verdict
For developers who demand total control over their local environment, zero third-party account dependencies, and aggressive pruning of arbitrary shell commands, the RTK and Headroom stack is the standard choice.
If you want a friction-free setup without debugging shell wrappers, managing proxy ports, or writing jq filters, WOZCODE provides an integrated plugin experience right out of the box.
Letting raw terminal noise saturate your agent's context window is an unnecessary engineering tax. Choose an architecture, lock down your hooks, and keep your tokens focused on execution.
References
- https://andrewpatterson.dev/posts/token-savings-rtk-headroom/
- https://github.com/WithWoz/wozcode-plugin