August 6, 2026Johan Huynh7 min read

Claude Code stuck, hanging, or frozen? Diagnose and fix it

“Stuck” covers three different failures: a response that will not finish, an agent running away from the task, or the same bad fix repeating. Match the symptom first and the recovery is usually quick.

The kitstarter robot frozen mid-step beside a stalled loading spinner

If Claude Code stops responding, first decide whether the current operation is still making progress. A slow session keeps producing tokens, tool output, CPU activity, or visible task movement. A hung session produces none of those. A runaway session is active but doing the wrong work. A looping session keeps returning to the same failed approach. Those states need different interventions, so treating every one as “wait longer” is what turns a small interruption into a lost session.

Slow, hung, runaway, and looping are different

Slow means useful work is still moving. Hung means the response or tool call has stopped moving. Runaway means the agent is still active but has drifted into work you did not ask for. Looping means it keeps trying the same failed fix. Check output and task movement, not the spinner alone.

Choose the recovery by what “stuck” looks like

Use the smallest interruption that matches the failure. Claude Code keeps completed work when you interrupt a turn, so taking control early is safer than letting a bad direction consume more context.

No response or tool outputPress Esc to interrupt the current response or tool call. If the whole CLI ignores input, use Ctrl+C, restart it, then run claude --resume in the same directory.
Active, but going off taskPress Esc, state the exact outcome and boundary, then continue. If unwanted edits already landed, press Esc twice or use /rewind to return to a checkpoint.
Repeating the same broken fixStop the turn, preserve the useful evidence, and start a clean approach. Use /compact when the earlier context still matters or /clear when it does not.
One symptom word, three recovery paths. Interrupt first, then reduce only the context or work that caused the failure.

Why Claude Code hangs or freezes

The current Claude Code troubleshooting guidance points to three practical buckets:

A command or tool never returnsinterrupt the current operation. If the interface itself is unresponsive, restart it and resume the saved session. Run /doctor to check the installation, settings, MCP servers, and context usage.
High memory or context pressurelarge repositories, long tool output, and old conversation history can make the client feel frozen. Use /compact with a clear focus, move large-file work into a separate context, or /clear when the earlier conversation is no longer useful.
Configuration or service failurea bad MCP process, invalid setting, network interruption, or Anthropic error can stall the turn. /doctor separates local configuration problems from service errors before you start changing unrelated code.
The visible freeze is only the symptom. Recovery depends on whether the blocked layer is the operation, the session, or the environment.

How to unstick Claude Code right now

  1. Press Esc to interrupt. This stops the current response or tool call and keeps the work already completed in the turn. Redirect the task from the prompt instead of killing the whole session.
  2. Use Ctrl+C only when the interface is unresponsive. Anthropic's troubleshooting guide recommends cancelling the operation and restarting if needed. The conversation is saved continuously, so reopen it with claude --resume from the same directory.
  3. Run /doctor before changing the environment. It checks the installation, settings, MCP servers, and context usage. That is faster and safer than guessing that the shell, network, or every MCP server is broken.
  4. Reduce context only when context is the cause. Use /compact keep only the plan and the diff when the session still matters. Use /clear when it does not. Split large-file work into a separate session or subagent so one heavy operation cannot clog the main thread.
  5. Reproduce once, then isolate the failing layer. If the same tool or MCP server hangs twice, disable only that integration and retry. If unrelated operations fail too, check the service status and error message before changing the project.
The kitstarter robot calmly unplugging one tangled cable from a row of neat ones
Most hangs are one bad connection, not the whole setup. Pull that one and it moves again.

How to stop it hanging

Keep the main session small enough to reason about, isolate large-file or exploratory work, and run /doctor when the same environment failure repeats. Interrupt scope drift as soon as it starts. A clean recovery path matters more than a long list of speculative tweaks because it tells you which layer actually failed.

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 may be a command or tool call that never returned, high memory or context pressure, or a configuration or service failure. Press Esc to interrupt the current turn. If the entire CLI is unresponsive, use Ctrl+C, restart it, and resume the saved session.

How do I unfreeze Claude Code? Press Esc first to stop the current response or tool call. If the interface ignores input, use Ctrl+C and restart, then run claude --resume from the same directory. Run /doctor if the problem repeats so you can isolate settings, MCP, context, or installation problems.

What do I do when Claude Code keeps trying the same broken fix? Interrupt the turn, keep the useful error evidence, and change the approach explicitly. Compact the session if earlier context still matters or clear it if the old reasoning is now noise. Repeating the same prompt in the same bloated context usually repeats the failure.

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.

Why does Claude Code hang on startup? Run claude doctor from the shell when the interactive client will not start. It checks the installation and configuration without requiring a working session. Use the reported failure instead of changing shells or project settings at random.

Claude Code is freezing and not responding, what do I do? Press Esc to interrupt the response or tool call. If the whole interface is unresponsive, use Ctrl+C, restart, and resume the session. If it is active but off task, interrupt and restate the exact outcome. If it is looping, compact or clear the context before trying a different approach.

Catch the hang before it happens

kitstarter ships a setup checker that flags a broken MCP or a shaky environment, and keeps your setup minimal by default, for Claude Code, Codex, and Antigravity.

Get the kit · $25 $50Read the docs