Last updated 13 October 2026
Reduce Claude Code high memory usage
The indexing process and system resources
Claude Code can consume a large amount of memory when it tries to process a complex repository. You might notice your computer slowing down or the terminal window becoming unresponsive when the agent starts a large task. This happens because the agent is indexing your files to understand the project structure. It uses tools like Glob and Grep to scan through your code. Every file it reads and every piece of information it gathers must stay in the context window. If your project has thousands of files and you ask a broad question, the agent will try to hold as much information as possible to give an accurate answer. This behavior directly leads to high RAM usage in your terminal process.
When the agent performs a deep search, it creates a map of the relationships between different parts of your code. If you have large data files or hidden directories that are not part of your source code, the agent might still try to read them if they are not explicitly excluded. This increases the load on your system. You can monitor the current impact by checking your system activity monitor while a long command is running. If the memory usage climbs into the gigabytes, it is a sign that the agent is trying to handle too much context at once. Managing this scope is the key to maintaining a fast and responsive development environment.
Compacting the context window
The /compact command is your first line of defense against a bloated context window. As your session grows longer, the agent keeps a history of every interaction and every file it has viewed. This history takes up space in the context window. Running /compact instructs the agent to create a summary of the work done so far. It keeps the important conclusions and the current state of the task but removes the redundant history. This process shrinks the amount of data the agent has to track, which reduces the memory footprint of the active session. You should use this command whenever you switch to a new sub-task within the same session.
You can see how much you are spending on context by using the /cost or /usage commands. These commands give you an idea of how large your session has become. A high cost usually correlates with a large context window, which in turn correlates with higher memory usage. If the usage is high, a compaction will help keep the session manageable. It is better to compact early and often rather than waiting for the terminal to lag. This keeps the agent focused and prevents it from getting lost in the details of work you finished hours ago.
Restricting scope with ignore files
Your .gitignore file plays a critical role in how Claude Code perceives your project. The agent is designed to respect the rules you have already set for your version control system. If you have large folders full of compiled assets, dependencies, or temporary logs, ensure they are listed in your .gitignore. When the agent uses the Glob tool to find files, it will skip any path that matches your ignore patterns. This simple step prevents the agent from accidentally reading massive files that do not contain useful code. By narrowing the search space, you drastically reduce the memory required to index the project.
If you need to exclude files specifically from the agent but keep them in your git repository, you can use the settings files. Claude Code looks for settings in .claude/settings.json within your project folder. You can also use .claude/settings.local.json for settings that you do not want to commit to the repo. Within these files, you can configure permissions and tool access. If you know the agent should never touch a specific directory, you can set permissions to deny access to those paths. This ensures the agent never even attempts to load those files into its memory, keeping the process lean and efficient.
Using localized instructions for subdirectories
Using CLAUDE.md files effectively can guide the agent to use less memory. You should have a main CLAUDE.md in your repository root that contains general project instructions. However, you can also place a CLAUDE.md file in any subdirectory. When the agent is working within that subdirectory, it will read the local instructions. You can use these local files to tell the agent to only focus on specific files or to ignore certain patterns within that branch of the tree. This helps the agent maintain a smaller mental model of the project because it knows it only needs to care about the current folder.
Small, targeted instruction files prevent the agent from wandering off into unrelated parts of a large codebase. If you are working on a frontend component, the agent does not need to understand the backend infrastructure. By defining these boundaries in your markdown files, you limit the amount of code the agent reads into the context window. This localized approach is much more memory efficient than letting the agent explore the entire repository for every prompt. It also results in faster response times because the agent has less information to process before it can generate a solution.
Organizing work with session tiles
When you are dealing with several complex tasks across different parts of a project, the adhdTerminal app can help manage the load. Instead of having one massive terminal session that tries to do everything, you can split your work into separate tiles. adhdTerminal is a native app for macOS and Windows made by MINDBALANCER OU. It runs many Claude Code sessions side by side. Each tile has a color, a number, and a name. This allows you to isolate different parts of your project into their own sessions. By keeping each session focused on a small task, you ensure that no single session becomes so large that it consumes all your system RAM.
Each tile on the wall shows whether it is working, waiting for you, or idle. You can see the last exchanges of the conversation without even clicking into the tile. This visibility helps you monitor multiple memory-intensive tasks at once. If one tile is taking a long time to index a large folder, you can work on a different task in another tile. The sessions are persistent, so tiles reopen in the same place after a restart and resume the same session. This organization prevents the mental and technical overhead of managing multiple heavy terminal windows manually.
Clearing and resuming focused sessions
The /clear command is a useful way to reset the memory usage without quitting the agent. While /compact summarizes the session, /clear starts over in the same folder with a fresh context. This is the best option when you have finished a large feature and want to move on to something completely different. It wipes all the previously read files and conversation history from the agent's current memory. This immediately drops the RAM usage of the process to its baseline. It is a good habit to run /clear at the end of a long debugging session to ensure your next task starts with a clean slate.
If you are worried about losing your place, you can use the /resume command within a session or start the agent with claude --resume from your shell. This allows you to pick from a list of earlier sessions. This way, you can keep your active session small and focused. If you need to go back to a previous complex state, you can resume that specific session later. This strategy of using multiple short sessions instead of one long session is one of the most effective ways to manage memory. It keeps the context window small and prevents the agent from accumulating too much technical debt in its own memory.
Monitoring internal agent memory
Hook events allow you to automate some of your memory management. You can configure hooks in your settings to trigger certain actions at specific points in the conversation. For example, you can use the PreCompact hook to perform a final check before the session is summarized. You can also use the SessionEnd hook to log the final state of your memory usage. While the agent does not have a specific command to show a RAM graph, you can use the /status command to see the current state of the project and the agent. This gives you a high level view of what the agent is tracking.
The /memory command is also available inside a session. It provides information about the current state of the agent's memory. This is different from the system RAM used by the terminal process. It refers to the internal memory the agent uses to keep track of its tasks and goals. Monitoring this can help you understand when the agent is becoming overloaded. If the internal memory is full, the agent may start to struggle with complex instructions. In these cases, using /compact or breaking the task into subagents can help distribute the load.
Delegating tasks to subagents
Subagents are another powerful way to distribute the memory load of a large project. You can define custom subagents in .claude/agents using markdown files. A subagent can be designed to handle a specific type of task, like writing tests or refactoring a specific module. When you use the /agents command, you can see the available agents. By delegating a portion of a task to a subagent, you are effectively creating a new, smaller context window for that specific job. This prevents the main session from becoming bloated with the details of every minor change.
When a subagent finishes its work, the SubagentStop hook event is triggered. You can use this to clean up or to summarize the results back into the main session. This modular approach to coding with an agent is similar to how you would organize a team of human developers. Each agent has a specific scope and only needs to hold a small amount of code in its memory at any given time. This not only saves system resources but also improves the accuracy of the agent's work because it is not being distracted by irrelevant files.
Managing heavy sessions remotely
If you find that a particular session is still too heavy for your local machine, you can use the adhdTerminal iPhone app to stay connected to your work. The app mirrors your wall of tiles over an end-to-end encrypted link. This means you can keep a memory-intensive indexing task running on your main computer while you step away. You can check the status of the wall on your phone to see if the agent has finished its work or if it has hit a permission prompt. The app allows you to answer a prompt or send the next task directly from your mobile device.
This flexibility is important for developers who work on large codebases that take a long time to process. You do not have to stay tethered to your desk just because a session is consuming a lot of resources. The encrypted link ensures that your code remains private while you manage your tasks remotely. It costs 99 dollars once, and one key runs one computer at a time. This single payment model is simple and avoids recurring costs. Using a combination of local session management and mobile monitoring gives you total control over your development workflow without being slowed down by high memory usage.
Questions people ask
What is the difference between /compact and /clear?
The /compact command creates a summary of your conversation to free up space in the context window while keeping essential facts. The /clear command wipes the session context entirely, allowing you to start fresh in the same directory. Use /compact for long tasks and /clear when switching to a completely new problem.
How can I see how much RAM the agent is using?
You should check your operating system's activity monitor to see the RAM usage of the terminal process running Claude Code. Inside the session, you can use the /memory command to check the agent's internal memory state. High system RAM usage is usually a sign of a very large context window filled with many files.
Does Claude Code work with very large files?
The agent can read large files, but doing so will quickly fill the context window and increase memory usage. It is more efficient to use the Grep tool to find specific snippets or to provide the agent with narrow file paths. If you have files that are several megabytes in size, try to keep them out of the agent's scope using .gitignore.
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.