Claude Code Task Stuck? Common Causes and How to Recover

A Claude Code task that looks stuck is almost always waiting for something specific. In order of how often it happens: a permission prompt you have not answered, a shell command that will never finish on its own, a background job Claude is waiting on, a context window that has filled up, an MCP server that is not answering, or a rate or usage limit. Each one leaves a different sign on screen, and each has a documented command that confirms it: /tasks, /context, /mcp, /usage, /status and /doctor. Find the cause, clear it, and then write the blocker on the card so the next session does not walk into it again.

This post is about getting a stalled session moving. If you have already decided to stop the work, how to stop a Claude Code task midway covers Esc, /rewind and the handover note.

A two-minute triage

Before you press anything, read the bottom of the screen. What it says narrows the cause to one or two of the six below.

• A question or an approval box: it is waiting on you. See cause 1.
• A spinner on a Bash call that has been running for minutes: cause 2 or 3.
• Context limit reached, or an Autocompact is thrashing message: cause 4.
• A tool call to a connected service that never returns, or a line telling you to run /mcp: cause 5.
• Retrying in Ns · attempt x/y, Waiting for API response, or Usage limit reached: cause 6.
• Nothing at all, and the prompt does not respond to typing: the last section.

Ctrl+O opens the transcript viewer, which shows the detailed tool calls. It is the quickest way to see the last thing Claude actually tried.

1. It is waiting for your permission

The most common stall is not a stall. Claude asked to run a command or edit a file, the prompt is sitting there, and you were in another window. Background subagents make this easier to miss: when one needs permission, the prompt appears in your main session and names the subagent asking. For background sessions, claude agents shows the row as Needs input.

Claude Code fires a notification↗ (opens in a new tab) when a permission prompt has waited about six seconds and you appear to be away. By default it sends a desktop notification only in Ghostty, Kitty and iTerm2. In any other terminal, set preferredNotifChannel to terminal_bell in your settings and you will hear it instead of finding it an hour later.

The recovery is to answer. The prevention is to stop being asked the same question twenty times: open /permissions and add an allow rule for the commands you always approve, such as your test runner. Keep the rule narrow; an allow rule for every shell command is not a fix for prompt fatigue.

2. A shell command that will not finish

Some commands never end by themselves: a dev server, a file watcher, a test runner in watch mode, or anything that has stopped to ask a question on standard input that nobody will answer. Claude Code does not wait forever. Its Bash tool has a default timeout of two minutes↗ (opens in a new tab) (BASH_DEFAULT_TIMEOUT_MS), and Claude can raise that per command up to a ceiling of ten minutes (BASH_MAX_TIMEOUT_MS). When a command reaches its timeout, Claude Code moves it to the background instead of killing it, unless the command starts with sleep.

• Press Ctrl+B to send the running command to the background yourself and get the conversation back. Under tmux, press it twice.
• Press Esc to interrupt the turn, then tell Claude what went wrong: “that command is waiting for input; run it with the non-interactive flag”.
• If the command belongs in the background permanently, a dev server for example, say so up front: “start the dev server in the background, then run the tests”.

3. A background job it is waiting for

Sometimes Claude is not stuck, it is waiting for a background subagent or a long test run to report back. Run /tasks (also /bashes) to see the background work in the session, including subagents that have just finished. From there you can open one, check its output or stop it. Ctrl+X Ctrl+K stops every background subagent at once. If a background job is itself the thing that hung, stop it from /tasks, and Claude carries on with what it has.

The details of each kind of background work, and how quickly the list forgets finished jobs, are in Claude Code background tasks.

4. The context window is full

Long sessions fill the context window. Claude Code compacts automatically, summarising the conversation to make room, but two failure modes↗ (opens in a new tab) look like a hang. The first is Context limit reached: requests fail until you free space. The second is Autocompact is thrashing: compaction worked, but a large file or tool output refilled the window straight away several times in a row, so Claude Code stopped retrying.

1. Run /context to see what is using the space. When the conversation is over the limit, it says by how much and which command frees space.
2. Run /compact with a focus that drops the bulk, for example /compact keep only the plan and the diff.
3. If compaction itself fails with “Conversation too long”, press Esc twice to step back a few messages, then compact again.
4. Ask Claude to read the oversized file in parts, or hand that work to a subagent, which has its own context window.
5. If the earlier conversation no longer matters, /clear starts fresh. The old conversation can be reopened with /resume.

It helps to know what survives compaction↗ (opens in a new tab). Your project-root CLAUDE.md and the plan written in plan mode are re-injected from disk; the rest of the conversation is summarised. Anything Claude only knew from the chat, such as which card it was on or why it chose one approach over another, is now a summary of itself. That is one more reason to keep the state of the work on the card rather than in the conversation.

5. An MCP server is not responding

A tool call to a connected service that never comes back, or comes back with an error, points at the MCP server. Run /mcp to see each server’s status; from the shell, claude mcp list prints the same health status↗ (opens in a new tab) next to each one, such as ✔ Connected, ! Needs authentication or ✘ Failed to connect, and claude mcp get <name> shows the failure detail.

• Disconnected: /mcp reconnect <server> reconnects one server without opening the dialog.
• Signed out: a message such as MCP server "<name>" needs you to sign in again means the sign-in expired or was revoked. Run /mcp, choose the server and sign in again.
• Slow: a remote HTTP server’s request times out after 60 seconds by default, and a tool call to a network server that sends nothing for five minutes is aborted with an error. MCP_TIMEOUT controls how long a server gets to start (30 seconds by default).

A refusal is not a stall. When a fenbs board says no, the answer is a sentence naming the missing permission and the role the connection holds, for example that it cannot move a task because the role does not allow moving. Claude should relay that sentence, not retry. If it keeps retrying, stop it and fix the role or the scopes rather than the prompt.

6. Rate limits and usage limits

Claude Code retries transient failures↗ (opens in a new tab), including temporary rate-limit responses and overloaded servers, up to ten times with exponential backoff. While it does, the spinner shows Retrying in Ns · attempt x/y. If no data arrives for 20 seconds, it shows Waiting for API response · will retry in … · check your network. Both are progress, not a hang; if the second appears on every attempt, treat it as a network problem.

A usage limit on a claude.ai subscription is different: requests stop until the reset time shown. In an interactive session Claude Code can wait and carry on by itself, with a line reading Usage limit reached · continuing automatically at …. Run /usage to see your limits and when they reset, and /rate-limit-options for the other choices. One catch the documentation spells out: the continued turn still asks for permissions as usual, so an unattended session can hit cause 1 straight after cause 6.

When nothing on screen explains it

1. Press Ctrl+C to cancel the current operation.
2. Run /status for the version, model, account and connectivity. It works while Claude is responding.
3. Run /doctor for a checkup of the installation, settings and context usage; it proposes fixes and asks before applying any. If claude will not start at all, run claude doctor from the shell.
4. If the terminal is unresponsive, close it and start again. Nothing is lost: claude --resume in the same directory picks the session back up.
5. If it keeps happening, restart with claude --safe-mode, which disables plugins, MCP servers and hooks for the session. If the problem goes, one of those is the cause.

Write the blocker on the card

Once it is moving again, spend thirty seconds on the record. A stall that cost you twenty minutes will cost the next session the same twenty unless someone writes down what it was. If Claude is connected to your board, ask it to do this while it still remembers:

Comment on BUG-042:
- Blocked by: what stopped the work (the prompt, command, server or limit).
- Found with: the command that showed it (/context, /mcp, /tasks ...).
- Fixed by: what cleared it, or "not fixed" and what is needed.
- Avoid next time: one line for the next session.
If it is still blocked, flag the task for everyone so it stands out.

On fenbs that is fenbs_comment, and fenbs_flag_item with the business flag, which everyone on a team board sees (it needs the Flag for everyone permission). fenbs has four fixed lanes, To Do, Next Up, In Progress and Completed, and no separate Blocked lane, so a blocker is a comment and a flag rather than a move. If the cause will recur, such as a test command that always needs a flag to run unattended, ask Claude to add it to the board’s AI context with fenbs_add_context_note, so every assistant reads it before it starts.