How to reduce Claude Code token usage

A coding agent does not send your question. It sends your question plus everything it decided you meant: the files it opened, the directory listings it walked, the output of every command it ran, and the whole conversation so far, again, on every single turn. The question is a rounding error. The context around it is the bill.

That is why the usual advice, write shorter prompts, does almost nothing. You can halve your prompt and change the total by one percent. The seven items below are ordered by what they are actually worth.

1. Say which file you mean

The single largest avoidable cost in an agent session is exploration: the agent reading its way toward the file you already had open. Every Read, every Grep, every directory listing lands in the context and stays there for the rest of the session.

Naming the file turns a search into a lookup. It is worth more than any flag, any setting, and any prompt-writing technique.

$capsul ask 'why does the retry loop give up early' --open src/lib/retry.ts

2. Start a new session when the subject changes

Conversation history is re-sent in full on every turn. A session that has been running for forty messages pays for all forty on message forty-one, whether or not any of it is still relevant.

So the habit that costs the most is the one that feels most natural: keeping one long session open all day. Two unrelated tasks in one thread means the second one pays for the first. Close it and start again when the subject changes.

3. Put a ceiling on the context

A budget is a hard cap on how much context is allowed through, expressed in tokens. It is not a suggestion the agent may exceed when it feels underinformed.

$capsul ask 'add a rate limit to the login route' --budget 3000

The number matters less than the fact that one exists. An agent with no ceiling will fill whatever window it is given, because there is never a reason for it to stop.

4. Match the model to the task

Renaming a variable and designing a migration are not the same job, and they should not run on the same model. Most sessions run entirely on the largest model available because that is the default, not because anyone chose it.

$capsul ask 'rename userId to accountId across the auth module' --model haiku

5. Keep tool output out of the transcript

A test run that prints two thousand lines costs two thousand lines of context, and keeps costing them on every subsequent turn of that session. So does a verbose build, a full git log, and an unfiltered find.

Pipe the noisy thing through something that shortens it before the agent ever sees it. head, grep, --quiet, --json with a filter: all of them are cheaper than asking the model to ignore the noise.

6. Measure before and after, not just after

Any claim about token savings that is not measured against the same task on the same model is a guess. Run the thing you actually do, twice, and compare.

$capsul context 'your real task here' --json

7. Watch the trend, not the turn

One request tells you nothing. Token usage is bursty by nature: an exploration-heavy turn can cost ten times an edit-heavy one, and both are normal. What you want is the weekly line.

$capsul stats

What does not work

• →Asking the model to be brief. Output tokens are a small share of the bill; input is where the money goes.
• →Turning off the tools. The agent then asks you to paste the file, and you paste more of it than it needed.
• →Upgrading to a larger context window. A bigger window is a bigger invoice for the same answer, not a cheaper one.
• →Compacting the conversation late. By the time compaction triggers, you have already paid for every turn that led to it.