Home / When things go wrong

A stuck command

A shell command that stops responding is cut off with Ctrl+C without closing the session, and the delay that switches it to a background task is already fixed by Claude itself, not by a prefix you add by hand.

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. Confusing the two makes a chat wait for nothing, or cuts off a command that was about to succeed.

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.