Last updated 13 October 2026
Reduce Claude Code token usage on large repos
Large repositories fill the context window fast
When you run Claude Code in a massive codebase, every file the agent reads adds to the input tokens. The agent uses the Read tool to look at your code and understand how it works. If the project has thousands of files, a simple search can pull in more data than the context window allows. This leads to errors where the agent forgets earlier parts of the conversation or fails to complete a task because the window is full. You see this happen when the agent starts repeating itself or loses track of the instructions you gave at the start of the session.
The context window includes your prompt, the file contents the agent has read, and the history of its actions. Tools like Glob and Grep help the agent find files, but every file it opens stays in the session memory. If the agent reads a large library file or a heavy data file, your token usage spikes. This is why you must control what the agent can see. Limiting the scope of the session is the most effective way to keep your token costs low and ensure the agent remains accurate throughout the development process.
Isolate tasks with subdirectory instructions
You can control what the agent focuses on by using CLAUDE.md files in specific subdirectories. While a CLAUDE.md file in the repo root sets the global rules, a CLAUDE.md file in a subdirectory applies specifically to that part of the tree. If you are working on a frontend component, start your session in that specific folder or add a guide there. This tells the agent that the relevant context is limited to that directory. It prevents the agent from wandering into the backend or infrastructure code when it does not need to.
When the agent sees a CLAUDE.md file in its current working path, it prioritizes those instructions. You can use these files to define the boundaries of a task. Tell the agent which files are relevant and which ones it should ignore for the current work. This reduces the number of times the agent uses the Read tool on unrelated files. By narrowing the focus, you ensure that the tokens you spend are used only on the logic that matters for your current ticket.
Use the ignore file to filter out irrelevant data
Claude Code respects your .gitignore file by default. This is your first line of defense against token waste. If your repository contains large build artifacts, log files, or compiled binaries that are not ignored, the agent might try to read them. This consumes a massive amount of tokens for data that the agent cannot even use. Check your .gitignore file to ensure that it covers all non-source files that do not need to be indexed or read during a coding session.
If you have files that you want to keep in the repository but hide from the agent, you can update your .gitignore or use the /config command to adjust how the agent interacts with your files. The agent relies on the Glob tool to list files and the Grep tool to search through them. If these tools return hundreds of irrelevant results, the agent has to process all of them. Keeping your project tree clean and your ignore rules strict is a direct way to save money and context space.
Summarize the conversation to reclaim space
As a session grows longer, the history of every command and every file edit begins to crowd the context window. You can use the /compact command to fix this. This command summarizes the session so far and frees up space. It keeps the essential information about what has been done but removes the line-by-line history of previous tool outputs. This is particularly useful after a long period of debugging where the agent has read many files and tried several different fixes.
Running /compact is like a mental reset for the agent. It keeps the context window lean without losing the progress you have made. If you find the agent is becoming slow or starting to hit context limits, /compact is the fastest way to continue without starting over. You can also use the /clear command if you want to start a fresh session in the same folder, which completely empties the context window for a brand new task.
Delegate specialized work to subagents
Subagents are a powerful way to keep the main session focused. You can define subagents as markdown files in the .claude/agents directory. When you use the /agents command, you can move specific, isolated tasks to a subagent. This subagent starts with its own fresh context. It does not carry the weight of the main conversation, which saves tokens. Once the subagent finishes its task, it returns the result to the main session.
This approach is ideal for large repositories where you need to research a specific module or write a unit test. Instead of the main agent reading the entire test suite, a subagent can handle that specific job. This keeps the main context window available for high-level architectural decisions and coordinates the work without bloating the session. Using subagents forces you to modularize your requests, which naturally leads to lower token consumption.
Review costs and usage within the terminal
You should monitor your spend frequently to understand which actions are the most expensive. Use the /cost command to see the cost of the current session. Use the /usage command to see your overall activity. If you notice a single prompt cost much more than expected, it is likely because the agent read a very large file or performed a wide search that returned too much data. Monitoring these figures helps you adjust your instructions in CLAUDE.md to prevent similar spikes in the future.
The /status command also provides a view of what is happening in your current environment. By keeping an eye on these metrics, you develop a better sense of how your repository size impacts your token usage. If the costs are rising too fast, it may be time to use /compact or to break the task into smaller pieces. Knowledge of your current usage prevents surprise bills and helps you stay within the limits of the context window.
Manage multiple focused sessions with adhdTerminal
Running one massive session for an entire day is the fastest way to run out of context space. A better strategy is to keep several small, focused sessions open for different parts of your project. adhdTerminal is a native app for macOS and Windows that lets you run many Claude Code sessions side by side. Each session is a tile on a wall, and tiles reopen in the same place after a restart. This allows you to have one tile for the frontend, one for the API, and one for documentation.
By using adhdTerminal, you keep each session small and task-specific. Instead of one agent trying to remember the whole repository, several agents handle small parts of it. A tile has a colour, a number and a name, and it shows whether it is working, waiting for you, done or idle. This visual overview makes it easy to manage multiple contexts without them bleeding into each other. Keeping your sessions separate in this way is an honest and effective method to minimize the tokens each individual session uses.
Interrupt the agent to prevent runaway loops
Sometimes the agent gets stuck in a loop. It might use the Glob tool repeatedly or try to Read the same files over and over. This wastes tokens every second the agent is running. You can press the Escape key to interrupt what the agent is doing immediately. If you see the agent heading in the wrong direction or starting a massive search that you know is unnecessary, stop it right away. This saves the tokens that would have been spent on the rest of that execution.
Pressing Escape twice offers you a list of earlier messages so you can go back to a point before the agent went off track. This is often better than trying to correct the agent with a new prompt, which would only add more tokens to the history. By jumping back to an earlier state, you prune the conversation and keep the context window clean. Using the /permissions command can also help by requiring the agent to ask before it performs expensive operations or reads certain directories.
Questions people ask
How can I see exactly which files are currently in the context window?
The /status command provides information about the current state of your session. While it does not always list every individual file in a simple list, it gives you an overview of the environment and any active configurations. You can also review the conversation history to see which files the agent accessed using the Read tool.
What is the difference between /clear and /compact for saving tokens?
/clear wipes the entire conversation history and starts the session over in the same folder, which uses the least amount of tokens. /compact summarizes the conversation so far into a shorter form, preserving the context of your progress while freeing up space in the window. Use /compact if you need the agent to remember what it just did, and /clear if you are starting a completely new task.
Does Claude Code read my entire repository when I start it?
No, Claude Code only reads files when it needs to using tools like Read, Glob, or Grep. However, it may index your file names to help it navigate. To prevent it from reading large sections of your code, ensure your .gitignore is configured correctly and use subdirectory CLAUDE.md files to limit its search area.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.