How 5 Tools + Custom Hooks Cut Claude Code Token Usage by 90%+

In actual development, Claude Pro's quota often runs out after just a few rounds, leaving work unfinished. A casual 'test' can silently burn hundreds of tokens. A single code search can spike to 400K tokens, exhausting a session in 20 minutes. You think you're coding, but tokens are being consumed in invisible places.

So saving tokens can't rely on 'say less' or switching to a cheaper model. The real approach is to break down the entire pipeline: code search first goes through CBM, large output first enters context-mode, raw shell output is first compressed by RTK, then Headroom does full compression, and finally Caveman limits Claude's verbosity.

The core idea is simple: don't expect the model to be frugal—make token saving the default behavior.

Your Prompt │ ▼ Layer 1: CBM (Knowledge graph for code) ← cbm-code-discovery-gate blocks Read/Grep │ ▼ Layer 2: context-mode (Large output sandbox) ← PreToolUse hook redirects to ctx_batch_execute │ ▼ Layer 3: RTK (Shell output compression) ← bash-ban-raw-tools blocks cat/grep │ ▼ Layer 4: Headroom (Pre-API full compression) ← shell wrapper intercepts claude binary │ ▼ Layer 5: Caveman (Claude says less) ← Plugin auto-activates, no extra hook needed │ ▼ Anthropic API

Think of it as five gates. Each layer handles its own segment of consumption; no single tool is expected to solve everything.

Tool: Codebase Memory MCP

Repo: github.com/DeusData/codebase-memory-mcp

CBM uses a tree-sitter AST to parse the codebase into a persistent knowledge graph, supporting 66 languages. When looking up function definitions, call chains, or module relationships, Claude can query the graph directly instead of cramming dozens of files into the context.

The numbers in the original post are striking: 5 structural queries via CBM cost about 3,400 tokens; the same via grep across files is about 412,000 tokens. A 99.2% reduction.

Gate: cbm-code-discovery-gate

This uses two hooks to create a lightweight state machine.

The PreToolUse hook (cbm-code-discovery-gate) does three things:

• On first encounter with Grep/Glob/Read/Search, exit 2 to block and suggest using CBM.
• Simultaneously, write a marker file /tmp/cbm-code-discovery-gate-$PPID to indicate the reminder has been issued.
• On subsequent file search attempts, check /tmp/cbm-mcp-used-$PPID. If it exists, allow the call. If it doesn't exist but was already blocked once, also allow to avoid infinite loops.

The PostToolUse hook (cbm-mcp-marker) fills in the second marker. Any call to mcp__codebase-memory-mcp__* triggers a touch on /tmp/cbm-mcp-used-$PPID.

The SessionStart hook (cbm-session-reminder) reinjects CBM usage rules on startup/resume/clear/compact. Long sessions tend to make Claude forget prior constraints; this step refreshes its memory.

The key point here: merely writing 'suggest using CBM' won't work. Claude will always slide back to Read and Grep. To save tokens, you must block the shortcuts.

Tool: context-mode

Repo: github.com/mksglu/context-mode

context-mode handles large outputs. It runs commands in a sandbox subprocess, keeps the full output locally, builds a BM25 index, and only sends a summary into the conversation window. When details are needed, a search retrieves the relevant snippets.

The original post gives the effect: with a 200K context window, a session extends from about 30 minutes to over 3 hours.

Common tools:

Gate: PreToolUse Hook redirection

Installation is two steps:

claude plugin marketplace add mksglu/context-mode npm install -g context-mode

Both the plugin and npm package are needed. The plugin lets Claude Code recognize it; the npm package provides the CLI that the Hook calls.

The Hook is placed on PreToolUse, PostToolUse, PreCompact, and SessionStart, all invoking:

context-mode hook claude-code <event>

Test commands deserve special treatment. Commands like npm test, pytest, go test ./... can produce thousands of lines of output. Consider adding a non-blocking PreToolUse hook: don't force block, just remind Claude to use ctx_batch_execute. Test logs should not be dumped directly into the context.

Tool: RTK (Rust Token Killer)

Repo: github.com/rtk-ai/rtk

RTK is a Rust binary specialized in compressing CLI output. It strips boilerplate, merges duplicates, truncates long outputs, and deduplicates. Overhead is under 10ms, with no network dependency.

Its responsibility differs from context-mode: context-mode handles large outputs, especially test and build logs over 20 lines; RTK handles small-to-medium shell output, like git status, npm install, and short test results.

RTK is bundled with Headroom and typically doesn't need separate configuration.

Gate: bash-ban-raw-tools

The goal here is to prevent Bash from bypassing the system.

Claude might bypass Read/Grep and just run:

cat file.py

grep 'pattern' src/

This sends raw output that bypasses the compression strategy. bash-ban-raw-tools is a Bash PreToolUse hook specifically designed to block this path.

It blocks:

• Raw commands like cat, head, tail, find, grep, rg, wc
• Commands not going through the RTK wrapper
• Pipelines like | head / | tail that appear to truncate but have already pushed large output to the tool layer

Also provide an escape hatch. When raw output is genuinely needed, temporary unlock is available:

touch /tmp/bash-raw-unlock-$PPID # single session unlock touch /tmp/bash-raw-unlock # global machine unlock

Both markers expire after 10 minutes.

Tool: Headroom

Repo: github.com/chopratejas/headroom

The previous three layers control 'what enters the context'. Headroom handles something different: before the request leaves the local machine and is sent to the Anthropic API, it recompresses the entire prompt.

It doesn't just compress tool output, but also conversation history, system prompts, CLAUDE.md, rule files, and more. Many tokens are hidden in these places, beyond the reach of ordinary tools.

It consists of four main components:

Gate: shell wrapper

Headroom's install.sh injects a claude function into the shell configuration.

bash / zsh:

headroom wrap claude -- "$@"

fish:

headroom wrap claude -- $argv

The '--' is mandatory. Arguments like --resume, -p 'query' depend on it for correct passthrough.

This wrapper starts a local proxy, sets ANTHROPIC_BASE_URL, and then launches Claude. RTK is also embedded in the Headroom binary; installing Headroom automatically registers it as the internal CLI proxy.

Tool: Caveman

Repo: github.com/JuliusBrussee/caveman

There is another source of waste often overlooked: Claude itself is too verbose.

Caveman compresses Claude's replies into 'register mode'. Pleasantries, preamble, and repetitive explanations are stripped; technical information is preserved.

Before compression:

'Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by a race condition in the authentication middleware where the token expiry check uses a strict less-than comparison instead of less-than-or-equal.'

After compression:

'Bug in auth middleware. Token expiry check use < not <=. Fix:'

Common commands:

Three intensity levels: lite, full, ultra. Default is full.

Gate: Plugin auto-activation

Caveman doesn't need manual hooks. Once installed as a Claude Code plugin, it auto-registers on SessionStart and UserPromptSubmit.

"enabledPlugins": { "caveman@caveman": {} }

Install and it works. The plugin itself is the gate.

The five layers ultimately converge into a single configuration file.

Environment variables:

"env": { "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50", "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6", "ENABLE_PROMPT_CACHING_1H": "1" }

Model and reasoning:

"model": "claude-opus-4-7", "effortLevel": "xhigh", "advisorModel": "opus"

effortLevel: xhigh retains strong reasoning; advisorModel: opus uses a stronger model for the advisor.

Plugins:

"enabledPlugins": { "caveman@caveman": {}, "context-mode@context-mode": {} }

PreToolUse:

Bash → context-mode + bash-ban-raw-tools + flutter-ctx-redirect + rtk

Grep|Glob|Read|Search → cbm-code-discovery-gate

PostToolUse:

All tools → context-mode

MCP calls → cbm-mcp-marker

Edit|Write|MultiEdit → sync-copilot-on-edit + sync-runner-tools-on-edit

PreCompact:

context-mode

SessionStart:

context-mode + memory-repo-symlink + cbm-session-reminder

CLAUDE.md should only contain rules that Claude can see and execute within the session. Headroom and RTK operate outside the session; Claude doesn't know they exist, so writing about them there is pointless.

Recommended content:

• Core principles: DRY / KISS / YAGNI / SSOT. Read code before acting. Ask before destructive operations.
• Workflow: Index → Skill gate → Clarify → CBM explore → Plan → Delegate? → Ripple → TDD → Verify → Advisor.
• Ripple check: Before adding, modifying, or deleting, use trace_path to find callers. Don't trust 'only used here'.
• Tool quick reference: Use search_graph for definitions, trace_path for call chains, ctx_execute for running code, ctx_fetch_and_index for web pages.
• Blocklist: Don't use cat / head / tail / grep / find for reading files. Use Read / Grep / Glob and accept gate control.
• Sub-agent strategy: Delegate for research, multi-file refactoring, auditing, multi-file impact analysis. Max 3 in parallel.
• Reply style: Lead with the answer, less preamble, less summary.

~/.claude/rules/ can be organized by tech stack, then loaded via @ import. One file per stack keeps maintenance lightweight.

Each rule file can follow a fixed structure: first load the corresponding skill, then list the common pitfalls.

Flutter example:

• Load building-flutter-apps skill
• Every await in a notifier should be followed by if (!ref.mounted) return;
• Don't write _buildXxx(), extract into standalone Widgets

React/Next example:

• Load vercel-react-best-practices skill
• Server Components by default, only add 'use client' for interactivity
• Use useMemo for heavy computations
• Don't use enum, use as const objects instead

Numbers are directional due to different measurement scopes.

The core of this approach is layered plugging: CBM handles code exploration, context-mode handles large output, RTK compresses shell output, Headroom compresses at the API layer, and Caveman reduces verbosity. Tools plus gates together make token saving work.

Article: https://medium.com/@abdulgafoorabid/how-i-cut-claude-code-token-usage-by-90-with-tools-custom-hooks-and-enforcement-d3f8d2488cd6

Code repository: https://github.com/sgaabdu4/claude-code-tips

CBM: https://github.com/DeusData/codebase-memory-mcp

context-mode: https://github.com/mksglu/context-mode

RTK: https://github.com/rtk-ai/rtk

Headroom: https://github.com/chopratejas/headroom

Caveman: https://github.com/JuliusBrussee/caveman

Codeburn: https://github.com/getagentseal/codeburn

Agent browser: https://github.com/vercel-labs/agent-browser

Flutter MCP: https://docs.flutter.dev/tools/mcp

Claude Code slash commands: https://code.claude.com/docs/en/claude-code/slash-commands

Claude Code issue #30280: https://github.com/anthropics/claude-code/issues/30280