You've handed Claude Code a non-trivial refactoring task. It's been chugging along, modifying files, running tests—and then it stops. The "try stopping" button appears. Or the terminal just hangs. Or the response simply never comes.
The most common mistake developers make in this situation is immediately re-running the same task. Depending on how far Claude Code got before stopping, doing this can mean double-applying changes, stacking new edits on top of partially completed ones, or triggering the same tool failure that caused the hang in the first place.
There's a right order of operations here. This guide walks through it.
Why Claude Code Stops Mid-Task
Understanding the cause shapes how you recover. There are four main scenarios.
Context window exhaustion: As conversation history and code changes accumulate, the available token space fills up. You'll often see "continuing..." before a sudden stop, or the response will simply cut off. This is the most common cause during long, large-scope tasks. The more files Claude Code reads and modifies in a single session, the faster it burns through context.
Rate limiting: If you're on the API tier or working intensively on a Max plan, you may hit request limits. An error mentioning "429" or "overloaded" points here. Usually recoverable by waiting a few minutes before retrying. If you're hitting this repeatedly, spacing out heavy tasks or using smaller, more focused requests helps.
Tool execution failure: A Bash command timed out, returned a permission error, or fell into an infinite loop. Claude Code waits for tool output that never arrives and hangs. The terminal often shows a running command with no visible result. Long-running test suites and commands that prompt for user input are frequent culprits.
Network disconnection: Waking from sleep, a VPN reconnect, or a brief outage can sever the connection mid-response. A full Claude Code restart typically resolves this. If you're on a flaky connection, shorter task scopes reduce the chance of a disconnect happening in the middle of something important.
The recovery steps below apply regardless of cause—but knowing which scenario you're in helps you decide whether to wait, restart, or roll back.
Step 1: Run git status Before Anything Else
When Claude Code stops, do not restart it, re-run the task, or close the terminal until you've checked the state of your working directory.
# See which files were touched
git status
# Example output when changes were partially applied:
# On branch feature/refactor-auth
# Changes not staged for commit:
# modified: src/auth/login.ts
# modified: src/auth/session.ts
#
# Untracked files:
# src/auth/types.tsThis tells you exactly where Claude Code left off. Files listed under "Changes not staged" have been written to disk. If you see nothing to commit, either Claude Code hadn't started the actual modifications yet, or it cleaned up after itself—safe to retry from scratch.
The reason not to restart Claude Code first is that doing so clears the conversation history. You lose the context of what you originally asked for, which makes writing an accurate "resume from here" prompt harder.
A common variant of this situation: Claude Code finishes the file changes but stops while trying to run tests or linting. In that case, git status shows the complete changes—which is good news. The stop happened after the work was done, not during it.
Step 2: Inspect Changes with git diff
Once you know which files were modified, check what was actually changed.
# See all unstaged changes
git diff
# Narrow it down to a specific file
git diff src/auth/login.ts
# Get a summary of how many lines changed per file (useful for large tasks)
git diff --statScan the diff output and ask yourself:
- Do the changes look complete and coherent, or do they trail off mid-function?
- Are there any unclosed braces, missing return statements, or obvious syntax issues?
- Does the logic in the
+lines make sense given what you originally asked for? - Are there any temporary debugging statements or half-written code that Claude Code was in the middle of?
If you can, run a quick sanity check to catch broken syntax before deciding how to proceed:
# TypeScript: check for type errors without emitting output
npx tsc --noEmit
# Python: check for syntax errors
python -m py_compile src/auth/login.py
# Go: quick compile check
go build ./...
# Node.js: check if the entry point parses correctly
node --check src/index.jsNo errors here means the changes Claude Code completed before stopping are at least syntactically valid—you can build on them confidently.
If you do find broken syntax or logic that doesn't make sense, that's a strong signal the task was interrupted mid-edit rather than post-completion. In that case, Pattern A below is the right call.
Step 3: Pick the Right Recovery Pattern
With a clear picture of what was done, choose one of three paths forward.
Pattern A: Changes are incomplete or broken
Roll back to a clean state first.
# Discard all unstaged changes to tracked files
git checkout .
# Also remove newly created (untracked) files if needed
git clean -fd
# Verify you're back to a clean state
git status
# Should show: nothing to commit, working tree cleanOnce you're back to a clean baseline, restart Claude Code and re-submit the task. This time, break it into smaller pieces as described in Step 5.
Pattern B: Changes are complete, but Claude Code stopped before finishing subsequent steps
Maybe the file modifications are done but Claude Code stopped while trying to run tests, generate documentation, or produce a summary. Keep the changes and give Claude Code specific context when you resume.
# Commit the completed work as a clear checkpoint
git add -A
git commit -m "WIP: auth refactor – login.ts and types.ts done, session.ts remaining"Then restart Claude Code and be explicit: "The changes to login.ts and types.ts are committed as WIP. Please continue from session.ts and apply the same pattern." Giving Claude Code a concrete reference to what's done removes ambiguity about where to pick up.
Pattern C: The task is fully done, Claude Code just didn't respond with confirmation
This happens when the last step was something low-stakes—generating a summary, outputting a review comment, or printing a status update—and the response timed out or was cut off. The actual code changes are complete and valid.
# Verify everything looks correct
git diff --stat
# Run your test suite to confirm
npm test # or pytest, go test ./... etc.
# If it passes, commit normally
git add -A
git commit -m "feat: refactor auth module to TypeScript strict mode"No recovery needed here. The stop was cosmetic, not substantive.
Step 4: Use /compact to Prevent Context Exhaustion
If context window limits are the recurring cause of your stops, /compact is the tool to reach for.
# Type this in the Claude Code chat interface
/compact
/compact summarizes and compresses the current conversation history, freeing up token space without fully resetting the session. The task context is preserved in the summary—so calling it mid-task won't leave Claude Code confused about what it was doing. Think of it as creating a "compressed checkpoint" that retains the essential context while shedding the verbose conversation history.
A practical rule: once a conversation hits 30–40 back-and-forth exchanges, run /compact before starting the next major subtask. This is especially important for sessions that involve reading many files, because each cat or file read adds to the accumulated context.
You can also reduce context consumption by adjusting how you prompt:
# High context consumption (avoid for long tasks)
"Please explain each change you make as you go, step by step."
# Low context consumption (better for long tasks)
"Make the changes directly. Commit when each file is done. No explanations needed."
The second style can meaningfully extend how long a session runs before hitting limits. For a deeper look at token management strategies, see How to Cut Claude Code Token Usage in Half.
Step 5: Build a Checkpoint Habit for Long Tasks
The most reliable way to handle mid-task stops is to design tasks so that interruptions don't matter much.
The problem with large, all-in-one requests:
"Update all components in src/ to TypeScript strict mode,
write unit tests for each, update the CI config, and revise the README."
If Claude Code stops two-thirds of the way through this, figuring out the current state and what remains is genuinely hard. You're left reading through dozens of files trying to reconstruct progress.
A checkpoint-based approach that scales better:
Checkpoint 1:
"Update src/components/ to strict mode. Commit when done, then stop."
→ Review the commit. Looks good.
Checkpoint 2:
"Now update src/pages/. Same approach—commit when done, then stop."
→ Review. Adjust if needed.
Checkpoint 3:
"Write unit tests for the components updated in the previous two checkpoints."
Each checkpoint produces a git commit. If Claude Code stops, git log tells you exactly what's been completed. If a particular commit looks wrong, git revert handles it cleanly without touching later work.
A useful mental model: treat each Claude Code task like a database transaction. It should either complete fully (and get committed) or roll back to a known state. The "WIP" commit pattern from Pattern B gives you that transaction boundary explicitly.
For scope, I've found one commit per 10–20 files changed to be a practical ceiling. Beyond that, the cognitive overhead of verifying a stop-and-recovery grows disproportionately.
If you're hitting Bash tool timeouts specifically—where Claude Code stops because a command runs too long—the guide on Claude Code Bash Tool Execution Errors covers those cases in more detail.
Diagnosing Quickly: A Decision Tree
When you're in the middle of a stopped session and need to decide fast, here's the short version:
Claude Code stopped → Run: git status
Nothing changed?
→ Restart Claude Code, retry the task (safe)
Changes present → Run: git diff + compile check
Changes look complete and compile?
→ Commit as WIP, then resume from the next step
Changes are broken or half-done?
→ git checkout . && git clean -fd, then retry with smaller scope
Session stopped mid-tool (running indicator visible)?
→ Wait 30-60 seconds first. If still stuck: Ctrl+C, then assess.
The Core Takeaway
When Claude Code stops mid-task, the single most valuable habit is to check git status and git diff before doing anything else. Knowing what was completed—and whether it's in a valid state—determines whether you roll back, resume from a specific point, or simply commit and continue.
Treat mid-task stops as natural checkpoints rather than failures. With a checkpoint-based workflow and /compact as a regular tool, Claude Code becomes significantly more resilient for long, complex tasks. The developers who get the most out of Claude Code aren't the ones who avoid interruptions—they're the ones who've built a workflow that recovers from them gracefully.