Claude Code high CPU and memory use, and what to measure

The memory warning, and what to do about it

When a session's heap memory passes 2.5GB, a critical memory usage warning appears in the session. The documented recovery is to restart Claude Code and resume the conversation in a fresh process:

claude --continue

If memory use stays high after the steps further down this page, Anthropic's next step is the heap dump, taken while the process still holds the evidence:

/heapdump

What it writes. Two files, to ~/Desktop, or to your home directory on Linux when there is no Desktop folder: a JavaScript heap snapshot named <session-id>.heapsnapshot and a memory breakdown named <session-id>-diagnostics.json. Anthropic keeps the command out of the command menu, so type it in full.

What it prints. A summary in the conversation with the process's total memory, how much of that is in the JavaScript heap and how much sits outside it, and any leak indicators, such as a high memory growth rate or an unusually high number of open handles. It also says which of the two the memory is mostly in, because that decides what you can do next.

What to share. Only the -diagnostics.json file. The .heapsnapshot file contains every string in the process, including your full conversation and credentials, and Anthropic says not to attach it to a public issue or share it. The diagnostics file carries the statistics behind the printed summary and no conversation content.

If the summary says most memory is in the JS heap, open the snapshot in Chrome DevTools under Memory, then Load, and sort by retained size to see what is holding it. If it says most memory is native, the snapshot cannot show it, so include the summary's leak indicators in a bug report instead.

CPU is measured somewhere else

Anthropic's troubleshooting and commands pages document no CPU meter: the 2.5GB warning is about memory. The reporter on issue #19393 read CPU with top or ps aux, and the reproduction steps on issue #4953 use this form of the second one to watch the process:

ps aux | grep claude

Read the percentage next to the claude process while it is idle, at the prompt, with no turn running. A number that stays high there is the symptom the open CPU reports describe. The same reading during a long turn, or while tools run, is expected work.

Anthropic also points at /doctor inside a session for an automated check of your installation, settings, extensions and context usage, and at claude doctor from the shell when Claude Code will not start at all.

What grows memory, and which version changed it

Anthropic's own framing is that Claude Code may consume significant resources when it processes a large codebase. Beyond that, its changelog names the specific leaks and growth paths it has fixed. If you are on an older version, the row for your symptom is also the version to update past. Versions below are the release each change first appeared in.

The changelog is also where the answer most reports miss lives: a leak does not have to come from the conversation. The reporter on #18859 reports four idle sessions reaching about 15GB each over 18 hours while, by their reading of the debug log, the context size stayed at 6,664 characters the whole time.

The two output limits that bound the biggest sources

MAX_MCP_OUTPUT_TOKENS caps the tokens allowed in an MCP tool response. The default is 25,000, Claude Code warns when a response passes 10,000, and a successful text result longer than 50,000 characters from a tool that has no limit annotation is written to a file instead of held in the conversation. BASH_MAX_OUTPUT_LENGTH caps how many characters of bash output are read back into a command's result: default 30,000, maximum 150,000. Both are documented in Anthropic's environment variable reference, and both are set in the env block of a settings file.

Why CPU stays high, and which version changed it

The CPU side has the same shape as the memory side: Anthropic's changelog names loops it has fixed, one version at a time. A loop that survives on your machine is a reason to check your version before anything else.

Two of these look like an idle session doing nothing. The 2.1.268 entry is a busy loop in a long-running idle session, and the 2.1.271 entry is an MCP server sending list_changed notifications in a tight loop. The changelog names the release each change shipped in and attaches neither one to an issue number, so an update is the documented next step, not the fix for a particular report.

What bounds it

These are the steps Anthropic documents, in the order its troubleshooting page gives them, plus the two output limits that bound the largest inputs.

1. Compact the conversation. /compact summarizes what is already there and frees context. Anthropic's page also notes it frees memory outside fullscreen rendering, and that the 2.5GB warning clears once memory drops below that line. If it answers Not enough messages to compact., the conversation has too few turns to summarize, which can happen even in a full context when one large paste filled it.
2. Restart between major tasks. Anthropic's plain advice is to close and restart Claude Code between major tasks, and claude --continue is how you keep the conversation when you do.
3. Add large build directories to your .gitignore. That is Anthropic's own step for a large codebase.
4. Test with every customization off. claude --safe-mode disables CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles, workflows, themes, status line and file-suggestion commands, LSP servers and auto memory for the session. If usage drops, the culprit is one of those, and Anthropic's configuration debugging page walks through finding which.
5. Lower the MCP output ceiling. MAX_MCP_OUTPUT_TOKENS starts at 25,000 tokens per response. A server that returns large results is the case to lower it for.
6. Lower the bash output ceiling. BASH_MAX_OUTPUT_LENGTH starts at 30,000 characters. A command that prints megabytes is the case to lower it for.

The last two are environment variables, so they belong in a settings file rather than one shell. Anthropic documents the env block of ~/.claude/settings.json as the place for variables that every session should see.

Which reports are still open

Every issue below was read on October 26, 2026, and the state is the one GitHub showed that day. Three of the eight are closed, and the page says so rather than listing them as live.

Each of the five open reports names the version it was filed against. Run claude --version and compare before anything else: where your version is older than a row in the tables above, updating is the documented change to try. None of those rows says it closes any of these reports, and all five are still open, so treat an update as something that may help rather than as a fix.

What does not help

• Assuming it must be the conversation. The report used for that reading is a reporter's own log (#18859), and two changelog rows fix growth tied to what a session carries: subagent tool results in 2.1.238 and images in 2.1.121. The heap dump's split between heap and native memory is what settles which one you have.
• Attaching the heap snapshot to a public issue. Anthropic says it contains your full conversation and credentials. The -diagnostics.json file is the one to attach.

When the sessions are all yours

One Claude Code session that is busy is easy to account for. Six of them, each in its own terminal, is where a machine starts to feel taken over: every one of them is a separate process with its own heap and its own CPU slice. Omniscio is the desktop app we make for running several Claude Code sessions at once, and it carries two Windows performance levers for that case. A CPU cap, off by default, can bound the combined CPU the whole Omniscio process tree uses once other programs are competing for the machine.

The other one is memory reclaim, on by default. When free memory stays below a threshold you set, Omniscio trims the working sets of its own idle sessions, never one that is mid-reply or waiting on your answer. Both levers are Windows only, and neither one fixes a leak inside a Claude Code process. They bound what the fleet costs the rest of the machine. Installers are on the download page, and the features page lists what else is in the app today.

Sources

Every number and every quoted line above comes from one of these, read in its Markdown form on October 26, 2026.

• Troubleshooting, for the high CPU and memory section, the four documented steps, the 2.5GB warning, the /heapdump files and summary, and the warning about what the snapshot contains.
• Commands, for /compact, /clear and the /heapdump entry, including that the command is hidden from the menu.
• CLI reference, for claude --continue and claude --safe-mode, and what safe mode leaves out.
• Environment variables, for MAX_MCP_OUTPUT_TOKENS and BASH_MAX_OUTPUT_LENGTH.
• Debug your configuration, for the page safe mode sends a reader to when usage drops.
• Claude Code changelog, latest entry 2.1.310, for every version and every fix named in the two tables.
• The eight GitHub issues linked above, each read on October 26, 2026, for the reporter, the filed date, the state and the symptoms quoted.

The changelog carries no dates, so this page gives versions rather than release dates. When a row names a version, that is the release the change first appeared in.

Common questions

Why is Claude Code using so much memory?

Anthropic says Claude Code may consume significant resources when it processes a large codebase. Beyond that, its changelog names the leaks it has fixed: MCP responses, images, debug logging, subagent output and long sessions. /heapdump is how you find out which of them is your case, because its summary separates memory in the JavaScript heap from memory outside it.

What is the 2.5GB memory warning in Claude Code?

Anthropic documents a critical memory usage warning that appears when a session's heap memory passes 2.5GB. The documented recovery is to restart Claude Code and run claude --continue, which resumes the conversation in a fresh process. The warning clears once memory drops back below 2.5GB, and outside fullscreen rendering /compact frees memory too.

Does /heapdump share my conversation?

The .heapsnapshot file does: Anthropic says it contains every string in the process, including your full conversation and credentials, so it should not be attached to a public issue or shared. The -diagnostics.json file carries the statistics behind the printed summary and no conversation content, and Anthropic says to attach only that one.

Is high CPU use in Claude Code a known bug?

Some of it was, and Anthropic's changelog names the loops it fixed, including a busy loop in long-running idle sessions in v2.1.268 and repeated tool-list requests from an MCP server in v2.1.271. Others are still open: #19393 reports 100% or more CPU while idle on v2.1.12, and #22509 reports close to 100% at the prompt on v2.1.29.

Does restarting Claude Code fix high memory use?

It ends the current session's memory use, and claude --continue brings the conversation back in a fresh process, which is the step Anthropic documents for the 2.5GB warning. It is not a diagnosis. If the warning returns in a session that is not doing anything unusual, run /heapdump before restarting so the evidence survives.