How to Reduce Token Usage with AI Coding Agents: A Sysadmin's Field Guide

If you've spent any serious time with Claude Code, Cursor, Codex, or another terminal-based coding agent, you've felt the same thing I did: the bill creeps up faster than the code quality improves. I've been running servers longer than these tools have existed, so I treat a token meter the way I treat disk space or CPU load — it's a resource, and most setups are leaking it.

A token is roughly four characters of English text, or about three-quarters of a word. Every message you send and every reply the model writes is priced per token, and in agentic coding a casual "fix this bug" can silently turn into tens of thousands of tokens as the agent runs commands, reads files, and narrates its progress. The good news: most of that waste is mechanical, which means it's fixable with tools and habits — not by hoping for cheaper models.

A note on numbers before we start. Everything in this post is either (a) the tool's own published measurement, which I label as such and which you should re-measure on your own workload, or (b) a vendor-published figure with a link. Nobody in this space has an incentive to understate savings, so treat every percentage as a hypothesis until your own ccusage report confirms it.

The short version

• Most waste is invisible: command output, re-loaded context, verbose replies, and session history — not your prompts.
• RTK compresses command output. Caveman compresses replies. Context7 pulls docs on demand. Repomix packs a repo once. ccusage measures all of it.
• The biggest single win is usually discipline (a tight CLAUDE.md, a .claudeignore, session control), not any one tool.
• Savings come in five flavors — command-output, context, response, session, and cost — and they do *not* add up the way READMEs imply.
• Any tool that promises "90% off your bill" is selling something. The honest tools say "90% off the bash output we touch," which is a very different claim.

Where the tokens actually go

Before installing anything, you need a mental model of the five sinks. Every tool below attacks one or two of them, and knowing which one you're fixing keeps you from being seduced by a nice dashboard.

1. Command output. The agent runs git status, ls, a test suite, and the entire raw output is streamed back into context for the model to read. A 15-line git push progress dump and a 200-line failing cargo test log are pure overhead. *Savings type: command-output.*

2. Context. Before you type a single word, the model is already carrying the system prompt, your CLAUDE.md, MCP server tool descriptions, a repo map, and possibly injected docs. This prefix is re-sent (or re-read from cache) on *every single turn*. *Savings type: context.*

3. Response. Models narrate. "Sure! Let me take a look at the authentication middleware to understand the token expiry logic…" That filler is output tokens, and output tokens are the most expensive ones on the price sheet. *Savings type: response.*

4. Session. History accumulates across a long session. Files you read thirty minutes ago get re-read, old tool outputs linger, and auto-compact summaries trade detail for space. *Savings type: session.*

5. Price per token. Not all tokens cost the same. Output runs roughly 5× input on Claude models, cache reads cost 10% of input, and cache writes cost 25–100% more than input. Model choice and caching strategy are therefore cost levers, not just token-count levers. *Savings type: cost.*

Rule 0: measure before you optimize

You cannot manage what you do not measure, and yes, I ran this like a monitoring rollout. ccusage (github.com/ccusage/ccusage, MIT, actively maintained) reads the local session logs of Claude Code, Codex, OpenCode, Amp, Gemini CLI, GitHub Copilot CLI, and about eight more agents, and turns them into daily, weekly, monthly, and per-session reports with USD cost estimates.

# Baseline — run this before changing anything
npx ccusage@latest            # all detected sources, by day
npx ccusage weekly            # weekly totals
npx ccusage claude daily --instances   # per-project breakdown

It also tracks cache creation vs. cache read tokens separately, which matters a lot once we talk about caching. If you're in Claude Code, /cost and /usage in-session give you the same picture ad hoc; Gemini CLI has /stats. Run a baseline for a few days of normal work. That file is your control group.

1. RTK: stop paying for command output

RTK ("Rust Token Killer", github.com/rtk-ai/rtk, Apache-2.0) is a single Rust binary that sits between your agent and the shell. When the agent runs git status, RTK intercepts the command, runs it, and hands back a compressed version — grouped, truncated, deduplicated. git push becomes ok main. A 200-line failing test run becomes failure lines plus a collapsed pass count. It supports 100+ commands across git, test runners, linters, package managers, AWS, Docker/kubectl, and Pulumi, and integrates with 16 agents (Claude Code, Gemini CLI, Codex, Cursor, Windsurf, Cline, Copilot, and more).

Install and enable:

brew install rtk                 # macOS; see repo for other installers
rtk init -g                      # Claude Code / Copilot (installs a PreToolUse hook)
rtk init -g --gemini             # Gemini CLI
rtk init -g --codex              # Codex (OpenAI)
rtk --version                    # verify

Restart the agent, and shell commands are rewritten automatically. Handy commands to know:

rtk git status                   # compact stat format, grouped by state
rtk git log -n 10                # hash, author, subject only
rtk cargo test                   # failures only, passing tests collapsed
rtk ls .                         # compact tree with file counts
rtk read src/main.rs -l aggressive   # signatures only, bodies stripped
rtk gain                         # dashboard of estimated tokens saved
rtk discover                     # find commands RTK didn't optimize

Limitations, honestly. The hook only intercepts *Bash tool calls*. Claude Code's built-in Read, Grep, and Glob tools bypass it, so files read through those paths stay uncompressed. RTK's own README is admirably blunt: it measures "up to 90% reduction in bash output," which is *not* a 90% bill reduction — bash output is only one contributor to input tokens, and input tokens are only part of the bill. Its token counts are estimated as bytes/4; it ships no tokenizer. Also, a different project called "rtk" (Rust Type Kit) exists on crates.io, so use the repo's install method, not a bare cargo install rtk.

Security. RTK is a man-in-the-middle on your shell: it rewrites every Bash command the agent runs. Install from the official repo/Homebrew, keep it updated, and check ~/.config/rtk/config.toml (you can exclude commands like curl). Telemetry is opt-in with explicit consent, and when a command fails, RTK can save the full raw output to a local tee file so the model still sees the complete error — that file lives on your machine, not in the cloud.

2. Caveman: stop paying for narration

Caveman (github.com/JuliusBrussee/caveman, MIT) is a skill/plugin — instructions, not a binary — that tells the agent to answer in compressed "caveman" style: fragments, no filler, substance first. Code, commands, URLs, and error strings stay byte-for-byte exact; only the prose narration shrinks.

# macOS / Linux / WSL
curl -fsSL https://raw.githubusercontent.com/JuliusBrussee/caveman/main/install.sh | bash

# Or as a Claude Code plugin
claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

In-session: /caveman lite (or full, ultra, wenyan), /caveman-stats to see session savings, and /caveman-compress CLAUDE.md to rewrite a memory file into compressed form — the project's own measurements show ~46% fewer input tokens for typical memory files, and since that file loads every session, it compounds.

The honest numbers. The README claims 65% fewer output tokens on chat-style prose (its own 10-prompt benchmark) and 8.5% on a full agentic coding run — the latter independently measured by JetBrains on 86 auto-graded tasks, with quality statistically indistinguishable between arms. That gap is mechanical: in a long coding run, most output is code and tool calls, which Caveman leaves untouched by design. The README also warns that the skill adds ~1–1.5k input tokens per turn and can go *net-negative* on already-terse workloads. Caveman saves response tokens, nothing else. If your bill is mostly input tokens — which is true for most agentic work — Caveman alone won't move it.

Security. A skill file is prompt instructions, and prompt instructions are an injection surface: only install skills you've read from sources you trust. /caveman-compress rewrites files in your repo, so review the diff. Verify the install script like you would any curl | bash.

3. Context7: docs on demand, not in context

Context7 (github.com/upstash/context7, MIT, ~60k stars) solves a subtler waste: the agent guessing library APIs from stale training data, writing hallucinated code, running it, failing, and re-reading docs in a loop. Each cycle burns thousands of tokens. Context7 pulls version-specific, current documentation from a maintained index and drops it into the prompt only when needed.

npx ctx7 setup              # OAuth, generates a key, installs skill or MCP
npx ctx7 setup --claude     # target a specific agent

Then prompt naturally: "Use context7: how do I set up Next.js 14 middleware?" or pin a library: "use library /vercel/next.js for API and docs." CLI mode works too: ctx7 docs /vercel/next.js "middleware".

Limitations. Docs are community-contributed; quality varies and Context7 explicitly disclaims accuracy. It's a hosted service — your library names and queries go to context7.com (there's a local MCP option in the repo if that matters to you). Requires Node 18+; a free API key raises rate limits. And it saves tokens only if your agent actually *uses* it — add the rule to CLAUDE.md, or it's just another unused MCP.

4. Repomix: pack the repo once

Repomix (github.com/yamadashy/repomix) packs your entire repository into a single AI-friendly file (Markdown, XML, or JSON) with tree-based file selection, ignore rules, and optional compression. It's for the "understand this codebase" moment — onboarding, review, one-shot analysis — not for interactive loops.

npx repomix@latest
npx repomix --compress --ignore "**/*.lock,**/node_modules,tmp/"

Paste the resulting file into a fresh session: "Review this codebase first." One read, one context, done. Limitations. It's a snapshot: big repos produce big files, and it doesn't update as you work. For interactive agents, a repo *map* (next section) beats a full pack.

Security. Repomix reads everything you point it at — exclude .env and secrets with --ignore, and it includes its own check that scans the packed output for suspicious content (use it). The packed file is a complete copy of your code; handle it like source code.

5. Aider's repo map: the "map, not files" pattern

Aider is a terminal pair-programming agent, and its repository map is the pattern every coding agent should copy: instead of dumping file contents, it builds a concise map of the repo — classes, functions, and call signatures extracted with tree-sitter — and sends only the most relevant portions, selected by a graph-ranking algorithm, sized to a token budget that defaults to 1,024 tokens (--map-tokens).

aider --map-tokens 1024                    # default; shrink if you're tight
aider --show-repo-map | wc -l              # see how big the map actually is

Add a .aiderignore (mirroring .gitignore) to keep generated and vendored directories out of the map. The lesson for every agent: give the model a map and let it ask for files, rather than pre-loading the whole tree. Claude Code's equivalent discipline is a tight CLAUDE.md plus Read/Grep on demand instead of "read everything." The map costs input tokens on every turn, so keep it small and let the agent pull detail lazily.

6. Built-in hygiene: the free wins

Before adding tools, do the boring stuff. Anthropic's own Claude Code best practices and context-window docs are the best official reference, and most of it generalizes to Cursor, Codex, and Gemini CLI:

• `CLAUDE.md` is config, not prose. Every session loads it. Keep it to commands, conventions, and gotchas; cut the marketing paragraphs. This is the highest-leverage edit you can make, and it's where Caveman's /caveman-compress shines.
• `.claudeignore` excludes the noise. node_modules, lockfiles, build artifacts, generated code, logs — anything the agent should never read.
• Control the session. /compact focus on the auth bug fix summarizes with intent instead of whatever the automatic pass guesses; /autocompact 500000 sets when auto-compact fires; /clear starts fresh for unrelated work; /rewind drops a bad turn. One session per task beats one epic session.
• Fewer MCP servers. Every connected MCP server's tool descriptions occupy context on every turn, even when unused. Add them per project, not globally.
• Turn off narration styles. Claude Code's output styles (JSON/stream-json) strip prose when you don't need it; Gemini CLI and Codex have equivalent flags.

*Savings types: context and session.*

7. Platform levers: caching, routing, and tool-use design

These are the cost-layer moves, and they're where real money lives.

Prompt caching. Anthropic prices cache writes at 1.25× input (5-minute TTL) or 2× (1-hour TTL), but cache reads at 0.1× input, a 90% discount (official docs). Claude Code enables caching automatically, which is why stable prefixes (system prompt, CLAUDE.md) are cheap to re-send. The practical rules: keep your prefix *stable* (don't reorder CLAUDE.md sections mid-session), and don't touch cache-write pricing unless you're building on the API — for CLI users, the win is already happening. ccusage shows cache read vs. write tokens so you can verify it.

A gateway if you build on the API. LiteLLM is a proxy that can auto-inject cache checkpoints, route requests to keep cache hits alive, and send routine work to cheaper models while keeping expensive models for edits. Useful if you're wiring agents into infrastructure; overkill for one laptop.

Programmatic tool calling (PTC). If you're building agents rather than using them: Anthropic's advanced tool use engineering post measured that keeping intermediate tool results *out* of context — having the program consume them instead — cut average usage from 43,588 to 27,297 tokens, a 37% reduction on complex research tasks (vendor-measured). The CLI tools in this post are the consumer-grade version of the same idea: filter before the model sees it.

*Savings type: cost.*

Comparison table

A starter setup you can run today

1. Baseline. npx ccusage weekly --json > baseline.json after a normal week.
2. Hygiene. Write a tight CLAUDE.md; add .claudeignore (node_modules, locks, builds).
3. RTK. brew install rtk && rtk init -g, restart the agent.
4. Caveman. Install the skill, set /caveman lite; /caveman-compress CLAUDE.md once.
5. Context7. npx ctx7 setup and add the rule to CLAUDE.md.
6. Sessions. One task per session; /compact focus on … before long tasks; /clear between unrelated work.
7. Re-measure after a week of similar work. npx ccusage weekly --json > after.json and compare.

How to measure savings (the simple protocol)

# Before: after one normal week of work
npx ccusage weekly --json > baseline.json

# Make your changes, work for another week, then:
npx ccusage weekly --json > after.json

# Compare — totals, per source, per project
npx ccusage claude daily --instances
jq '.totals' baseline.json after.json

Compare like-for-like work (same week length, similar task mix — don't compare a vacation week to a crunch week). Watch the *breakdown*, not just the total: input tokens tell you about context/command-output waste, output tokens about narration, cache reads about caching efficiency. If a "90% saving" turns out to be 15% on your stack, that's normal — it's why you measure.

Security considerations, in one place

• Hooks rewrite your shell. RTK's PreToolUse hook is a man-in-the-middle on Bash commands. Install from official sources, review config, keep telemetry off unless you opt in.
• Skills are prompt injections. Caveman and any SKILL.md are instructions loaded into the prompt. Treat them as third-party code; read before installing.
• MCP servers see your queries. Context7 (hosted) receives the library names and questions your agent sends. Use the local MCP if that's a problem for your codebase.
• Packers read everything. Repomix will happily include your .env if you don't --ignore it. Exclude secrets; use its output-scan check.
• Proxies hold keys. A LiteLLM gateway concentrates your API keys and traffic — protect it like a jump host.
• Measurement logs are sensitive. ccusage reads local session JSONL that contains your prompts and code. It runs locally, but don't paste reports containing secrets into public chats.

Official sources

• RTK: github.com/rtk-ai/rtk
• Caveman: github.com/JuliusBrussee/caveman · docs/HONEST-NUMBERS.md
• ccusage: github.com/ccusage/ccusage · ccusage.com
• Context7: github.com/upstash/context7 · context7.com
• Repomix: github.com/yamadashy/repomix · repomix.com
• Aider repo map: aider.chat/docs/repomap.html
• Claude Code context window: code.claude.com/docs/en/context-window · costs: code.claude.com/docs/en/costs · best practices: code.claude.com/docs/en/best-practices
• Anthropic prompt caching: platform.claude.com/docs/en/build-with-claude/prompt-caching · pricing: platform.claude.com/docs/en/about-claude/pricing · advanced tool use: anthropic.com/engineering/advanced-tool-use
• Gemini CLI: geminicli.com/docs
• LiteLLM prompt caching: docs.litellm.ai/docs/completion/prompt_caching

If you've cut your token bill with a setup that works, or watched a "90% savings" claim evaporate on your own workload, drop it in the comments. The best benchmarks are the ones you run yourself.

Until next time, keep your systems thoughtful.