Claude Code printed steps 1, 2, and 3 of a 5-step task. Then nothing. No error. No “I’m done.” Just a blinking cursor. You wait 60 seconds, then a minute more. Still nothing. The work isn’t finished, the agent isn’t reporting why it stopped, and re-prompting gets it to step 4 — then stuck again at step 5.
A stuck-after-partial state has three distinct flavors with different fixes: out-of-context (agent silently truncated), tool hang (a Bash or Test call never returned), or silent abort (agent thinks it’s done despite incomplete work). Don’t fight the stuck session — diagnose which flavor, save state, restart from a fresh status doc.
Common causes
Ordered by hit rate, highest first.
1. Context window near full; agent silently summarized and lost its plan
The agent’s plan was in its context. As context filled, auto-summarization dropped the plan. The agent finished what it remembered and emitted nothing because, in its compressed view, the task is done.
How to spot it: Session was long with many tool calls before stalling. After restart with full context, the same prompt finishes — meaning context, not the task, was the limit.
2. A tool call hung, agent waits for a phantom callback
pnpm test started but never returned (infinite loop in test setup, hanging dev server). Claude’s tool layer blocks waiting; no output reaches you.
How to spot it: Check running processes: ps aux | grep -E "node|python|pnpm". If one is alive but doing nothing (no CPU, no output), kill it and the agent will likely resume.
3. Streaming connection dropped silently
WiFi blip, VPN reconnect, or laptop sleep cut the streaming response from the server. Claude is still running on the backend but you’re not seeing output.
How to spot it: Network conditions weren’t great. Try /resume if available, or restart the session — usually the work continues from server-side state.
4. Agent’s plan completed but work isn’t done
The agent had a 3-step plan internally; you needed 5. After step 3 it considered itself done and stopped emitting. Plan and reality diverged.
How to spot it: Ask “did you complete the task? List remaining steps.” If the agent says “yes” but you can see incomplete work, its plan was smaller than yours.
5. Output got truncated and the trailing “done” message got cut
A stream limit clipped Claude’s final summary. Code was applied, but you didn’t see the wrap-up. The agent did finish; you just don’t know it.
How to spot it: git status and git diff reveal that the work is done — the stuck appearance was a presentation issue.
6. Long reasoning vs hang — distinguish before restarting
Some thinking steps take 30+ seconds without output. Restarting prematurely wastes the work-in-progress.
How to spot it: Wait 60 seconds with no output before judging stuck. If your client shows a “thinking” indicator, the model is still working.
Shortest path to fix
Ordered by ROI. Step 1 diagnoses the flavor; the right fix follows from that.
Step 1: Wait 60 seconds, then diagnose
1. Wait 60s with no output (in case it's a long reasoning step).
2. Run `git status` and `git diff` — is work *actually* incomplete?
3. Check running processes: `ps aux | grep -E "node|python|pnpm|vitest"` — any hanging?
4. Look at `top` / Activity Monitor — is anything using CPU?If the diff shows incomplete work AND processes are idle AND it’s been 60+ seconds, the session is genuinely stuck.
Step 2: Capture state before restarting
# Quick checkpoint commit
git add -A && git commit -m "wip: stuck during step N"
# Write what was supposed to happen next
cat > STATUS.md <<EOF
Task: <one-sentence>
Done: steps 1-3 (files A, B, C edited)
Remaining: steps 4-5 (need to edit D, E)
Last action visible: <what Claude was doing>
EOFThis is your resume point — restarting blind costs more than the 2 minutes to write this.
Step 3: Kill hung processes if any
# Find the hung tool process
ps aux | grep -E "node|python|pnpm|vitest" | grep -v grep
# Kill orphans (replace PID)
kill -9 <PID>
# Aggressive cleanup if needed
pkill -9 -f vitest
pkill -9 -f "pnpm test"If killing a hung tool unsticks the session, you found the cause — note which tool to avoid combining in future sessions.
Step 4: Restart with STATUS.md as the handoff
Open a new session:
Read STATUS.md. Pick up the task.
Verify against `git log` what's already committed.
Do not redo completed work. Start from "remaining."Fresh context for the snapshot — no fading-memory risks.
Step 5: If consistently stuck at the same step, split that step
A step that consistently stalls is likely too large or has a problematic sub-task. Split it:
Original step 5: "Update all consumers and run integration tests"
Split into:
5a: Update consumer in src/api/users.ts. Stop.
5b: Update consumer in src/api/orgs.ts. Stop.
5c: Run `pnpm test src/api/users.test.ts`. Stop.
5d: Run `pnpm test src/api/orgs.test.ts`. Stop.Each sub-step is small enough to fit without hitting whatever the failure mode is.
Step 6: For tool hangs, run the troublesome tool manually first
If pnpm test keeps hanging when Claude runs it, run it yourself in a separate terminal first. Once it’s started + completed cleanly, tell Claude to skip running it and just use the result.
I just ran `pnpm test` and it produced the output below.
Use this output; do NOT run the test command yourself.
[paste]Workaround for unreliable tools without abandoning the agent.
Prevention
- After every major step, ask Claude to write a STATUS file — survives all three flavors of stuck
- Cap tasks at under 1 hour of expected agent time; smaller checkpoints survive better
- Run on stable network; mobile hotspot is the silent killer for streaming connections
- Don’t combine multiple long-running tools in one session — split test runs from edits
- Know your tools’ typical durations so you can tell hang from slow
- For consistently-hanging tools, run them manually and feed results to Claude
Related
- Claude Code stuck in a loop
- Claude Code stops mid-task due to usage limits
- Claude Code lost project context mid-task
- Claude Code beginner guide
- Claude Code workflow
- Claude Code project setup
Tags: #Troubleshooting #Claude Code #Debug #Partial execution