Warn when memory is critical

High CPU or memory usage

Claude Code is designed to work with most development environments, but may consume significant resources when processing large codebases. If you're experiencing performance issues:

1. Use /compact regularly to reduce context size. If it returns Not enough messages to compact., the conversation has too few turns to summarize; that can happen even with a full context when a single large paste filled it
2. Close and restart Claude Code between major tasks
3. Consider adding large build directories to your .gitignore file
4. Restart with claude --safe-mode to check whether a plugin, MCP server, or hook is the source. It disables all customizations for the session; if usage drops, see Debug your configuration to find which one

If a session's heap memory passes 2.5GB, a critical memory usage warning appears. To free the memory, restart Claude Code and run claude --continue to resume the conversation in a fresh process.

Outside fullscreen rendering, running /compact frees memory too. The warning disappears once memory use drops back below 2.5GB.

If memory usage stays high after these steps, run /heapdump to write two files to ~/Desktop: a JavaScript heap snapshot named <session-id>.heapsnapshot and a memory breakdown named <session-id>-diagnostics.json. Claude Code hides the command from the command menu; type it in full. On Linux without a Desktop folder, the files are written to your home directory.

The .heapsnapshot file contains every string in the process, including your full conversation and credentials. Don't attach it to a public issue or share it.

The command also prints a summary in the conversation, showing resident set size, JS heap, array buffers, and unaccounted native memory, plus any leak indicators it detected, such as a high memory growth rate or an unusually high number of open handles. The summary says whether most memory is in the JS heap, which the snapshot captures, or in native memory, which it doesn't.

Report the output or investigate it yourself:

• Report it: open a GitHub issue and attach only the -diagnostics.json file, which carries the statistics behind the printed summary and no conversation content or credentials
• Investigate it yourself: if the summary says most memory is JS heap, open the .heapsnapshot file in Chrome DevTools under Memory → Load and sort by retained size to see what's holding the memory

If the summary says most memory is native, the snapshot can't show it; include the summary's leak indicators in your report instead.