Why a one-line fix can eat a lot of Claude Code usage, where the tokens go, and how to match effort and process to the risk of the change.
A one-line fix burns usage in Claude Code because the line is a small part of what each request carries. Every request re-sends the whole conversation and the fixed startup context, thinking tokens bill as output in an amount that depends on the effort level, and any plan, subagent or review you add runs as extra requests on top. The fix is to price the session separately from the edit: clear context before an unrelated task, set effort and process by the risk of the change, and never cut checks on a small edit that can fail quietly.
Disclosure: we build TLM Forge, a process layer for Claude Code, so weigh the product section accordingly. Process costs tokens, and most of this post is about when not to pay for it.
You pay for the session, not just the edit
Claude Code makes a new API request each time you send a message, and the model keeps nothing between requests. The prompt caching page says Claude Code therefore "re-sends the full context: the system prompt, your project context, every prior message and tool result, and your new message." Caching discounts the repeated part but does not remove it. The costs page adds that each time Claude uses tools it sends another request carrying that batch of tool results. A small edit involves tool calls too, so it can mean several requests. The page states the consequence plainly: Claude Code re-reads that history at the cached token rate, "so a one-line question in a session that has been open all day still draws usage for the whole conversation."
Sources: Claude Code docs: How Claude Code uses prompt caching, Claude Code docs: Manage costs effectively
The best-practices page gives the multi-task version: "Every request sends the whole conversation, so a session that's collected three unrelated tasks re-reads all three on every turn of the fourth. That's discounted while the cache is warm and full price once it expires." The same page says the cache lasts about an hour on a subscription and five minutes on an API key, a cloud provider or usage credits, and that subagents get five minutes unless you change it. The costs page adds that the first message after a break longer than the cache lifetime misses the cache and reprocesses your full context.
Sources: Claude Code docs: Best practices, Claude Code docs: Manage costs effectively
So the price of a small edit depends heavily on where you make it. The same rename costs less in a fresh session than in the one that has been open since morning. For more on deciding what belongs in context, see Context Management for AI Coding.
Where the tokens go on a small change
Five points explain the bill around a small edit, and the last three are choices you make per task.
1. The startup floor
Before you type anything, CLAUDE.md, auto memory, MCP tool names and skill descriptions all load into context. Skill descriptions you add, and the tool names and instructions of MCP servers you connect, join that floor. The costs page suggests keeping CLAUDE.md under 200 lines. Run /context for a live breakdown of what loaded, and on a subscription plan run /usage for a breakdown of what counts against your plan limits by skill, subagent, plugin and MCP server.
Sources: Claude Code docs: Explore the context window, Claude Code docs: Manage costs effectively
2. A big token count is not a big bill
The numbers on screen mix token types that bill at different rates. The costs page's sample /usage output lists 1.2k input, 5.3k output, 940.0k cache read and 50.0k cache write tokens for a session that comes to $0.55, and the caching page says the re-read is billed at the cached token rate. The API pricing page lists that cache-hit price for each model, below the base input price, and it differs by model. For subscribers, the costs page says the session cost figure is not relevant for billing, so read the plan usage bars and breakdown instead. One GitHub reporter saw tens of thousands of displayed tokens for a one-word prompt in an empty folder. In later comments the same reporter wrote that the figure sums several API calls and mixes input, output, cache-read and cache-write tokens. That is one user's report, not a measurement, but it points the same way as the docs sample, since a raw token count is not the billed amount.
Sources: Claude Code docs: Manage costs effectively, Claude Code docs: How Claude Code uses prompt caching, anthropics/claude-code issue 52979, Claude API docs: Pricing (prompt caching)
3. Thinking tokens and effort
The costs page says thinking tokens are billed as output tokens and that the default budget can be tens of thousands of tokens per request depending on the model. Effort is the control. The model configuration page says "Lower effort is faster and cheaper for straightforward tasks," and lists medium as the default for Opus 5.5, Sonnet 5.5 and Haiku 5.5. For low it lists quick exchanges where you review each result, including a small change like a rename. On ordinary tasks, the best-practices page warns, max "tends to overthink," so you pay more for an answer that may be no better than high would give.
Sources: Claude Code docs: Manage costs effectively, Claude Code docs: Model configuration (effort), Claude Code docs: Best practices
4. Exploration from a vague prompt
The costs page says vague requests like "improve this codebase" trigger broad scanning, while a request like "add input validation to the login function in auth.ts" lets Claude work with minimal file reads. A prompt that names the file, the symptom and what fixed looks like is one of the cheapest savings on this list, because it costs a little extra writing and no settings changes.
Sources: Claude Code docs: Manage costs effectively, Claude Code docs: Best practices
5. Process you add, and work in the background
Plans, subagents and reviews each add requests, covered in their own section below. Background work adds more: the costs page notes that session recap and idle compaction can use tokens while you are idle, and that a session-scoped scheduled task fires on its interval even when the session is idle, sending your full context each time.
Sources: Claude Code docs: Manage costs effectively
| Where tokens go | What drives it | Cheapest fix | What the fix costs you |
|---|---|---|---|
| Long session | The whole conversation is re-sent every request; full price after the cache expires | Run /rename, then /clear between unrelated tasks | You lose the live history and must resume the old session to get it back |
| Startup floor | CLAUDE.md, memory, MCP tool names and skill descriptions load before you type | Between sessions, trim CLAUDE.md and disable MCP servers you do not use | Less standing guidance; some instructions move into skills that load on demand |
| Thinking | Thinking bills as output; each effort level trades token spend against thoroughness | Start the session with claude --effort low for mechanical edits | Lower effort means less verification and edge-case checking |
| Vague prompt | Broad scanning and extra file reads | Name the file, the symptom and the check that proves it is fixed | A little more writing |
| Extra process | Plans, subagents and reviews send their own requests | Skip them for a diff you can read in seconds | No second look; you are the reviewer |
| Background | Recap, idle compaction and scheduled tasks run while you are away | Turn off the ones you do not use; the costs page links how | You lose the convenience each one provides |
Two savings that can backfire
One tip list on reducing Claude Code token usage says to start every session on Sonnet, shows a /model command for each task type, and says to "Drop to Haiku for the mechanical stuff." A cheaper model has its place: the costs page says Sonnet "costs less than Opus," and the best-practices page calls Haiku a good fit for subagents doing simple jobs. What the list does not mention is the cache cost of switching mid-session. The caching page says: "Each model has its own cache. Switching with /model means the next request reads the entire conversation history with no cache hits, even though the content is identical." In a long session that one uncached read can cost more than the edit saves. The same page tells you to pick your model and effort level at the top of a session. With the opusplan setting, which uses Opus in plan mode and Sonnet for execution, each plan-mode toggle is a model switch and starts a fresh cache.
Sources: KDnuggets: 7 Practical Ways to Reduce Claude Code Token Usage, Claude Code docs: Manage costs effectively, Claude Code docs: How Claude Code uses prompt caching
Effort has a caching rule of its own. On most models, changing effort mid-session also misses the cache. With an API key or a Claude subscription, the docs say changing effort keeps the cache on models including Opus 5.5, Sonnet 5.5 and Haiku 5.5. A second trap is persistence. Typing /effort low saves the level as your default for later sessions, so later sessions on that model start at low until you undo it. To apply a level to one session only, press s in the /effort slider (Claude Code 2.1.257 or later) or launch with claude --effort low. To clear a saved level for the active model, run /effort auto.
Sources: Claude Code docs: How Claude Code uses prompt caching, Claude Code docs: Model configuration (effort)
For a sense of what effort costs, the effort write-up that the model configuration page links to reports internal numbers. At both low and max effort, Fable 5.1 made 370 Terminal-Bench 3.0 attempts. It had a median of 73k tokens per attempt at low and 222k at max, and passed 140 attempts at low and 214 at max. The write-up says those tasks are much more complicated than the average task its author faces, so do not expect the same ratio on a rename. The point is the direction: effort converts tokens into thoroughness. For model choice more broadly, see How to Choose a Model for AI Coding.
Sources: Using Claude Code: Spending your effort (claude.dev blog)
Do not save tokens on the wrong edit
Most cost-cutting advice assumes an average edit. The edits that hurt are small diffs that fail quietly. A typo in a log message fails loudly or harmlessly. A three-line change to rounding in a price calculation, a permission check or a date boundary can compile, pass a shallow test and still be wrong. The effort write-up's author found that effort modulates how much verification and edge-case testing Claude does and how much of its own judgment it uses, and that higher effort is best for tasks with "lots of hidden edge cases." Cutting effort on that work removes the exact step you wanted.
Sources: Using Claude Code: Spending your effort (claude.dev blog)
The same write-up has a limit worth knowing. Higher effort tends to reduce failures from missed edge cases, but it does not fix a wrong approach, and the write-up notes that higher effort also means Claude makes more assumptions for you. By our reading, that makes effort a poor substitute for a clear request. The best-practices page points the same way: its specific-prompt example describes the symptom, points at the code and asks Claude to write a failing test that reproduces the bug before fixing it. Our heuristic, built on that guidance, is to size the spend by blast radius and by how loudly a mistake would show, not by line count. Tokens are also only one line in the cost of a change; rework and review are the others, and How to Actually Measure the ROI of AI Coding Tools covers counting them.
Sources: Using Claude Code: Spending your effort (claude.dev blog), Claude Code docs: Best practices
| Kind of change | Example | Reasonable spend | Why |
|---|---|---|---|
| Mechanical, fails loudly | Rename a function across three files; fix a typo in a log message | Fresh session, low effort, specific prompt, you read the diff | The compiler, linter or an existing test can catch a broken rename, and the diff takes seconds to read |
| Small logic with a test | Fix an off-by-one in a helper that already has a test | Default effort, or high if edge cases are likely; ask Claude to run the test, read the diff | The test is the check, so spend tokens on running it, not on a plan; the docs list fixing a bug in an existing codebase as an example for high effort |
| Small diff, fails quietly | Rounding in a price calculation; a permission check; a date-boundary query | Higher effort, a failing test first, then a fresh reviewer or your own careful read | Wrong answers look plausible, and the docs point high effort at work where verification matters or edge cases are likely |
| Hard to undo | A migration, a bulk delete, anything that writes production data | Not a small task whatever the diff size; plan it and review it like a large one | The cost of a miss is far larger than the tokens |
Plans, subagents and reviews on a tiny diff
Extra process is where a small task most easily becomes an expensive one. The costs page recommends plan mode for complex tasks as a way of "preventing expensive re-work when the initial direction is wrong." On a change you can state in one sentence there is little direction to get wrong, so in our view the plan is mostly an extra turn plus exploration. One GitHub reporter described a basic request to integrate two backend endpoints that "consumed 22% of a 5-hour quota just on /plan, without any implementation" (Claude Code 2.1.98). That is a report from one user, so read it as a symptom, not a rate.
Sources: Claude Code docs: Manage costs effectively, anthropics/claude-code issue 46012
Subagents cost tokens too. The costs page says every subagent "sends its own requests on top of the main conversation's," and the best-practices page adds that the cost can be time as well, because a fresh subagent "first has to gather context your conversation already had, so it can end up slower than doing the task where you are." By default a custom subagent also starts with your CLAUDE.md files and a git status snapshot in its own context, though the built-in Explore and Plan agents skip both.
Sources: Claude Code docs: Manage costs effectively, Claude Code docs: Best practices, Claude Code docs: Subagents
Reviews follow the same rule. In a terminal session /code-review runs as a background subagent and, in the docs' words, "it counts toward your plan's usage or API billing the same way the rest of the session does." A fresh reviewer is worth paying for when a miss costs more than the review, because it has not seen your reasoning. For a rename in a typed language, the compiler is a cheap reviewer, and a test you run yourself is the cheapest one for logic. For how to tell whether a passing test proves anything, see How to Test AI-Generated Code Properly.
Sources: Claude Code docs: Review locally with /code-review, Claude Code docs: Best practices
A routine for small edits you can copy
- Size it first. If the change is on the "fails quietly" or "hard to undo" rows above, skip this routine and spend more.
- Clear before an unrelated task. If the session holds history you may want back, run
/renameso you can find it later, then/clear. Or open a second terminal. - Pick model and effort when you launch the session, not mid-task:
claude --model sonnet --effort lowfor a mechanical edit. The flags apply to that session only. - Write the prompt with the file, the symptom or goal, and the check. For example: "Rename getUserData to fetchUserProfile in src/api/ and every call site. Behavior must not change. Run the type check when you are done."
- Do not ask for a plan or a review. Read
git diffyourself before you commit. - Check the bill afterward. On a subscription plan,
/usageshows which skills, subagents, plugins and MCP servers took the most;/contextshows what loaded. - Undo what you changed. If you typed
/effort lowinstead of using the flag, run/effort autoto clear the saved level.
Use the cheap path only when three things are true: you can read the diff in seconds, a compiler, linter or test would fail loudly if it were wrong, and nothing touches money, permissions or data. That test is our rule of thumb, not a docs rule.
Where TLM Forge fits
TLM Forge sizes each task Light, Medium or Deep, and Light gets no review agents, so a task sized Light, such as a rename, sets off no review wave. Medium and Deep show you a design for your OK before building, then end with a final wave of independent reviewer agents (code-reviewer and phase-auditor on Medium; tester, red-team-reviewer and architect-reviewer join on Deep). Each agent sends its own requests, so a Medium or Deep task costs more tokens than the bare edit. We give no token figure, because it depends on the task. See Checks big and risky changes harder than small ones.
The limit is that the model does the sizing, so it can land a level higher or lower than you would pick. For an edit you already know is mechanical, a process layer adds little, and a plain session with a specific prompt is enough.
Frequently asked questions
01Why does Claude Code use so many tokens on a small task?
Each request carries the whole conversation plus startup context, thinking tokens bill as output, and any plan, subagent or review adds more requests. The edit itself is only one part of that. A long session or a high effort level can dwarf a one-line change.
02Does /clear actually save tokens?
Yes. The docs say stale context wastes tokens on every later message, and /clear costs nothing, so the next task stops paying for the previous history. You lose the live conversation, so rename the session first if you may want it back.
03Should I use plan mode for a small change?
The costs page recommends plan mode for complex tasks, where it prevents expensive rework from a wrong direction. If you can describe the change in one sentence and read the diff in seconds, a plan is an extra turn with little to catch. Use it when the approach is uncertain.
04Is it cheaper to switch to Sonnet or Haiku mid-session?
Not always. Each model has its own cache, so switching makes the next request read the whole conversation with no cache hits. In a long session that can outweigh the saving. Clear first, or choose the model at the start of a fresh session.
05Is low effort safe for small fixes?
It suits quick, in-the-loop work such as a rename. The docs point high effort at work where verification matters or edge cases are likely. Pick by how quietly a mistake could fail, not by diff size. A three-line change to a price calculation is not a rename.