Why Does Claude Code Keep Consuming So Many Tokens? Where Repeated Codebase Reads Waste Them, and How to Lower Context Costs

Your Claude Code session keeps growing, and a small code change is using more tokens than expected.

The fastest fix is to check what entered the session before assuming Claude Code reread the entire codebase. Narrow the task and file scope, trim tool output, keep project instructions focused, and start a fresh session when the work changes direction.

This guide is for developers investigating large repositories and trying to understand high token use.
It also helps engineers separating file reads from tool output and retained conversation context.
Team leads can use the checks to establish a repeatable context-management workflow.

Full repository reads versus repeated, targeted reads

Claude Code does not necessarily reread the entire repository on every turn. A high token total alone cannot establish that it did. The relevant evidence is the sequence of file reads, searches, commands, and responses in the session.

A repository task can involve several distinct operations:

• A search returns paths or matching lines.
• A later step opens one or more files found by that search.
• A test or build command returns logs.
• A follow-up inspects a different part of a file or revisits a previously inspected section.

Those operations add different material to the investigation. A repeated read of the same content can contribute again, but a newly opened file or fresh test failure is not redundant just because it concerns the same task.

To check what happened, review the session record and tool activity rather than estimating from repository size. The Claude Code interactive-mode documentation explains how to inspect the session transcript. Look for repeated file paths, repeated search output, and command results that are pasted back into the conversation. Then ask whether each repetition helped answer a new question.

Treat “Claude Code loaded the whole repository” as a hypothesis to verify, not a default explanation. A large checkout may contain many files that were never read during a particular session.

Three sources of context growth

Token use can rise because different kinds of material accumulate. Separating them makes the next action clearer.

File content enters when Claude Code inspects source files, configuration, documentation, or test fixtures. Reading a long file to answer a question about one function can introduce irrelevant sections. Reopening the same file may add more content, but the actual cost depends on what was read and what the session retained.

Tool output includes search matches, command results, test failures, stack traces, and responses from connected tools. A broad command can return much more text than the decision requires. The official MCP documentation describes output limits and warns when an MCP tool returns more than 10,000 tokens. That documented threshold is useful context for oversized tool responses, not a claim that every tool call uses that amount.

Conversation history includes the instructions, earlier findings, decisions, and follow-up questions that remain relevant in the current session. A long investigation can retain useful context, but it can also carry stale assumptions and unrelated task details. The interactive transcript helps you identify those earlier exchanges. Session history is not the same thing as a fresh read of every file in the repository.

These sources can overlap. A test error may prompt a file read; the explanation of that error then becomes part of the conversation. The important distinction is where the avoidable material entered: oversized file inspection, broad tool output, or a session that kept accumulating work after its goal changed.

Repeated reads and the cost of each investigation step

The waste is easiest to spot when the same information is repeatedly brought into the working context without changing the decision.

For example, a developer may ask for a general review of a large service. A broad search returns matches across several packages. Claude Code opens multiple files, then a test command emits a long log. The developer changes the question to focus on one API path, but the previous search and unrelated review remain part of the session. The cost is not simply “the repository was read twice.” It comes from an overly broad first pass, unnecessary output, and carrying unrelated exploration into the next task.

Now compare that with a scoped request: “Trace the request handler for this endpoint, identify the function that validates the input, and inspect the test covering invalid input. Do not review unrelated packages.” The assistant can still discover that another file matters, but the starting point is clearer and the investigation has a stopping condition.

The second request does not guarantee a particular token reduction. The amount depends on the repository, the task, the model, the commands run, and the output returned. It does make it easier to recognize an unnecessary read and stop before unrelated files enter the investigation.

Task boundaries and project instructions

A task boundary answers three questions: what you need to find, where to begin, and what result is enough. Without those limits, “look into this codebase” can invite searches that return far more material than a single debugging question requires.

Start by stating the outcome. For example, ask for the source of a failing test, the call path for one feature, or the reason one configuration value is ignored. Include a likely directory or entry point if you know it. Ask Claude Code to locate relevant files first, then inspect only the promising results. This separates navigation from detailed analysis.

Project instructions need the same discipline. Keep durable rules there: build steps, architecture constraints, naming conventions, or warnings about generated files. Put task-specific facts in the request for that task. Avoid repeating a large project overview in every prompt if the same information already exists in a maintained instruction file.

The official memory documentation explains how Claude Code discovers and loads memory files, including how to inspect what is active. Review the actual instructions being applied. A long or duplicated instruction set can add text without clarifying the current task.

The settings documentation distinguishes settings by scope, including user, project, and local configuration. Use the narrowest appropriate scope for a rule: a team-wide requirement belongs somewhere different from a personal preference. This avoids copying the same setup explanation into every request and makes it easier to see which instructions should apply.

Smaller tool outputs and cleaner session history

A command should return enough information to make the next decision, not every possible detail. If a search produces hundreds of matches, narrow the search path or pattern. If a test runner prints extensive logs, run the smallest relevant test where possible or capture only the failing section. If an error message is long, retain the first useful failure and the surrounding lines rather than repeatedly pasting the complete output.

Do not discard evidence blindly. A truncated log can hide the first failure or the context needed to diagnose it. The goal is to preserve the information that distinguishes likely causes while excluding unrelated output. When the right excerpt is unclear, ask Claude Code to identify the relevant error location and explain why the surrounding lines matter.

Separate investigations when the goal changes. A bug fix, a security review, and a broad refactor may share a repository but need different context. Before starting a new session, write a compact handoff containing confirmed facts, relevant paths, completed checks, and the unresolved question. Claude Code’s CLI usage reference documents ways to continue or resume sessions; choose deliberately rather than carrying a session forward by habit. A resumed session can be useful when prior context matters. A focused new one is cleaner when it does not.

Skills and commands also have different loading behavior. Check the official slash-command documentation before adding large reusable instructions: moving task guidance into a mechanism that loads at a different point can change what context is present. Keep reusable guidance concise and specific to the work it supports.

Common questions about token use

Why does Claude Code appear to revisit files?

A later question may require a closer inspection after an earlier search or test exposed a relevant path. That is different from automatically loading every file again. Compare the paths and content in the session record, then decide whether the repeated inspection supplied new evidence or only duplicated material already available.

Which source should you optimize first?

Use the transcript and usage categories together. If broad searches and commands dominate, tighten tool output. If long file contents recur, begin from a more precise entry point and inspect smaller sections. If the session contains several unrelated investigations, split them. The best target is the largest avoidable source in your own workflow, not a presumed universal cause.

What is a safe way to reduce codebase analysis scope?

Name the outcome and likely location, then request a focused search before detailed reading. Keep the result open-ended enough for Claude Code to follow a relevant dependency when evidence points there. If the search reveals a new path, inspect that path; do not continue exploring unrelated packages simply because they are present in the repository.

When should you start another session?

Start a separate session when the task changes materially or the existing conversation contains substantial background that no longer informs the next decision. Carry forward a short summary of verified findings, file paths, and unresolved questions. Keep the current session when its earlier reasoning or evidence is still necessary to complete the same investigation.

A repeatable review of context costs

Use this checklist after a task that felt unexpectedly expensive. It turns “the session used too many tokens” into a specific next change.

• [ ] Record the task goal and whether it stayed the same throughout the session.
• [ ] Review the transcript for repeated file paths and distinguish new evidence from duplicate inspection.
• [ ] Identify wide searches, large file reads, and long command or tool responses.
• [ ] Check whether project instructions repeat background already supplied in the request.
• [ ] Note when the session changed direction and whether a focused new session would have helped.
• [ ] Compare recorded usage for similar tasks, rather than comparing unlike investigations.
• [ ] Change one part of the workflow, then review the next comparable task before making another change.

The usage report is another useful signal. Its documented fields distinguish measures such as input_tokens, output_tokens, cache_read_input_tokens, and cache_creation_input_tokens; use those categories to compare runs instead of treating one total as proof of repeated repository reads. See the official usage-report field definitions. The report describes usage, while the transcript helps explain which actions contributed to it. Neither alone proves that one optimization caused a change.

For a fair comparison, keep the question and success criteria similar. Record the files visited, the amount of tool output, whether the session continued or restarted, and the usage measures available for each run. Different tasks, models, settings, and service rules can change the result. Do not turn one before-and-after example into a promised saving rate.

Choosing a development environment

If your current setup is a laptop, its availability depends on that device staying ready, and the local development environment may be difficult for a team to reproduce. A generic remote machine can help with access but may not fit a workflow that specifically needs macOS. Neither option changes Claude Code’s context behavior by itself: you still need to scope tasks, manage output, and review session history.

For occasional work, a local Mac or an existing remote environment may be the simplest choice. If your workflow needs a reachable remote Mac for development or AI-agent work, review the Hashvps package details and Hashvps AI-agent environment information to confirm whether the available offering fits your actual requirements. Do not assume a rental environment will reduce token use; its value is the development environment, while context costs still depend on how you use Claude Code.

This week, pick one expensive-feeling task and identify whether file content, tool output, or session history was the main avoidable source. Apply one change on the next comparable task, then check the transcript and usage report again. If the investigation also needs a stable remote Mac environment, use the Hashvps pages above to verify the fit before choosing a rental over a local machine or another remote setup.