Claude Code Running Slow or Freezing: Performance, Stability, and /doctor Diagnostics

Claude Code is installed and you are logged in, but as you use it, it gets slow, freezes, shows garbled text, or search stops finding files. This article covers those once-it-is-running performance and stability problems, based on the official Claude Code docs. If installation, login, or connection itself fails, start with the install, auth, and connection guide instead.

Which page matches your symptom

Where to look depends on the type of problem. If you are not sure, run /doctor inside Claude Code — it checks your installation, settings, MCP servers, and context usage in one pass. If claude will not start at all, run claude doctor from your shell.

When it is slow or using too much memory

Claude Code may consume significant resources on large codebases. Try these 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.
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, one of them is the cause.

If memory stays high, run /heapdump. It writes a heap snapshot and a memory breakdown to ~/Desktop (or your home directory on Linux without a Desktop folder), which you can attach when reporting a memory issue on GitHub.

The "Autocompact is thrashing" error

The Autocompact is thrashing... message means automatic compaction succeeded, but a file or tool output immediately refilled the context window several times in a row. Claude Code stops retrying so it does not waste API calls on a loop that is not making progress. To recover:

• Ask Claude to read large files in smaller chunks — a specific line range or function — instead of the whole file.
• Run /compact with a focus that drops the large output (for example, "keep only the plan and the diff").
• Move large-file work to a subagent that runs in a separate context window.
• Run /clear if the earlier conversation is no longer needed.

When a command hangs or freezes

If Claude Code is unresponsive, first press Ctrl+C to try to cancel the current operation. If it is still stuck, you may need to close the terminal and restart. Restarting does not lose your conversation — run claude --resume in the same directory to pick the session back up.

Garbled text in an editor terminal

If characters render as boxes, smears, or wrong glyphs in the VS Code, Cursor, or Devin Desktop integrated terminal, the terminal GPU renderer is likely the cause. Run /terminal-setup inside Claude Code to set terminal.integrated.gpuAcceleration to "off" (or set it manually in your editor settings and reload the window).

When search cannot find files

If the Search tool, @file mentions, or custom agents and skills are not finding files, the bundled ripgrep binary may not run on your system. Install your platform ripgrep and tell Claude Code to use it.

brew install ripgrep        # macOS
sudo apt install ripgrep    # Ubuntu/Debian
winget install BurntSushi.ripgrep.MSVC   # Windows

Then set USE_BUILTIN_RIPGREP=0 in your environment.

Slow or incomplete search on WSL

Crossing file systems on WSL incurs disk-read penalties, so you may get fewer matches than expected (search still works, but returns fewer results). In this case /doctor shows Search as OK. Fixes: (1) submit more specific searches by directory or file type, (2) move the project to the Linux filesystem (/home/) rather than the Windows path (/mnt/c/), or (3) run Claude Code natively on Windows instead of WSL.

Recovery commands

If none of this helps

If the above does not resolve it: (1) run /doctor to check install health, settings, MCP, and context in one pass, (2) use the /feedback command inside Claude Code to report the problem directly to Anthropic, and (3) check the GitHub repository for known issues. You can also ask Claude directly about its features.

Wrap-up

In short, for once-running problems, work in this order: /doctor to diagnose → /compact to trim context → --safe-mode to isolate the cause, and most issues get narrowed down. If you are stuck at install or login, see the install, auth, and connection guide. This is based on the official Claude Code docs (Troubleshooting).

New here?: How to Read Error Messages (beginner)