Try free

Last updated 13 October 2026

Fix Claude Code memory limits on Windows

Windows terminal sessions crash during large indexing tasks

Your Claude Code session on Windows just died without warning. You were likely asking the agent to index a large directory or perform a complex refactor across dozens of files. Suddenly, the terminal displays a wall of text ending in a JavaScript heap out of memory error. This happens because the underlying runtime has a default memory limit that is too small for heavy coding tasks. Windows users often face this sooner than those on other systems because of how the environment handles memory allocation for command line tools. When the agent uses the Glob or Grep tools to search through a massive repository, it stores metadata in memory. If your project has thousands of files or deeply nested folders, that metadata quickly exceeds the standard one or two gigabyte limit set by the system runtime.

The crash is particularly frustrating because it destroys your current interactive session. You lose the immediate context of your conversation, and any uncommitted changes might be left in a half finished state. While you can use the claude --continue command to try and pick up where you left off, the memory pressure remains. If you do not change how the system allocates resources to the claude command, the agent will simply crash again the next time it tries to read a large file or scan the directory tree. This is not a bug in the agent itself but a limitation of the environment it runs in on Windows. You must tell the system to allow the process to use more of your available hardware RAM to handle the scale of your codebase.

Adjusting the runtime heap size fixes memory errors

To stop these crashes, you need to set an environment variable called NODE_OPTIONS. This variable tells the runtime how much memory it can claim from your system. By default, this is often limited to a fraction of your total RAM. For a developer machine with sixteen or thirty-two gigabytes of RAM, you should increase this limit significantly. You can do this temporarily in your current PowerShell or Command Prompt window to test if it solves the problem. In PowerShell, you would type a command to set the environment variable for the session, specifically setting the max old space size to a value like eight thousand one hundred and ninety-two. This value represents eight gigabytes of memory, which is usually enough for even the largest project indexing tasks.

After you set this variable, run the claude command again. The agent will now have the breathing room it needs to use the Read and Glob tools on large file sets without hitting a wall. You will notice that the agent becomes more stable during long sessions where the conversation history has grown large. If you still see crashes at eight gigabytes, you can increase the number further, provided your physical hardware supports it. Most developers find that eight or twelve gigabytes is the sweet spot for balance between the agent's needs and the needs of their IDE and browser. Remember that this temporary setting only lasts until you close your terminal window. To make the fix permanent, you must change your system settings.

Configure permanent environment variables for the command line

To ensure every new session of Claude Code has enough memory, you should add the NODE_OPTIONS variable to your Windows User Environment Variables. Open the Start menu and type environment variables, then select the option to edit your account variables. Create a new variable named NODE_OPTIONS and set the value to include the flag for max old space size followed by your chosen megabyte count. Once you save this and restart your terminal, any instance of the claude command will automatically inherit these settings. This removes the need to remember manual commands every time you start work. It also ensures that background processes and subagents launched by the main tool have the same expanded memory pool to work with.

If you prefer using the command line to manage your system, the setx command is an alternative way to apply this change permanently. Running setx within a terminal will write the variable to your Windows registry. Be aware that you must open a fresh terminal window for the changes to take effect. If you are using a specific terminal emulator like Windows Terminal or a shell inside your IDE, verify that it is picking up the new variable by checking the environment state. Stable memory allocation is the first step toward a reliable workflow. Without it, you will spend more time restarting your agent than actually writing code or solving architectural problems.

Manage internal session context to reduce memory pressure

Even with expanded system memory, you should practice good context hygiene to keep the agent fast. Every file the agent reads and every message you send adds to the context window. As this window fills up, the agent has more data to process, which can slow down response times and eventually strain the heap again. You can use the /compact command inside a session to manage this. This command summarizes the conversation so far and clears out the older, detailed logs while keeping the important facts. It effectively resets the memory usage of the current session without losing the progress you have made on your task. It is a good habit to run this after finishing a major subtask or if you notice the agent is taking longer than usual to think.

If a session becomes too cluttered or if you are switching to a completely different part of the project, use the /clear command. This starts a fresh session in the same folder, wiping the current context entirely. This is the most effective way to drop memory usage to zero for that specific instance. If you find yourself needing to jump back and forth between different problems, do not try to do it all in one long session. Instead, use the /resume command to switch between distinct sessions you have previously started. This keeps the memory footprint of each individual task small and manageable, preventing the agent from getting confused by irrelevant code from a different part of the repository.

Organize complex projects with adhdTerminal wall tiles

When you are working on a large Windows project, you often need to run multiple sessions of Claude Code at once. One session might be dedicated to running tests with the Bash tool, while another focuses on refactoring a specific module using the Edit tool. Managing these multiple terminal windows on a single monitor is difficult and often leads to hidden windows that continue to consume memory in the background. This is where adhdTerminal provides an honest solution for the developer. It allows you to run many Claude Code sessions side by side as tiles on a single wall. Each tile is a live session that shows you exactly what the agent is doing, whether it is working, waiting for your input, or sitting idle.

Using adhdTerminal helps you maintain a visual map of your project. You can give each tile a name and a color to represent different parts of your codebase. Because the tiles show the last few exchanges of the conversation directly on the wall, you do not have to click into every window to remember where you left off. This visual organization reduces the mental load of managing several high memory processes on Windows. If you need to restart your computer, adhdTerminal reopens all your tiles in their original positions and resumes the sessions. This persistence, combined with the ability to monitor multiple tasks at a glance, makes it much easier to stay focused on complex development work without getting lost in terminal tabs.

Limit the scope of tools to prevent overflow

The way you structure your project files also affects how much memory Claude Code consumes. The agent respects your .gitignore file, so ensure that large build artifacts, dependency folders like node_modules, and temporary log files are properly excluded. If the agent tries to use the Glob or Grep tools on these folders, it will waste massive amounts of memory processing data that is not relevant to your code. You can further refine this by using a CLAUDE.md file in your project root. Use this file to provide specific instructions to the agent about which directories are important and which should be ignored during broad searches. You can also place additional CLAUDE.md files in subdirectories to give the agent more localized context for specific modules.

By guiding the agent with clear instructions, you prevent it from performing expensive operations that lead to memory exhaustion. For example, if you know a specific directory contains thousands of small generated files, tell the agent never to use the Read tool on the entire folder. Instead, instruct it to look for specific entry points. This targeted approach keeps the context window lean and the memory usage low. You can also define custom behaviors in .claude/settings.json to restrict tool permissions if you find the agent is being too aggressive with project wide searches. Setting these boundaries ensures that the agent works within the limits of your hardware while still being effective at solving coding problems.

Monitor resource consumption with built in commands

To stay ahead of memory issues, you should regularly check the health of your installation and the cost of your sessions. Running the claude doctor command from your shell will check your environment for common issues and ensure everything is configured correctly. Inside a session, you can use the /status command to see a summary of the current state, including which tools are active and what permissions are set. This helps you identify if the agent is stuck in a loop or performing an unexpectedly large task that might be eating up your system RAM. If the agent seems slow, checking the status is the first step in diagnosing a potential memory bottleneck.

You should also monitor your usage and spend with the /usage and /cost commands. While these primarily track your API consumption, a sudden spike in cost often correlates with the agent reading a massive amount of file context into memory. If you see a high cost for a single prompt, it is a sign that the agent is pulling in more data than necessary. This is your cue to use the /compact command or to refine your CLAUDE.md instructions. Keeping an eye on these metrics allows you to run a more efficient development environment on Windows. By combining proper runtime configuration, smart context management, and proactive monitoring, you can turn Claude Code into a stable and powerful part of your daily workflow.

Questions people ask

What is the recommended memory limit for Claude Code on Windows?

For most professional development projects, setting the heap size to 8192MB is sufficient. If you work on extremely large monorepos with tens of thousands of files, you may need to increase this to 12288MB or 16384MB. Always ensure you leave enough RAM for your operating system and IDE to function smoothly.

Why does /compact help with memory issues if I have already increased the heap?

The heap size limits the total RAM the process can use, but the context window limits how much information the agent can process at once. Even with a large heap, a very long conversation can slow down the agent as it tries to track every detail. The /compact command reduces this internal data load, making the agent more responsive and less likely to hit processing bottlenecks.

How can I tell if a crash was caused by memory or a network error?

A memory crash on Windows will usually print a JavaScript heap out of memory error in the terminal and immediately exit to the shell prompt. A network error or API timeout will typically be caught by the agent, showing a retry message or an error within the interactive interface. You can run claude doctor to see if your environment has persistent configuration problems that might mimic a crash.

Read next

More on when it goes wrong·All posts