Agentic Dev Wiki

Reducing token usage

4 min read

Every request Claude Code sends carries the whole context, and output, including thinking, costs five times input (see Tokens). So the biggest savings come from three places: a smaller context per request, a cheaper model or lower effort where it is enough, and fewer requests you did not ask for. These habits work the same whether you pay per token or draw on a subscription’s usage limits.

When to use it

When you hit your session or weekly limit more often than you would like, when an API bill grows, or when /usage flags a pattern taking 10% or more of your usage.

How to do it

  1. Measure first. Run /usage and look at the attribution and the flags. Fix the biggest share first.
  2. Keep the context small. Clear between unrelated tasks and write specific prompts so the agent reads fewer files. See Managing context.
  3. Pick the model for the task. Sonnet handles most coding work at a lower price than Opus. Keep Opus or Fable for hard architecture and multi-step reasoning. Pick at the start of a session: switching mid-session costs a cache rebuild.
  4. Lower effort for simple work. /effort low or medium for renames, small fixes and test runs; raise it when a task needs real reasoning. max lasts one session only.
  5. Pick the model per subagent. See below.
  6. Use /clear, not /compact, when you do not need continuity. /compact reads the whole conversation to summarize it; /clear costs nothing.
  7. Mind what runs while you are away. Scheduled tasks and /loop send the full context on every run. Stop the ones you no longer need.
  8. Prefer CLI tools to MCP servers when both exist. Tools like gh or aws add no tool listings to the context, so they are more context-efficient than an MCP server for the same job. Disable MCP servers you are not using in /mcp.
  9. Filter noisy output with a hook. A hook is a script Claude Code runs at a fixed point, for example before every Bash command. It can rewrite a test command to print only failures, so a log of thousands of lines becomes a few hundred tokens instead of tens of thousands.
  10. Move specialized instructions from CLAUDE.md into skills. CLAUDE.md loads into every session; a skill loads only when it is used. Keep CLAUDE.md under about 200 lines.

Pick the model per subagent

A subagent works in its own context and returns a summary, which keeps the main conversation small. It does not save allowance: its requests count against the same limits. And unless something sets its model, it runs on the main conversation’s model, so a session on Opus runs all its research on Opus too. The built-in Explore subagent also uses the main model, not Haiku.

Set the model in the subagent’s frontmatter, the settings block between --- lines at the top of its file:

---
name: test-runner
description: Runs the test suite and reports only the failures
tools: Bash, Read
model: haiku
---
 
Run `npm test` and report only the failing tests with their errors.

model takes haiku, sonnet, opus, fable, a full model ID or inherit (the main conversation’s model). To give every subagent without its own model a default, set CLAUDE_CODE_SUBAGENT_MODEL. To force one model on all of them, add CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (v2.1.257 or later). Run /tasks while a subagent runs to see which model it is on.

Example

A Node API session on Opus at high effort runs the test suite after every change. The 2,000-test output lands in the context and rides along with every later request, and each run’s analysis is Opus thinking.

  • Move the test run into the test-runner subagent above: the full output stays in its context, on Haiku, and only the failures come back.
  • Or add a PreToolUse hook that pipes npm test through a filter for failing lines.
  • Drop to /effort medium for the routine fix-and-rerun loop, and raise it again for the hard bug.

Common mistakes

  • Switching models to escape a session limit. The session and weekly limits are shared across models.
  • Thinking a subagent is free. It saves context, not allowance.
  • Leaving a /loop running over lunch. Each run sends the whole conversation.
  • Coming back after a long break to a huge session. The first message misses the cache and re-processes everything. If the old context is not needed, /clear first.

Citations

  1. Manage costs effectively: reduce token usage
  2. Create custom subagents: choose a model
  3. Model configuration
  4. Pricing (Claude API)

Graph View

Backlinks