Co-authored with Claude. Final editorial judgment and accountability are Alex's.
Companion to the Economics of Claude Code series.
Code: zivtech/claude-cost-helpers on GitHub. GPL-3.0-or-later licensed.
Every helper in this guide is a local hook — a small shell script that runs automatically at a specific point in your Claude Code session. They warn but never block. Install whichever ones match your workflow, or install all of them — they're independent and don't conflict.
git clone https://github.com/zivtech/claude-cost-helpers
cd claude-cost-helpers
Session Timing Helpers
From Part 1: Session Timing — gaps that kill the cache, and sessions that go too long.
idle-tax
Warns the moment you return to a session whose cache has gone cold.
cd idle-tax && ./install.sh && cd ..
Installs a UserPromptSubmit hook — a small shell script that runs before each prompt — that tracks your last activity timestamp and compares it to the 5-minute TTL. The warning is informational — your prompt always proceeds. The point is to give you a real choice at the moment it matters: continue here (sometimes that's right) or save and start fresh (often cheaper).
just-one-more-turn
Warns when the session is getting expensive — turn count climbing, context growing.
cd just-one-more-turn && ./install.sh && cd ..
Installs a UserPromptSubmit hook that tracks turn count and estimated context size. Every prompt, you see where you are on the cost curve. When the session is getting heavy — past ~30 turns or ~200K estimated context — it warns you. Past the knee, it tells you what the session has cost and what a fresh start would save. On the very first turn, it also reports what your session started with — how much of your context budget is already spoken for by CLAUDE.md, memory files, rules, and hooks — so you know the starting line, not just the current position.
effort-control
If you're on Opus 4.7, install this at the same time — it pins CLAUDE_CODE_EFFORT_LEVEL=high via the only mechanism that survives 4.7's first-run override (xhigh is the default on 4.7 and silently reapplies when you first switch to it).
cd effort-control && ./install.sh && cd ..
Delegation Helpers
From Part 2: The Agent Tradeoff — delegation keeps files out of your context, but agent results flow back in.
subagent-isolation
Warns when file reads are bloating your main session — the signal to delegate to a subagent.
cd subagent-isolation && ./install.sh && cd ..
Installs a UserPromptSubmit hook that tracks estimated context growth from file reads. When accumulated file-read tokens cross a threshold (configurable, defaults to ~50K), it warns you and suggests delegating to a subagent. A heads-up fires earlier, at 15 unique files, before the token count gets heavy.
delegation-cost
Warns when agent results are piling up in your parent session.
cd delegation-cost && ./install.sh && cd ..
Installs a PostToolUse hook (runs automatically after Claude finishes using a tool) on Agent results that tracks token sizes landing in your context. Per-result warning at 5K tokens. Cumulative warnings escalating at 20K, 50K, and 100K. A swarm warning at 3+ agents returning results. At 8K+ tokens, it suggests having the agent write to a file instead of returning inline. It also checks whether the parent's cache went cold while agents were running — surfacing the idle tax from Part 1 at the moment it matters.
A companion PreToolUse hook (runs before a tool call, so it can inspect and warn) checks whether agent prompts include output length constraints ("under 200 words", "brief summary") and nudges when they don't — because detailed input prompts are good, but unconstrained output is where the carrying cost comes from.
Context Weight Helpers
From Part 3: What You Carry — tool output that lives forever, and the compaction gamble.
watching-cost
Warns when tool output is inflating your context — the silent cost nobody tracks.
cd watching-cost && ./install.sh && cd ..
Installs PostToolUse hooks (scripts that run automatically after Claude finishes using a tool) that track tool output size landing in your context. When a single tool result exceeds 5K tokens, it warns you. It tracks cumulative output for the session and warns at escalating thresholds. For Bash commands specifically, it detects test/build patterns and suggests CI when the output is heavy — CI runs the job, Claude reads the result artifact, one file read instead of thousands of tokens permanently in context. It also flags known-verbose commands (recursive grep, find, curl) and suggests redirecting to a file or piping through head/grep instead of dumping everything into the conversation.
compact-safety
A safety net for when Claude Code auto-compacts your conversation.
cd compact-safety && ./install.sh && cd ..
Installs a PreCompact hook (runs automatically just before Claude Code summarizes and compresses your conversation) that writes a snapshot of the conversation state before auto-compact fires — turn count, estimated tokens, key file paths. It's metadata, not the full conversation, but it gives you a checkpoint. A companion UserPromptSubmit hook detects when compact just happened and reminds Claude to re-read CLAUDE.md and verify that constraints survived — turning the manual "did something get dropped?" check into an automatic one.
Ecosystem Tools
The helpers above are 30-second sensors — they make cost visible. These ecosystem tools are the automated fixes. Install both layers.
For file reads: token-optimizer-mcp
Pair with the subagent-isolation hook. An MCP server (Model Context Protocol — a standard way to plug external tools into Claude Code) that provides smart_read and smart_grep tools returning compressed diffs instead of full file contents. 95%+ token reduction on file reads.
npx @anthropic-ai/claude-code mcp add token-optimizer-mcp -- npx -y token-optimizer-mcp
Our hook warns you at 50 files. Their MCP makes each file read dramatically cheaper. The two are complementary.
For Bash output: RTK
Pair with the watching-cost hook. RTK (28K+ stars) is a Rust CLI proxy that compresses command output 60–90% via a PreToolUse hook. Builds, test runs, grep results — all compressed before they hit your context.
brew install rtk-ai/tap/rtk
RTK compresses Bash output only — it doesn't touch results from Claude Code's built-in tools (Read, Grep, Glob, Agent). Our hook monitors all tool output regardless of source. RTK prevents Bash bloat; our hook catches everything else.
For compaction quality: token-optimizer
Pair with the compact-safety hook. token-optimizer is a plugin with 7-signal quality scoring, progressive compaction checkpoints, and automatic context restoration.
claude plugin install alexgreensh/token-optimizer
For delegation results
There's a genuine ecosystem gap. RTK compresses Bash output but doesn't touch Agent results. Token-optimizer-mcp compresses file reads but not agent returns. The fix is behavioral: constrain what comes back, split when results accumulate, and know the difference between the invoice and the tax.
All helpers: zivtech/claude-cost-helpers on GitHub. GPL-3.0-or-later licensed.