Claude Code Stuck? Fix Every Frozen State (Responding, Tool Calls, Startup)

Claude Code stuck, spinning, or sitting there with no output? Almost every case is one of five distinct states, and they have different fixes. Work out which state you are in, then jump to that section.

Quick Fixes: Try These First

If Claude Code is stuck right now, work down this list. Most sessions recover at step 1 or 2.

Two keys are worth committing to memory. Esc is bound to cancelling the current chat turn, so it is the gentlest way out of a stuck response. Ctrl+C (interrupt) and Ctrl+D (exit) are hardcoded and cannot be rebound, so they still work when a broken custom keybinding file is the reason everything else is unresponsive.

Nothing here loses your work. Sessions persist to disk, so after any restart claude --continue picks up the most recent conversation in that directory and claude --resume opens a picker of earlier ones.

Stuck on "Running in the Background"

What it looks like: the response stops, and instead of an answer you see that the task is running in the background. The prompt comes back but the work seems to have vanished.

Why it happens: this is not a freeze at all. Ctrl+B is bound to task:background in Claude Code, which sends the foreground task to the background — every blocking tool call returns immediately and reports that it is running in the background. You keep chatting while the work continues elsewhere.

The trap is tmux. tmux's default prefix key is also Ctrl+B, so the two collide constantly. Claude Code detects when it is running under tmux and tells you to press Ctrl+B twice instead, precisely because the first press is swallowed by tmux. If you are a tmux user who has never deliberately backgrounded anything, this is almost certainly what happened.

The fix:

/tasks

/tasks (alias /bashes) views and manages everything running in the background. From there you can see what is still executing, bring it back, or kill it. If a task finished while backgrounded, its output is waiting for you there.

How to avoid it: if you use tmux, remap its prefix to something that does not collide — Ctrl+A is the common choice — by adding this to ~/.tmux.conf:

unbind C-b
set -g prefix C-a
bind C-a send-prefix

Stuck Mid-Tool-Call

What it looks like: Claude starts a Bash command, a test run, or a build, and the spinner never stops. No error, no output, no completion.

Why it happens: the overwhelming majority of these are a shell command waiting for input that will never arrive. The command is not slow — it is blocked:

• A pager. git log, git diff, and systemctl status pipe into less and wait forever for a keypress.
• An interactive confirmation. apt install, npm init, and anything that asks "Proceed? [y/N]".
• A long-lived process. npm run dev, docker compose up, or tail -f never exit by design.
• A credential prompt. sudo, ssh, or a git push asking for a passphrase on a terminal Claude cannot type into.

The fix: press Esc to cancel, then re-run the command in a form that cannot block:

git --no-pager log --oneline -20    # never opens a pager
git -c core.pager=cat diff          # same, per-invocation
npm install --yes                   # no confirmation prompt
apt-get install -y package          # no confirmation prompt
command | cat                       # forces non-paged output

How to avoid it: set the pager off for your whole environment with git config --global core.pager cat, and start dev servers and watchers as background tasks rather than foreground ones so they never hold the session. If you have a hook that runs a command, make sure it cannot prompt — a blocking hook blocks the session.

Stuck at Startup

What it looks like: you type claude, and the prompt never appears. It may hang on a splash screen, on loading, or on connecting to something.

Why it happens: startup hangs come from customizations loading, not from Claude Code's core. The usual suspects, in order of likelihood:

• An MCP server that never becomes ready — a broken command path, a server waiting on an expired OAuth token, or a remote endpoint that does not answer.
• A SessionStart hook that blocks. Hooks run synchronously; one that prompts or waits stalls startup indefinitely.
• A plugin or custom agent with a malformed definition.
• A very large CLAUDE.md tree being discovered and read.

The fix: bisect it with the two flags built for exactly this.

claude --safe-mode

--safe-mode starts with all customizations disabled — CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles, custom themes, and keybindings. Auth, model selection, built-in tools, and permissions still work normally. If Claude Code starts cleanly this way, the problem is in your configuration and not in the CLI.

claude --bare

--bare goes further: it skips hooks, LSP, plugin sync, auto-memory, background prefetches, keychain reads, and CLAUDE.md auto-discovery entirely.

Once you know it is a customization, narrow it down:

claude --strict-mcp-config     # ignore all configured MCP servers
claude --setting-sources user  # load only user settings, skip project and local
claude --debug                 # verbose startup logging
claude doctor                  # health check that reads settings without a trust prompt

claude doctor checks the health of your installation from outside a session. Inside a session, /doctor runs a fuller checkup that can also fix issues it finds.

How to avoid it: keep hooks fast and non-interactive, and remove MCP servers you no longer use rather than leaving them configured and failing.

Frozen Terminal / No Output at All

What it looks like: the whole terminal is unresponsive. Keystrokes do not echo. Esc and Ctrl+C produce nothing. This is different from Claude being stuck — the terminal itself has stopped drawing.

Why it happens: the common causes are terminal-level, not Claude-level:

• Flow control. An accidental Ctrl+S freezes terminal output on most Unix terminals. Ctrl+Q resumes it. This one catches people constantly and looks exactly like a crash.
• A tool dumped an enormous amount of output and the emulator is still rendering it.
• The terminal's scrollback buffer is exhausted.
• macOS App Nap or sleep suspended the process while the machine was idle.

The fix: try Ctrl+Q first — if flow control was the cause, everything unfreezes instantly and no work is lost. If that fails, force quit from a second terminal:

# macOS / Linux
pkill -f claude
pkill -9 -f claude    # if it survives

# Windows PowerShell
Stop-Process -Name "claude" -Force

Then reopen a terminal, return to your project, and run claude --continue to resume the conversation.

How to avoid it: avoid commands that dump megabytes into the terminal — redirect them to a file and have Claude read the file instead. Keep the machine awake during long operations. If your terminal emulator handles heavy output badly, a modern one (iTerm2, WezTerm, Ghostty, Windows Terminal) will cope better than the stock app.

Stuck After a Long-Running Command

What it looks like: Claude kicked off a build, a test suite, or a migration. Minutes pass with no output. You cannot tell whether it is working or dead.

Why it happens: a silent command is indistinguishable from a hung one. Many build tools detect that they are not writing to an interactive terminal and suppress their progress spinners entirely, so a job that shows a lively progress bar in your own shell shows nothing at all here.

The fix: diagnose before you kill anything.

/tasks       # is something still running?
/status      # is the API connection healthy?

If /tasks shows the command still executing, it is working — wait. If /status reports an API connectivity failure, the problem is your network, a proxy, or a VPN, not the command. Only if both look wrong should you interrupt with Esc.

How to avoid it: make long commands verbose, and give them somewhere to write.

npm test -- --reporter=dot          # steady output instead of silence
pytest -v                            # per-test progress
npm run build > /tmp/build.log 2>&1  # then read the log

For anything genuinely long, start it as a background task deliberately and check /tasks, rather than letting it hold the foreground.

Slow Is Not Stuck

If Claude still responds but each turn takes longer and longer, that is context pressure, not a freeze. Every file read, tool result, and build log adds to the context window.

/context     # visualize current context usage as a colored grid
/compact     # free up context by summarizing the conversation so far
/clear       # start a new session with empty context (old one stays resumable)

/compact accepts an instruction, which is worth using so the summary keeps what matters:

/compact keep file paths, decisions, and current task progress

You can also set the auto-compact window at launch with claude --autocompact auto or an explicit token budget. Switching to a faster model with /model for routine work helps too — reserve the heaviest model for genuinely hard reasoning.

A long pause that ends in an error rather than an answer is a third thing again. API Error: 529 overloaded_error means Anthropic's capacity for that model is saturated — nothing local will fix it, and switching models with /model is usually faster than waiting.

Keeping large files out of context in the first place is the durable fix. Deny-list them in ~/.claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(**/*.log)",
      "Read(**/*.sql)",
      "Read(**/node_modules/**)",
      "Read(**/dist/**)",
      "Read(**/*.min.js)",
      "Read(**/vendor/**)"
    ]
  }
}

Recovering Your Session

Nothing above costs you your conversation. Sessions are written to disk as you go.

claude --continue          # resume the most recent conversation in this directory
claude --resume            # interactive picker of previous sessions
claude --resume <id>       # resume a specific session by ID
claude --continue --fork-session   # resume under a new session ID

Inside a session, /resume does the same job, and /rewind (aliases /checkpoint and /undo) steps back to an earlier checkpoint if the thing that got you stuck also left a mess behind. Pressing Esc twice moves back up through previous messages so you can edit one and try again — useful when a specific prompt reliably triggers the hang.

Reporting a Genuine Bug

If a freeze reproduces on a clean --safe-mode session, it is worth reporting.

claude --version                    # version
claude doctor                       # installation health
claude --debug                      # reproduce with verbose logging
claude --debug-file /tmp/cc.log     # write debug output to a specific path

Debug logs are written per session to ~/.claude/debug/<session-id>.txt, and ~/.claude/debug/latest symlinks to the most recent one. Include the last few hundred lines, your Claude Code version, your OS and terminal emulator, whether you are in tmux or WSL, and the steps that reproduce it. File at the Claude Code GitHub repository, and redact anything sensitive from paths and code excerpts first.

Summary

Most of what reads as "Claude Code stuck" is a backgrounded task, a blocked shell command, or a customization that will not load. All three are recoverable in seconds once you know which one you are looking at, and none of them cost you the session.

Having persistent issues? Inventive HQ provides consulting on AI-assisted development tools and workflows. Contact us for help optimizing your Claude Code setup.