Why Claude Code Token Usage Suddenly Spikes: Tutorial, Troubleshooting, and FAQ

Claude Code can feel efficient for days and then suddenly start consuming far more tokens for similar tasks. That does not always mean the product became more expensive or the model changed. More often, the session context, tool output, file scope, Hooks, MCP calls, or retry loops grew without anyone noticing.

The right approach is to ask what changed recently, then reduce context, narrow the task, or adjust the workflow.

Where tokens are spent

Token usage can include your prompt, files read by Claude Code, terminal output, test logs, error stacks, conversation history, tool results, CLAUDE.md, Memory, Hooks output, and the model’s own response. A short user message can still be expensive if the surrounding context is large.

Quick emergency steps

If quota is dropping too fast:

1. Start a new session.
2. Tell Claude Code which files it may read.
3. Avoid repository-wide analysis.
4. Paste only the last useful part of logs.
5. Disable unnecessary MCP tools temporarily.
6. Check whether Hooks print large output.
7. Split diagnosis and editing into separate steps.

Example:

1
2
3

Please only inspect src/auth/session.ts and tests/auth/session.test.ts.
Goal: find why login state is lost.
Do not scan the whole repository. Do not modify files. First give the diagnosis.

Cause 1: long sessions

Long sessions accumulate logs, file contents, plans, and old decisions. Later small tasks may still carry all that baggage.

Signs include slower responses, references to old discussion, repeated review of previous plans, and rising cost over time.

Use a new session for independent tasks, summarize long work before continuing, and move stable rules into CLAUDE.md instead of relying on conversation history.

Cause 2: too many files read

Broad prompts such as:

1

Help me optimize this project’s login logic.

invite the agent to search routes, components, state, tests, configs, and docs. Narrow the scope instead:

1
2

Please analyze the login refresh flow. Start with src/auth and tests/auth.
If you need other directories, explain why first.

If Claude Code keeps opening unrelated files, stop and restate the boundary.

Cause 3: long test and build output

Install logs, verbose test output, Playwright traces, TypeScript error floods, and Docker build logs can consume a lot of context.

Prefer narrower commands:

1

pnpm test -- auth

instead of:

1

pnpm test

Keep the meaningful error section and avoid pasting repeated output.

Cause 4: oversized CLAUDE.md

CLAUDE.md is useful, but not if it becomes a multi-thousand-line project encyclopedia. Keep only high-frequency rules: stack, commands, protected files, validation, and project-specific conventions.

Move long background documents into docs/ and reference them only when needed.

Cause 5: Memory pollution

Memory should store cross-project preferences, not one repository’s paths and commands. If temporary project facts enter long-term memory, Claude Code may carry them into other projects and spend more context on irrelevant rules.

Move repository facts back into CLAUDE.md or project docs.

Cause 6: Hooks output too much

Hooks can quietly add large diffs, full test logs, environment dumps, or repeated failure output to the conversation.

Prefer compact summaries:

1
2

lint failed: 3 errors in src/auth/session.ts
full log saved to .tmp/lint.log

Do not paste full logs into the model unless needed.

Cause 7: MCP returns too much data

Search, database, web, or code-index MCP tools may return full documents or hundreds of results. Limit result count and ask for summaries first:

1

Return only the 5 most relevant results. Do not expand full text. Explain why each result is relevant.

Use limit, page_size, or summary_only when available.

Cause 8: model switch

Sometimes token count is not the main change; the selected model changed. Stronger models, longer-context models, or higher-effort modes may consume quota differently. Check the current model, team defaults, and any recent configuration changes.

Cause 9: repeated failed retries

When commands fail repeatedly, each failure adds logs, explanations, patches, and new tool calls. After two failures, stop and ask for a summary:

1

Stop editing. Summarize the common cause of the last two failures and propose one minimal verification command.

Cause 10: abstract tasks

Abstract requests force exploration:

1

Improve this module.

Bounded requests reduce cost:

1
2
3

Only optimize the expiration cleanup logic in src/cache/store.ts.
Do not change the public API.
After editing, run tests/cache/store.test.ts.

Troubleshooting checklist

A token-efficient workflow

1. Define goal and boundary.
2. Let Claude Code read only necessary files.
3. First analyze, then edit.
4. Modify a small file set.
5. Run the smallest relevant test.
6. Trim failure logs.
7. Start a new session for the next task.

1
2
3
4

Goal: fix login refresh failure.
Scope: start with src/auth/session.ts and tests/auth/session.test.ts.
Limit: first round only, no edits, no full-repo scan.
Output: the 3 most likely causes and verification methods.

FAQ

Is a token spike a Claude Code bug?

Usually not. First check context length, file reads, tool output, Hooks, MCP, and model settings.

Does disabling MCP save tokens?

It can, if tools return large results. Better yet, limit result size and return summaries.

Should CLAUDE.md be very detailed?

No. It should contain stable rules that affect behavior. Put long background docs elsewhere.

Why can a small change use many tokens?

Because the whole session context, logs, and tool output matter, not just changed lines.

Does a new session lose important context?

It drops old details, which is often helpful. Reintroduce only the necessary conclusions.

How can a team control token usage?

Document a default workflow: read relevant files first, run minimal tests, trim logs, limit MCP output, and avoid broad prompts.

Summary

Sudden Claude Code token spikes usually come from accumulated context, broad tasks, long logs, oversized project instructions, Memory pollution, Hooks, MCP output, model changes, or retry loops. Start fresh, narrow the scope, trim logs, and automate only concise checks. The goal is not to use less context at all costs, but to spend context on the parts that actually matter.