Agents UI
To reduce Claude Code token usage, start with /context to see what is filling the conversation. Keep file reads and command output focused on the task. Use /compact when you need to continue the same investigation, and /clear when you are moving to unrelated work.
The useful question is what Claude needs to make the next correct decision. A stack trace, two relevant functions, and a failing test can be a better starting point than an entire repository and a long conversation about yesterday's feature.
This guide covers the commands, a worked debugging example, and the mistakes that make a session repeatedly fill up. The examples assume you already have Claude Code running in a project. Enter slash commands inside Claude Code; enter shell commands in your terminal.
Context size, token usage, and usage limits are different
The context window is the information available to the model for a request. It includes conversation history, instructions, file contents, and tool results. Claude Code can summarize older conversation history automatically as the window fills, but a summary may omit a detail you still care about. See Anthropic's explanation of how Claude Code manages context.
Token usage measures processing across requests. A session can make many requests, so its total usage can exceed the amount of text that fits in one context window. A subscription usage limit is a separate allowance: freeing context does not reset that allowance. Anthropic's guide to models, usage, and limits explains the distinction.
That gives you three different troubleshooting paths:
| What you notice | What to investigate | Useful first action |
|---|---|---|
| The conversation keeps compacting | What occupies the current window | Run /context and inspect the largest categories |
| A small change takes many turns | Repeated searches, corrections, and tests | Name the failing behavior and define one verification command |
| Claude reports a plan usage limit | The account's remaining allowance | Check /usage; compaction cannot restore the allowance |
For API users, /usage includes session token and cost information. Subscription users also see plan usage information; an API-style cost figure is not the same as their subscription bill. The available display depends on the account and connection. See the official usage tracking documentation.
Start with a before-and-after context check
Run this before a representative task:
/context
After the first investigation or test run, run it again. Look for what grew. You do not need a universal threshold such as "compact at 70 percent" to act on an obvious source of noise.
For example, if opening a log consumes much of the remaining space, repeatedly compacting will not fix the workflow. The next full log read can fill it again. Ask for the relevant event and its surrounding lines. If the session starts with substantial context already loaded, examine the instructions and integrations you actually need for this project.
The Claude Code command reference documents /context, /compact, /clear, and /mcp. Commands can vary by version and environment; /help shows what your installation offers.
Give the agent a smaller, complete task
Consider a checkout bug: a customer receives a discount twice after retrying a payment.
This request leaves the investigation wide open:
Read the checkout code and fix the discount problem.
A more useful starting point includes the evidence, a boundary, and a stopping condition:
Fix a duplicate discount after a payment retry.
Observed: a 100.00 order with a 20% discount becomes 64.00 after retry.
Expected: the total remains 80.00.
Start with src/checkout/apply-discount.ts and its existing test file.
Trace callers only if those files do not explain the behavior.
Add a regression case for applying the same discount twice.
Preserve the public API and avoid unrelated checkout changes.
After the focused test passes, run the checkout package checks.
Report the cause, changed files, and verification results.
These are example paths, not a framework requirement. Substitute the paths and commands from your repository. If you do not know the relevant file, ask Claude to locate candidates and explain which one it will inspect first. A short search stage is useful; an arbitrary file limit that hides a dependency is not.
This prompt also gives you a way to notice drift. If the agent starts redesigning payments, return it to the duplicate-discount behavior. For more examples, see prompt engineering for AI coding agents.
Reduce tool output without hiding the failure
Search for candidate filenames, inspect matching lines, and then read the relevant code. In a repository with a src/checkout directory and ripgrep installed, that could look like:
rg --files src/checkout -g '*.ts'
rg -n -C 4 'applyDiscount|retryPayment' src/checkout -g '*.ts'
The first command helps locate files. The second includes nearby lines, so a match has some context. Neither requires pasting every checkout source file into the conversation.
Use the same approach with tests: begin with the regression case, then the relevant package, then whatever wider checks the change requires. A focused run makes it easier to see which edit affected the failure. The test-first workflow guide explains that sequence.
When output is large, ask for the failure summary, the complete relevant stack trace, and the command's exit status. Keep the full log available for follow-up. A truncated log that omits the assertion or a filter that accidentally makes a failed test look successful can cost more time than the tokens it saves.
When to use compact versus clear
Use the task boundary to decide:
| Situation | Action | What to carry forward |
|---|---|---|
| The same bug still needs a fix | /compact with specific instructions |
Reproduction, constraints, evidence, next step |
| Checkout is finished; next is a docs redesign | /clear |
The new task brief and any shared project rules |
| Several attempted fixes have confused the investigation | Write a reviewed handoff, then /clear |
Confirmed facts and the current diff |
| You are still using the current evidence productively | Continue | No summary is needed just to meet an arbitrary percentage |
For the checkout investigation, a focused compaction command could be:
/compact Preserve the duplicate-discount reproduction, the public API constraint, changed file paths, exact test results, rejected hypotheses with evidence, and the next verification step.
After compaction, ask Claude to restate the expected behavior and next action. Compare them with the actual files and test result. That quick check can catch a summary that dropped the retry condition.
Before starting a fresh conversation, save a short handoff in a task note. Here is one for the same example:
Goal: retrying payment must not apply the same discount twice.
Expected: 10000 cents with 20% off remains 8000 after retry.
Evidence: the retry path calls the discount helper with an already reduced total.
State: regression test added; implementation still fails it.
Constraint: preserve the public checkout API.
Next: inspect the retry caller and choose where to keep the original subtotal.
Verify: run the regression case, then checkout package checks.
Review that note before relying on it. Include the branch or worktree when you have several open. After /clear, provide the note and ask Claude to confirm the working directory and current changes before continuing. Our session handoff guide covers longer tasks.
Clearing conversation history does not undo edits to the project. It also does not make a terminal session, a Git branch, and a model conversation the same thing. Keep the code state and the conversational state explicit.
Check recurring overhead and repeated work
If fresh sessions are already crowded, separate stable project guidance from a running task diary. Build commands, architectural boundaries, and important conventions belong in persistent guidance. Yesterday's unsuccessful debugging transcript is usually better kept as a separate note that you load when relevant.
Inspect /mcp if you have many integrations. Keep the ones this task needs and investigate their actual contribution in /context. Current Claude Code can defer MCP tool definitions, so counting configured servers alone does not tell you their token footprint. Anthropic describes this in its cost management guidance.
There is also a tradeoff in restarting too often. Claude Code uses prompt caching to reuse previously processed input. Cached input still occupies context, and rebuilding a conversation can require reading the same files again. Caching and compaction solve different problems. See how Claude Code uses prompt caching.
For your own workflow, compare a few similar tasks. Record whether the change passed review, how often you corrected the agent, whether it repeated earlier investigation, and the usage shown for the session. Those observations are more useful than a promised percentage saving from a particular prompt.
Common questions
Does compact reset the Claude Code usage limit?
No. Compaction makes room in the conversation by summarizing history. It does not refund earlier processing or reset the account's usage allowance. Check /usage when the problem is an account limit.
Should I clear after every code change?
Use a fresh conversation when the task changes or the history is misleading. Keep a useful investigation together while its evidence still matters. Clearing after every small edit can make the agent repeat work.
Why does the context window fill up again immediately?
Look for the same large input being loaded repeatedly: an entire log, broad source searches, or an oversized response from a tool. Change that input at the source. A smaller summary cannot help for long if the next action reloads all the noise.
Can a different terminal increase the context window?
No. A terminal can help organize sessions and keep their output accessible, but it does not increase the model's context capacity or change the account's usage limits. The improvement comes from keeping each task's evidence easy to find and giving Claude the information it needs next.