Claude Code Stops Mid-Execution: Complete Diagnostic Guide

You've handed Claude Code a complex task. It's been running for a few minutes, and then — nothing. The cursor blinks. No output. No error. Just silence.

Do you wait it out? Hit Ctrl+C and risk losing progress? Start over from scratch?

This is one of the most disorienting experiences when working with Claude Code, and the advice you'll find online ("check your network connection") rarely helps. The causes are specific to how Claude Code manages execution state, and once you know what to look for, diagnosis becomes fast.

Step One: Classify the Freeze by Timing

The most reliable first signal is when the freeze happens, not just that it happened. Interrupting with Ctrl+C and reading the last few lines of output will usually tell you which category you're dealing with.

Freezes that happen quickly (within seconds to one minute):

• Claude called a tool and got no response → tool execution error, MCP server issue, or permission block
• Froze immediately after you typed a command → Hooks configuration error, authentication issue
• Edit tool usage seems to hang → file lock or filesystem permissions

Freezes that develop over several minutes:

• Happened as the context meter was getting low → context budget exhaustion
• Happened right after delegating to a subagent → subagent unresponsive or errored
• Looks like the same operations are repeating → infinite loop

Once you've observed the timing, the next step is to check the session log before doing anything else:

# View recent Claude Code session logs
cat ~/.claude/logs/claude-code.log | tail -100

Claude Code almost always records what happened. Reading those logs before force-resetting saves significant diagnostic time.

Cause #1: Context Budget Exhaustion (Most Common)

In my experience, this accounts for well over half of all mid-task freezes. Every Claude Code session has a finite context window. When that window fills up, Claude Code either auto-compacts (if enabled) or stops to wait for user direction. From the outside, it looks like a freeze.

How to Confirm It

The clearest signal is a message like this appearing in the session output:

Context window is 95% full. Consider starting a new conversation
or using /compact to summarize the conversation.

You may also see the token counter in the status bar turn red. If Auto Compaction is enabled, Claude Code may pause for 10–30 seconds while it summarizes the conversation — this is normal behavior and worth waiting out before interrupting.

Immediate Fix: /compact

The fastest recovery is running /compact inside the session:

# Run inside a Claude Code session
/compact

This compresses the conversation history while preserving the current working context. The session continues from where it left off, but fine-grained details from earlier exchanges may be lost. For important decisions or architectural choices made earlier in the session, consider asking Claude to write them into CLAUDE.md before compacting.

Structural Fix: Break Tasks Into Stages

The real solution is upstream — design tasks so that context doesn't fill up in the first place. Instead of:

Migrate the entire codebase from JavaScript to TypeScript.

Try:

Step 1: Migrate src/lib/ to TypeScript. Stop after this directory.
  → Review and commit
Step 2: Migrate src/components/. Stop after this directory.
  → Review and commit
Step 3: Migrate src/app/. Stop after this directory.

Each step gets a fresh context reset. The result is the same, but you stay in control throughout.

For deeper techniques, see Claude Code Context Budget Optimization Guide and Claude Code Auto Compaction Troubleshooting.

Cause #2: Tool or Subagent Unresponsiveness

This is the "waiting, not frozen" scenario. Claude Code has called a tool — Bash, Edit, Read, an MCP tool, or a Task subagent — and is waiting for a response that isn't coming. Nothing will happen until that response arrives or the session is interrupted.

Bash Tool Hangs

Long-running commands are a common source. The classic examples: npm install on a slow connection, find / with no scope limits, database migrations, or network calls to unresponsive endpoints.

# Problem: unbounded search can run for minutes
find / -name "*.log" -size +100M
 
# Better: constrained scope and age filter
find /var/log /tmp -name "*.log" -size +100M -mtime -7

Before passing any shell command to Claude Code, test it in your terminal first to get a sense of how long it runs. For anything that might take more than a few seconds, add a timeout wrapper:

# Hard limit: fail after 30 seconds rather than blocking indefinitely
timeout 30 npm run build || echo "Build timed out — investigate manually"

MCP Server Unresponsiveness

If you're using MCP tools, an unresponsive MCP server will cause Claude Code to wait indefinitely. Use /mcp to check server status:

# Inside a Claude Code session — lists all configured MCP servers and their status
/mcp

Look for any servers showing disconnected or error. For those, restart the server process and verify the configuration in your settings.json or ~/.claude/claude_desktop_config.json.

Full MCP connection diagnostic steps are in Claude Code MCP Connection Troubleshooting.

Subagent Not Returning

When Claude Code delegates work via the Task tool, it waits until the subagent returns. If the subagent encounters a problem, the parent session waits indefinitely.

There are three main failure patterns for subagents:

Pattern A: The subagent has also run out of context

Subagents run in isolated sessions with their own context budget. If you give a subagent too much work, it will exhaust its own context and stop. Keep subagent assignments focused and include explicit completion criteria:

# Weak: too broad, no completion signal
Task: Write tests for the project.

# Better: scoped, with a clear done condition
Task: Write unit tests for src/utils/formatter.ts using vitest.
Include 2 normal cases and 1 error case.
After writing, run the tests and confirm all pass. Then stop.

Pattern B: The subagent hit a permission-required action

Subagents will pause when they encounter an action requiring user confirmation, such as file deletion or certain shell commands. Review allowedTools in your settings or consider running the session with --auto mode.

Pattern C: The subagent spawned additional subagents

Subagents can, by default, spin up their own subagents. This creates chains that are hard to monitor and can cascade into deadlocks. Explicitly tell subagents not to create further agents: "Do not use the Task tool."

For detailed subagent diagnostics, see Claude Code Subagent Not Returning: Troubleshooting Guide.

Cause #3: Infinite Loops and Task Abandonment

This is the "technically running, not making progress" scenario. Claude Code is active — consuming context, calling tools — but the task isn't advancing. Left unchecked, this burns through your context budget and eventually triggers Cause #1.

Signs of a Loop

Watch for these patterns in the session output:

• The same file is being Read → Edit → Read → Edit repeatedly
• The same error appears again and again with no change in approach
• The Todo list keeps growing but nothing gets marked done
• The Bash execution history shows the same command multiple times

When you see this, the fastest intervention is to ask Claude Code to account for its current state:

(Type in the session)
What have you completed so far, and what are you currently trying to do?
Please give me a short summary before continuing.

This simple prompt forces a self-assessment that usually breaks the loop. Claude Code, when asked to reflect, often identifies the problem itself and adjusts. If it doesn't, interrupt with Ctrl+C, reset the context, and rephrase the original request with tighter constraints.

The "Waiting for User" Stall

Sometimes Claude Code encounters an ambiguous situation and quietly stops, waiting for direction without saying so. The screen shows nothing but a blinking cursor. This is especially common when Claude Code encounters a decision point it wasn't told how to handle.

The prevention is in your upfront instructions. Adding something like this to CLAUDE.md gives Claude Code a clear protocol for uncertain situations:

## Working Protocol
- If you encounter an error, attempt to resolve it up to 3 times before reporting.
- If you're unsure how to proceed, make the decision you think is best and note it.
- Don't ask for confirmation mid-task unless something is irreversible or destructive.

With clear fallback behavior defined, Claude Code will make a judgment call rather than stalling. For more on task abandonment and prompt design patterns, see Claude Code Task Abandonment and Verification Loops.

Quick Reference: Freeze Diagnosis Checklist

When Claude Code stops responding, run through this in order:

1. Note the timing — How long was it running before it stopped?
2. Press Ctrl+C — Interrupt safely and read the last output carefully
3. Check the log — cat ~/.claude/logs/claude-code.log | tail -50
4. Look for context warning — Is the token meter red? Any "context window full" messages?
5. Check MCP servers — Run /mcp inside the session
6. Look for repetition — Is Claude Code repeating the same operations?

In most cases, you'll have a clear culprit by step 4. Context exhaustion is far and away the most common cause, so starting there isn't a bad heuristic even without the other signals.

The pattern I've found most useful is: observe before interrupting. When something stops, resist the impulse to immediately kill the session. Give it 30 seconds, read the output, and then decide. That brief pause usually makes the diagnosis obvious — and saves you from restarting a session that was actually fine and just needed a moment.