Problem Solutions
Claude Code Stuck on Thinking? Check the Spinner First — Then Follow This Ladder
When Claude Code seems stuck on “thinking”, the first thing to check is the spinner line. If the seconds and token counter keep moving, Claude is working — wait. Everything else follows from that one check. This is the full ladder, tested on October 29 with Claude Code v2.1.312 on macOS; the Windows and Linux steps follow Anthropic’s official instructions.
Step 1: Read the spinner
While Claude works, the spinner shows a playful word, elapsed time and a token counter — for example “Grooving, 5s, 248 tokens, thinking”. The word changes turn to turn; ignore it. Movement is the signal: counting seconds and growing tokens mean real work. A big request, a long file or a higher effort level can make thinking last a while, and that is normal.
Step 2: Press Esc — once
If the wait is too long or you asked for the wrong thing, press Esc. Claude Code stops the turn, shows “Interrupted”, and asks what to do instead. Your conversation and anything already written stay in place — much better than closing the terminal. Then ask for less: split a big request (one file at a time, a short answer first). Shorter requests finish faster and use fewer tokens.
Step 3: Queue instead of waiting
You do not have to sit and watch. While Claude works, type your next message and press Enter — it queues in gray (ctrl+x ctrl+s sends it now; the up arrow edits queued messages) and reaches Claude when its current tool calls finish.
Step 4: Read the waiting banner
If the spinner stops and a “Waiting for API response” banner appears with a retry countdown, Claude Code has gone at least 20 seconds without data. The request has not failed: the countdown runs until it aborts the stalled connection and retries, and the banner clears on its own when data returns. If it appears on every attempt, treat it as a network problem — try another network, turn off a VPN, check for a proxy holding the response. After an abort: if Claude had finished nothing, it retries or ends with an error; if it had finished part, you see “The response above may be incomplete” — type “continue” and it picks up; if it had finished everything, the turn simply ends.
Step 5: Retries, timeouts, effort
While retrying, the spinner shows “Retrying in a few seconds” with an attempt count — the default is 10 attempts (change with CLAUDE_CODE_MAX_RETRIES), which is why a bad connection can look like a long freeze. The default request timeout is 10 minutes; on “Request timed out”, just type “try again” — your original message is still in the conversation. On a slow network or behind a proxy, raise API_TIMEOUT_MS. If many requests fail at once, check status.claude.com, and try /model to switch models, since capacity is tracked per model. For speed, run /effort to open the slider (low to max, Faster to Smarter; pressing s applies it to this session only) — use lower effort for simple chores, higher for hard problems.
Step 6: The truly frozen terminal
Rarely, Claude Code stops responding to keys at all. Press Ctrl+C; if still unresponsive, close the terminal and restart. You do not lose your chat: run claude --resume in the same folder to pick the session back up.
Other causes worth checking
Very long conversations slow down and fill the context window — use /compact regularly and restart between major tasks. A plugin, hook or MCP server can slow a turn — try claude --safe-mode (disables customizations for that session) and re-enable things one at a time. If your computer slept mid-request, Claude Code treats it as a dropped connection — just resend after it wakes. And run claude update: some stall fixes are version-specific (before 2.1.222, certain gateway connections could report false timeouts). The mistakes to avoid: closing the terminal at the first pause, pressing Esc over and over during the countdown, re-pasting a huge prompt after a timeout, asking for one giant task, forgetting that claude --resume brings the chat back, and leaving effort on a high level for tiny chores. The ladder in one line: if the counter moves, wait; if it does not, press Esc; if Esc does nothing, press Ctrl+C and resume.