title: "Unexpectedly High Token Usage" last_updated: 2026-03-21 status: proven difficulty: intermediate prerequisites: [03-prompting-for-agents]

Problem: Unexpectedly High Token Usage

Symptoms

  • API costs are higher than expected
  • Sessions feel slow and expensive
  • The agent reads many files you didn't ask about
  • Simple tasks consume a surprising number of tokens

Common Causes

  1. Large context window — CLAUDE.md is too long, or the agent is reading entire large files when it only needs a section.
  2. The redo loop — You keep asking the agent to redo the same task with slightly different prompts instead of giving targeted corrections.
  3. No use of /compact — Long sessions accumulate context that's no longer relevant.
  4. Unnecessary exploration — The agent searches broadly when you could point it to the specific file.

Solutions

For Cause 1: Trim Context

# Keep CLAUDE.md concise — under 80 lines
# Point the agent to specific files instead of letting it search:

"Fix the bug in src/auth/login.ts on line 42"
# instead of
"Fix the login bug"

For Cause 2: Give Targeted Feedback

# Instead of:
"No, try again"

# Do:
"The function signature is correct, but the error handling on line 15 should use a try/catch instead of .catch(). Keep everything else."

For Cause 3: Use /compact

In Claude Code, run /compact when:

  • A session has been running for 20+ minutes
  • You're switching to a different subtask
  • The agent starts referencing outdated context

For Cause 4: Be Specific About Location

# Expensive (agent searches everything):
"Find and fix the performance issue"

# Cheaper (agent goes straight to the file):
"The performance issue is in src/api/search.ts — the database query on line 89 is missing an index. Fix it."

Prevention

  • Check /cost periodically during long sessions
  • Use the checkpoint-commit pattern to start fresh sessions
  • Point the agent to specific files when you know the location
  • See the token-burning anti-pattern for more strategies