Claude's background commands on pi's bash tool. Source: extensions/background-bash.ts, with the shared registry in extensions/internal/background-shells.ts.
run_in_background: truestarts a command as a background task and returns at once with its ID and the file its output is written to.- A foreground command that reaches its timeout is moved to the background instead of stopped, unless it starts with
sleep. The result says so:Command did not complete within its 120s timeout and was moved to the background (ID: …). - When a background command finishes, a message reaches the session with its exit status and output file, and starts a turn, so an idle session wakes up to handle it. During a turn the message is steered in before the next model call. The model reads the output with the
readtool. - The override replaces pi's
bashonly where the session has it: a session whose tool selection leavesbashout (thedefaultToolssetting,--no-builtin-tools,--tools -bash, or abashturned off before/reload) stays without it.task_stopstays in such a session, as Claude keeps TaskStop where Bash is denied. task_stop(Claude'sTaskStop, with its aliasesKillShellandKillBash) stops a running command bytask_id, or by the deprecatedshell_id. A stopped command sends no completion message./taskslists background shell commands after background subagent runs, the last 20 finished ones included. A finished command dropped from that list loses its output file.- The footer shows how many background commands are running (
⏵ 2 background shells), and clears when none are. A foreground command is not counted until it moves to the background.
- Timeouts:
BASH_DEFAULT_TIMEOUT_MS(two minutes) applies when the model passes no timeout; a requested timeout is capped at the larger of that andBASH_MAX_TIMEOUT_MS(ten minutes). An unset, blank, zero, negative or non-numeric value keeps the default. A timeout over 2147483647 ms (about 24.8 days, the longest delay a timer holds) runs as that one, as Claude accepts any positive value. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1turns background commands off: the tool has norun_in_backgroundparameter, a call that passes it anyway fails, and a command still running at its timeout is stopped. The default timeout still applies.- A command outlives a session switch: across
/new,/resume,/forkand/reloadit keeps running. In a session that has not had a turn yet, its completion message is recorded for the next prompt instead of starting one, as background subagent results are. - Quitting pi stops every background command and removes their output files.
- Output cap: a background command whose output file passes 5 GB is stopped, and its completion message says so.
- The output, truncation, renderer and exit-code reporting are pi's own: the built-in bash tool still runs each command, through its operations seam, with pi's
shellPathandshellCommandPrefixsettings. A background command's output goes to its output file only; the copy pi keeps of a foreground command's truncated output is removed if the command then moves to the background.
- The timeout is in seconds, as pi's bash tool takes it, where Claude's is in milliseconds.
- A session without a UI (print and json modes, subagents) has background commands off, exactly as with
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1: it ends with its last turn, so no later turn could receive a completion message. Claude runs background commands under-p, with a time limit. - No time limit on background commands, as in an interactive Claude session. Claude's limits for unattended sessions (30 minutes by default, 10 minutes for a
-prun whose prompt is passed as text) do not apply, since unattended runs do not background here. - No Ctrl+B to move a running command to the background.
- A completion message goes to whichever session is current when the command finishes, or to the next session start when none is: after
/new, that is not the session that started the command. - Stopping is a kill with no grace period:
task_stop, the output cap and quit sendSIGKILLto the command's process group (taskkill /F /Ton Windows), with noSIGTERMfirst. - A process that leaves the process group (
setsid) survivestask_stopand quit. Claude stops these. /taskslists background commands but cannot stop one; onlytask_stopdoes.