Home / When things go wrong

A stuck command

For a frozen shell command, press Ctrl+C, which attempts to interrupt the operation; otherwise relaunch with claude --resume. Do not add a timeout prefix by hand, because the Bash tool already carries a delay parameter that Claude chooses itself, and most commands that reach their delay switch to a background task instead of being stopped.

A shell command launched from Claude Code can stay frozen: no output, no end. The first move is Ctrl+C, which attempts to interrupt the operation in progress without closing the session. If that is not enough, closing the terminal and relaunching with claude --resume in the same folder recovers the entire conversation, only the stuck command itself is lost.

The delay is not a habit to add yourself

A common habit is to wrap every risky command in a timeout prefix typed by hand. That is not how the Bash tool built into Claude Code actually works. It already carries a timeout parameter that Claude itself chooses to add when it anticipates a long-running command, with no action on your part. Two environment variables bound this behaviour: BASH_DEFAULT_TIMEOUT_MS sets the default delay applied to each command, BASH_MAX_TIMEOUT_MS sets the cap that Claude cannot exceed even if it asks for more.

# Two environment variables read by Claude Code
BASH_DEFAULT_TIMEOUT_MS=120000   # 2 minutes, default value
BASH_MAX_TIMEOUT_MS=600000       # 10 minutes, cap

The automatic switch to a background task

When a command reaches its delay without finishing, Claude Code does not stop it: it switches it to a background task on its own and carries on working while it runs. Three families of commands escape this automatic switch and remain blocking to the end: those that start with sleep, those that contain git, and compound commands the security parser cannot analyse, such as an expansion of the type ${PIPESTATUS[0]}. For a process you already know will be long, a development server or a build left running, it is better to explicitly request the run_in_background parameter rather than wait for the timeout to trigger.

# Simulates a long command, without changing anything on this machine
node -e "setTimeout(() => console.log('travail termine'), 5000)"
# Launched with run_in_background, it hands control back immediately
# and its output can be read later, without having blocked the conversation thread

The difference between the two situations rests on a single fact: the timeout protects against a command that will never finish, switching to a background task frees up the conversation while a command that will finish takes its time.

This same recover-without-losing-anything logic reappears when it is the whole session that stalls rather than a single command, see loops, polluted context and restarting.

Watching a background task without waiting for it

Claude no longer polls a background command's output file or sleeps while it runs. The Monitor tool also exists on Bedrock, Vertex and Foundry, where long foreground sleep pauses are now blocked. A time limit applies to background commands, but only in unattended sessions (-p, SDK, CI, cloud): a terminal, desktop or VS Code session has none.

To get back to a background session, claude attach <name> and claude logs <name> accept part of a session name in place of the id. The ← key sends the session to the background: a turn or ! command started while the session moves is stopped, instead of finishing out of sight.