How to cut Claude Code costs without making it dumber

Claude Code bills by the token, and most of the tokens are ones you never see. Every turn resends the system prompt, the tool definitions, the whole conversation so far, and every tool result the agent has read. The reply you watch being typed is a small fraction of what was charged.

That shape decides which fixes work. Anything that shrinks the resent part pays out on every later turn. Anything that only shortens the visible reply pays out once. This guide walks the levers in the order they usually pay, with the numbers we have measured and the cases where each one loses.

Where the money goes

A coding session has four counters: fresh input tokens, output tokens, cache writes, and cache reads. In agent work, input dominates. In our pinned Claude Code benchmark, six tool-heavy tasks run three times each consumed 885,793 provider-reported input tokens across 18 runs. That is about 49,000 input tokens per task, before any reply was written.

Output is smaller but expensive per token. Across ten ordinary coding prompts, Claude wrote an average of 1,214 output tokens per reply when left alone.

So the order of operations is: keep the cache warm, then shrink what gets resent, then shorten what gets written, then measure.

1. Keep the prompt cache warm

Anthropic prices a cache read at about a tenth of a fresh input token, and a cache write at about 1.25 times for the five minute cache. Claude Code already places cache breakpoints for you. Your job is to stop breaking them.

A cache is a prefix match. Any byte that changes early in the request invalidates everything after it. The usual culprits:

• A system prompt or CLAUDE.md that includes a timestamp, a random id, or a value that changes between turns.
• An MCP server that connects late in the session and changes the tool list, which sits before the messages in the prefix.
• Switching models mid-session. Caches are per model.
• Long gaps. The default cache lives five minutes.

Check with /cost inside Claude Code, or with the cache_read_input_tokens field if you log the API yourself. If cache reads stay near zero across consecutive turns, something in your prefix is moving.

If you run Claude Code through a gateway, the gateway must forward the cache_control markers untouched. LiteLLM can also inject them for clients that do not send any. Caveman's local proxy forwards them unchanged.

2. Shrink what the agent rereads

Tool output is the bulk of the resent context. Test logs, JSON responses, diffs, and search results enter the conversation once and get charged again on every turn until the session ends.

The Caveman proxy runs on your machine between Claude Code and Anthropic. It recognises the shape of each tool result and replaces it with a smaller version before it reaches the model. The original bytes are stored locally with a recovery handle, so the agent can ask for the full version back when it needs an exact line.

npm install -g @caveman-ai/cli && caveman setup --install
caveman claude

Measured on the pinned benchmark, provider-reported input tokens fell from 885,793 to 591,673 across 18 paired runs, a 33.2 percent reduction with a case-clustered 95 percent interval of 14.6 to 48.5 percent. All 18 exact-answer checks passed. One of the six cases, an HTML dashboard, had no matching compressor and cost 9.9 percent more than direct. That row stays in the total.

Your login passes through. Claude Pro and Max OAuth tokens go to Anthropic untouched, and no Caveman server sits in the path.

3. Shorten what the agent writes

Output tokens cost several times more than input tokens. The Caveman skill is a rule file that makes Claude answer in fewer words while leaving code, commands, paths, and error messages byte for byte intact.

claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman

Across ten coding prompts through the real API, output fell from an average of 1,214 tokens to 294, a 65 percent reduction. The best row was 87 percent on a React error boundary. The worst was 22 percent on a refactor that was already mostly code.

Two limits. The skill's own rules cost roughly 1,000 to 1,500 input tokens per turn, so on a session that was already terse you can pay more than you save. And it does nothing for input. Whole-session savings land below the table figure. If your own A/B goes the wrong way, turn it off for that workload.

4. Audit the MCP tool catalog

Every connected MCP server puts its full tool schemas into the prompt before the first message. We captured one real Claude Code configuration sending 224,655 characters of tool definitions on its first turn, from 91 tools. Sixty three of those tools, most of them never called that week, supplied about 69 percent of the schema characters.

Anthropic's own tool-search documentation puts a typical GitHub, Slack, Sentry, Grafana and Splunk set at around 55,000 tokens of definitions, and notes that tool selection accuracy degrades beyond roughly 30 to 50 tools.

Three fixes, from cheapest to most involved:

1. Disconnect servers you did not use in the last month. Check invocation logs before deciding.
2. Defer loading. Anthropic's tool search keeps a few frequent tools loaded and fetches the rest on demand. LiteLLM offers a similar mcp_tool_search pair for its proxy.
3. Keep the tool list stable within a session, so the cache prefix survives.

caveman learn reads your local session history and ranks these sinks worst-first, including per-server schema weight, without an account.

5. Put a budget in front of the key

A budget does not lower cost per task. It stops one runaway session from becoming a surprise invoice. Anthropic's console supports spend limits per workspace. If you run a gateway, LiteLLM's virtual keys carry daily and monthly budget windows and can fall back to a cheaper model when a window is spent. That is a well built feature and worth using on its own.

6. Use a cheaper model where the turn allows it

Not every turn needs the most capable model. Inside Claude Code, /model switches the session, and subagents can declare their own model in their definition file, so a read-only exploration agent can run on a smaller model while the main loop stays where it is.

Routing per request, rather than per session, needs something in the path that can classify the turn. LiteLLM ships a rule-based complexity router. Caveman Platform exposes the same idea as one model id, auto, documented here. Whatever you use, judge it on cost per completed task, not cost per request. A cheaper request that takes two more turns to finish is not cheaper.

7. Measure before you believe any of it

Tool-side token counters can point the wrong way. One published Cursor A/B showed 4.3 million tokens with the skill against 1 million without, and we could not reproduce it. The only comparison that settles an argument is the provider's own usage on the same task, with and without the change.

caveman trial -- claude
caveman trial report

Run the task at least three times per arm. Sum all four counters. Weight cache buckets by price if you can. Keep a correctness check so a cheaper wrong answer does not count as a win. And label the result for what it is: a local estimate is inferred, a paired benchmark is counterfactual, and neither is an invoice.

A setup that stacks

For a single developer on Claude Code, in this order:

Each row was measured on its own. We have not published a number for the stack together, and the layers overlap, so do not add the percentages.

Questions people ask

How much does Claude Code cost per day?

It depends almost entirely on context size and session length, not on how much you type. Anthropic's usage page shows spend per key. Inside a session, /cost prints the running total. On the benchmark tasks above, one task cost about 49,000 input tokens before compression, so a day of agent work is mostly input.

Does prompt caching work automatically in Claude Code?

Yes. Claude Code sets cache breakpoints itself. What you control is whether the prefix stays stable. A changing system prompt, a late-connecting MCP server, or a model switch breaks the cache for the rest of that turn.

Is the Caveman skill enough on its own?

For output it is the biggest single lever, 65 percent fewer output tokens on ten measured prompts. It does nothing for input, which is usually the larger bill, and its rules cost about 1,000 to 1,500 input tokens per turn. Pair it with cache hygiene and, if tool output is heavy, the local proxy.

Does compression change what Claude sees?

The proxy replaces eligible tool results with a shorter version and keeps the original on disk with a recovery handle. Code, diffs and errors keep the lines answers depend on. On the pinned benchmark every exact-answer check passed, 18 of 18. If a payload cannot be parsed or would not get smaller, it passes through unchanged.

Can I use LiteLLM and Caveman together?

Yes. Point a LiteLLM deployment's api_base at the local Caveman proxy, or set it in the LiteLLM proxy config.yaml so every client behind it gets compression. The full guide covers both, plus the routing callback.

Sources

• CaveBench Wrap benchmark, 54 runs, Claude Code 2.1.223, provider-reported usage.
• Honest numbers, including the cases where the skill loses.
• Your agent pays before it works, the first-turn MCP capture.
• Anthropic, prompt caching and tool search.
• LiteLLM, 5 ways to cut Claude Code costs, for budget windows, cache injection and tool search on their proxy.