background-task-tool
Fire off long-running commands, builds, test suites, servers,
without blocking the agent conversation. The bg_bash tool
returns a task ID immediately. Check output with task_output
and status with task_status at any time.
When the tasks extension is not active, background-task-tool shows
its own live widget for running commands. When tasks is active,
running commands move into the shared Background Tasks section
there instead. The /bg command lists and manages all active tasks.
Relationships with other extensions
Section titled “Relationships with other extensions”Background bash tasks appear in the tasks widget alongside the task board and running agents. When that shared widget is active, it becomes the canonical background-task surface and background-task-tool suppresses its standalone live widget to avoid duplicate rows and reorder jitter. Each background task shows the truncated command string and elapsed duration, capped at 5 visible entries with overflow.
In the combined widget, background tasks render below agents
with a spacer line. On wide terminals they share the right
column; on narrow terminals they stack at the bottom. Use
task_output(...) when you want the full inline output for a
specific task. See tasks, responsive layout
for the full layout behavior.
Background tasks and background subagents are different things.
Background tasks are raw shell commands (bg_bash). Background
subagents are full agent processes with their own context.
Both appear in the same widget but in separate sections, agents
first (with colored names and live activity), background tasks
below (with command strings and durations).
The footer doesn’t show background task counts directly, that information lives in the tasks widget. The footer focuses on token usage, cost, git state, and subagent counts. This avoids duplicating information that’s already visible in the widget above it.
Shell policy
Section titled “Shell policy”Background commands follow the same shell policy as the bash tool.
High-risk commands prompt for confirmation before spawning. Set
TALLOW_ALLOW_UNSAFE_SHELL=1 to bypass prompts in non-interactive
environments (CI, scripts).
All background commands are recorded in the shell audit trail.