Claude Code hanging or frozen? How to diagnose and fix it

You send a message and Claude Code just sits there. No tokens, no tool output, a spinner that keeps spinning past the point where anything should still be happening. That is hanging, and it is different from slow. Slow is the model working through a large context and eventually answering. Hanging is the agent stuck waiting on something that never returns, so it never answers at all. The two look similar for the first few seconds and then part ways: slow makes progress, hanging does not.

Hanging is not the same as slow

Before you fix anything, tell the two apart, because the fixes are opposite. Slow means real work is in flight: a big conversation, a huge file, a long tool run. It ends on its own if you wait, and you make it faster by trimming context. Hanging means nothing is in flight: a tool call that will not come back, a frozen terminal, a stalled connection. Waiting does not help, because there is nothing to wait for. If a couple of minutes pass with zero output and no CPU moving, treat it as hung, not slow.

Why Claude Code hangs

Three causes, in rough order of how often they are the real one:

How to unfreeze it

1. Press Esc to interrupt. This cancels whatever the agent is waiting on and hands you back the prompt without killing the session. It is the first move, and often the only one you need.
2. Disable MCP servers you are not using. A misconfigured or unresponsive server is the most common thing to hang on. Turning off the ones this task does not need removes the hang and frees context at the same time.
3. On Windows, switch from PowerShell to Git Bash. PowerShell has known freezing with the CLI. Running Claude Code from Git Bash avoids it, and it is a one-time change.
4. Close unused IDE tabs and shorten the path. The VS Code extension pulls open tabs into context every message, so close what you are not editing. If your project sits deep under your home folder, move it to a shorter path to dodge the duplicate-memory bug.
5. Check status and retry. If none of the above frees it, the stall is likely network or server side. Look at the Anthropic status page, retry the request, and try again off-peak if it persists.

How to stop it hanging

The sessions that never freeze are not lucky, they are set up clean. Keep only the MCP servers you actually use connected, so there is less to hang on and less context to carry. Run Claude Code from a shell it likes (Git Bash on Windows), keep your project on a short path, and close editor tabs you are not working in. None of this is exotic. It is setup hygiene, and it is the difference between a spinner that resolves and one that does not.

That is the boring work kitstarter does for you. The kit ships `doctor.mjs`, a setup checker that flags a broken or misconfigured MCP server and a shaky environment before either one hangs you, and it keeps the MCP and context surface minimal by default so there is simply less to stall on. It will not fix a network blip, but it catches the local causes, the ones you would otherwise spend twenty minutes staring at a spinner to find. Worth reading next: why Claude Code gets slow and how to set it up cleanly.

Common questions

Why is Claude Code frozen? It is almost always waiting on something that will not answer: a hung tool call, an unresponsive MCP server, a frozen terminal, or a stalled network connection. It is not the model thinking. Press Esc to interrupt, then look at your MCP servers and your shell, which are the two most common culprits.

How do I unfreeze Claude Code? Press Esc first to cancel whatever it is stuck on and get the prompt back. If it hangs again, disable MCP servers you are not using, switch from PowerShell to Git Bash on Windows, close unused IDE tabs, and check the Anthropic status page before retrying.

Does PowerShell cause Claude Code to hang on Windows? It can. PowerShell has known freezing with the CLI on Windows. Running Claude Code from Git Bash avoids it. It is a one-time switch and it removes one of the most common Windows-only causes of a frozen session.

Is hanging the same as slow? No. Slow means the model is doing real work through a large context and will answer if you wait, so you fix it by trimming context. Hanging means nothing is in flight and waiting will not help. If a couple of minutes pass with zero output, treat it as hung, not slow.