Fix Claude Code Performance

## TL;DR

When Claude Code feels slow, hangs, or consumes a lot of CPU or memory, the cause is almost always context size or a misbehaving customization, not a fixed "memory leak." The documented fixes are:

- Run `/context` to see what is filling the context window.
- Run `/compact` to summarize older history, `/clear` to start fresh between tasks.
- Restart Claude Code between major tasks, and add large build directories to `.gitignore`.
- Use `claude --safe-mode` to test whether a plugin, MCP server, or hook is the source.
- Run `/doctor` inside Claude Code, or `claude doctor` from your shell if it will not start.

## Overview

Claude Code is designed to work with most development environments but can consume significant resources when processing large codebases. Performance and stability issues group into a few documented categories: high CPU or memory usage, auto-compaction thrashing, hangs and freezes, and search problems. The single biggest lever for most of them is how much is loaded into the context window, because token cost and processing both scale with context size.

This guide covers the supported commands and steps from Claude Code's own troubleshooting, cost, and context-window documentation. It avoids unverifiable claims about exact RAM figures or "memory limit" settings, because Claude Code does not document a user-facing memory cap; instead it gives you tools to measure usage (`/context`, `/usage`, `/heapdump`) and to reduce it.

## Diagnose first

Before changing anything, find out where the resources are going.

```bash
# Inside an interactive Claude Code session:

/context     # Live breakdown of the context window by category, with suggestions
/usage       # Token usage for the current session (press d/w for 24h vs 7d)
/memory      # Which CLAUDE.md and auto-memory files loaded at startup
/mcp         # Configured MCP servers; disable ones you are not using
/doctor      # Automated check of install, settings, MCP servers, and context

# From your shell (use this if `claude` will not start at all):
claude doctor
claude --version    # Confirm which build you are on before reporting an issue
```

`/context` is the most useful starting point: it shows the live breakdown by category (system prompt, CLAUDE.md, MCP tools, files read, conversation history) so you can see what to trim. If `claude` will not launch, run `claude doctor` from the shell instead of `/doctor`.

## Symptom to fix reference

| Symptom | What to do |
| :--- | :--- |
| High CPU or memory usage | `/compact` regularly; restart between major tasks; add large build dirs to `.gitignore`; try `claude --safe-mode` |
| Memory stays high after the above | Run `/heapdump` to write a heap snapshot and memory breakdown to `~/Desktop`; do not upload the heap snapshot publicly, and share only redacted diagnostics through private support if requested |
| `Autocompact is thrashing...` error | Read oversized files in smaller chunks; `/compact keep only the plan and the diff`; move big reads to a subagent; `/clear` if history is no longer needed |
| Command hangs or freezes | Press Ctrl+C to cancel; if still stuck, close the terminal and reopen, then `claude --resume` |
| Slow responses / large token use | Use `/context` to find the bloat; `/clear` between tasks; switch to Sonnet with `/model`; lower thinking effort with `/effort` |
| Settings/hooks/MCP misbehaving and slowing things | `claude --safe-mode` disables all customizations; if usage drops, find the culprit per Debug your configuration |
| Garbled text in an editor's integrated terminal | Run `/terminal-setup` to turn off GPU acceleration |
| Search not finding files | Install your platform's `ripgrep`, then set `USE_BUILTIN_RIPGREP=0` |

## High CPU or memory usage

Work through these documented steps in order:

1. Use `/compact` regularly to reduce context size.
2. Close and restart Claude Code between major tasks.
3. Add large build directories to your `.gitignore` file so they are not scanned.
4. Restart with `claude --safe-mode` to check whether a plugin, MCP server, or hook is the source. Safe mode disables all customizations for the session; if usage drops, the cause is one of your customizations.

If memory usage stays high after these steps, run `/heapdump`. It writes a JavaScript heap snapshot and a memory breakdown to `~/Desktop` (or your home directory on Linux without a Desktop folder). The breakdown shows resident set size, JS heap, array buffers, and unaccounted native memory, which tells you whether growth is in JavaScript objects or native code. You can open the `.heapsnapshot` file in Chrome DevTools under Memory then Load to inspect retainers. Do not attach heap snapshots to public GitHub issues; share only redacted memory breakdowns or excerpts through a private support channel if requested.

## Auto-compaction thrashing

Claude Code compacts automatically as you approach the context limit, so a full window does not end your session. If you instead see `Autocompact is thrashing: the context refilled to the limit...`, compaction succeeded but a file or tool output immediately refilled the window several times in a row, so Claude Code stops retrying to avoid wasting API calls on a loop. To recover:

1. Ask Claude to read the oversized file in smaller chunks (a line range or a single function) instead of the whole file.
2. Run `/compact` with a focus that drops the large output, for example `/compact keep only the plan and the diff`.
3. Move the large-file work to a subagent so it runs in a separate context window.
4. Run `/clear` if the earlier conversation is no longer needed.

## Hangs and freezes

If Claude Code seems unresponsive, press Ctrl+C to attempt to cancel the current operation. If it stays unresponsive, close the terminal and restart. Restarting does not lose your conversation: run `claude --resume` in the same directory to pick the session back up.

## Keep the context window small

Token costs and processing both scale with context size, so the most effective long-term fix is keeping context lean. Documented strategies:

- **Clear between tasks.** Use `/clear` to start fresh when switching to unrelated work; stale context wastes tokens on every subsequent message. Use `/rename` before clearing so you can find the session later, then `/resume` to return to it.
- **Compact with focus.** `/compact Focus on code samples and API usage` tells Claude what to preserve during summarization. You can also add compact instructions to your CLAUDE.md.
- **Trim CLAUDE.md.** It loads at session start and stays in context even for unrelated work. Aim to keep it under about 200 lines and move specialized, on-demand instructions into skills, which load only when invoked.
- **Reduce MCP overhead.** MCP tool definitions are deferred by default, but you can run `/mcp` to disable servers you are not using. Prefer CLI tools like `gh`, `aws`, and `gcloud` when available, since they add no per-tool listing to context.
- **Choose the right model.** Sonnet handles most coding tasks and costs less than Opus; use `/model` to switch mid-session. Lower thinking effort with `/effort` (or in `/model`) for simpler tasks.
- **Delegate verbose operations.** Send research, test runs, and log processing to subagents so the bulky output stays in their context window and only a summary returns.
- **Offload to hooks and skills.** A hook can grep a 10,000-line log for `ERROR` and return only matching lines; a skill can supply architecture context so Claude does not have to read many files to orient itself.

If you genuinely need a larger window rather than a smaller conversation, the documentation notes that certain newer models support a 1 million token context window; see Extended context for availability and how to select a `[1m]` model variant. Compaction works the same way at the larger limit.

## Search and terminal problems

Two stability issues are commonly mistaken for performance bugs:

- **Search missing files.** If the Search tool, `@file` mentions, custom agents, or custom skills are not finding files, the bundled `ripgrep` may not run on your system. Install your platform's `ripgrep` package (for example `brew install ripgrep`), then set `USE_BUILTIN_RIPGREP=0` in your environment. On WSL, cross-filesystem reads can also return fewer matches; use more specific searches or move the project to the Linux filesystem.
- **Garbled or corrupted text** in the VS Code, Cursor, or Devin Desktop integrated terminal usually means the terminal's GPU renderer is the cause. Run `/terminal-setup` to turn off GPU acceleration, then reload the window.

## Get more help

Run `/doctor` for a one-pass check of installation health, settings validity, MCP configuration, and context usage. Use `/feedback` to report problems to Anthropic, and check the Claude Code GitHub repository for known issues. Claude Code updates regularly and behavior can change, so run `claude --version` before filing a report.

---

> **Still stuck?**
>
> If `/safe-mode` shows the slowdown comes from a customization, work through Debug your configuration to isolate the plugin, MCP server, or hook. For a deep memory investigation, keep `/heapdump` output private because it can contain session data; share only redacted diagnostics through a private support channel if requested.