Where Claude Code burns tokens
Token cost in an agent loop is dominated by context, not by the answer. Every turn, the agent re-sends the context it is carrying — and if that context is stuffed with whole files it grepped and read earlier, you pay for those tokens again and again. On a large codebase the bill climbs fast.
- whole-file reads pull in hundreds of lines to use a handful
- re-reading the same files each turn re-bills the same tokens
- grep / glob dumps large, low-signal blocks into the window
- context bloat forces auto-compact, which then loses useful detail
A hard token budget on every retrieval
With Context Engine, the agent calls one MCP tool — codebase_context — and passes a tokenBudget. The service runs hybrid retrieval (dense + sparse + symbol graph), reranks and de-duplicates, then assembles a file-level pack that stops at the budget. It returns the relevant spans rather than whole files, and skips files the agent has already seen.
So the context window carries only what answers the current question, the same code is not paid for twice, and you control the ceiling per call. Lower the budget for cheap sweeps, raise it for hard tasks.
Why this cuts cost without cutting quality
The naive way to save tokens is to feed the agent less — but blind truncation drops the wrong things and the agent flails, costing more in retries. Context Engine saves tokens the other way: by spending the budget on the highest-signal spans first. You are not sending less context, you are sending better context. That is what keeps quality up while the token count comes down.
That ordering matters most under a tight budget. When a codebase_context call has to stop early, it has already spent its tokens on the spans that reranking scored as most relevant, so the parts that get cut are the ones least likely to matter — not whatever happened to load last, which is how blind truncation tends to fail.
Works across every agent you use
The same token-budgeted context pack is available to Claude Code, Cursor, Codex, Windsurf, or any MCP-compatible client — one config block each. If you run more than one agent, they all draw from the same fresh index of your codebase.
A worked example
Say a session starts by asking Claude Code to find every place a deprecated helper is called before removing it. Left alone, the agent might grep the name, get 40 hits across the repo, then open each file in full to check the surrounding code — even though most of those files use the helper in a single line. By the time it has read through them, it has paid for thousands of lines it never needed, and the context window is already crowded before the actual removal work starts.
Context Engine turns that into one codebase_context call with a modest tokenBudget. Retrieval finds the 40 call sites, reranks them, and returns the few lines of context around each call rather than the surrounding file. The agent sees exactly what it needs to check, at a fraction of the tokens, and the removal task starts with a clean context window instead of one already half full of search debris.
- 40 grep hits become 40 short, relevant spans, not 40 full files
- Token spend scales with the number of call sites, not with file size
- The context window stays free for the actual code change
- The same pattern applies to renames, refactors, and dependency audits
How to see it for yourself
The fastest way to know if this saves tokens on your codebase is to run the same task twice — once letting Claude Code search on its own, once through codebase_context — and compare the token counts your provider reports for that session. Repos with deep folder structures, generated code, or large lockfiles checked into the tree tend to see the biggest gap, because those are exactly the files that grep and whole-file reads pull in for no reason. The free quota is sized to run a handful of real tasks on your own repo, so this is a five-minute check rather than a leap of faith.
context-engine