@bytetrue/pi-background-terminal

Pi's built-in bash is the foreground executor — and this package never touches it. It adds one standalone tool for the other half of the decision:

• Need the command's output to continue? Use bash — it blocks and returns the result.
• Should it run hands-off (builds, test suites, dev servers, watch mode)? Use background_run — it returns a task id immediately, and the Agent keeps working or ends its turn, and the command's exit arrives as a new message (exit code + last output line) that starts the next turn. That notification is how the Agent waits.

background_run(command, timeout?):

• timeout defaults to 600 seconds — a hard lifetime cap so nothing lingers forever. Pass a larger value (e.g. 86400) for dev servers and watch modes.
• Full stdout/stderr stream live to an output file (path in the result); the Agent reads it with Pi's built-in read only when needed.
• In TUI/RPC sessions the exit notification fires normally. In pi -p the process exits with the turn, so a task started there dies before its exit can be reported — hands-off backgrounding belongs in interactive sessions (subagent children are killed by their own session_shutdown).

Install

pi install npm:@bytetrue/pi-background-terminal

Restart or reload Pi, then ask naturally:

Start the test suite running hands-off — get back to me when it finishes.

The Agent calls background_run, keeps working or waits, and reports the outcome when the exit notification arrives. Completions that pile up while the Agent is busy arrive as one batched follow-up, not one turn per task.

Tools

Tool	Required input	Result
background_run	command	Task id + output file path, immediately; exit reported via follow-up; optional timeout (default 600s)
background_status	id	Status, exit code, line count, output path, and recent output
background_kill	id	Stops a running task

No built-in tool is overridden, shadowed, or registered under a built-in name.

Staying out of the built-ins' way

• bash (and powershell) keep their exact built-in behavior; the only touch is a tool_call hook injecting timeout: 600 when a call passes none — a safety net for runaway foreground commands, not a coupling. Explicit timeouts are respected.
• The background_run path applies your shellPath / shellCommandPrefix settings (read through Pi's own SettingsManager, honoring project trust) and the same session environment the built-in tools set (PI_* variables plus the agent bin dir on PATH).
• Uninstalling removes exactly the three tools above; the built-ins were never touched.

Requires @earendil-works/pi-coding-agent >= 0.80.5.

Lifecycle

A task ends when:

• the command exits (the agent is woken with the outcome);
• background_kill stops it (silent);
• its hard timeout expires (status timed_out, the agent is woken); or
• the owning Pi session shuts down — or the Pi process dies by any path (signal, crash): tasks spawn through Pi's own shell backend and are killed with it (verified against SIGTERM; only a command that daemonizes itself escapes, same as built-in bash).

Manual stops and session cleanup are silent. Tasks survive /reload inside the same session, but they do not survive Pi exiting.

Output is stored under $TMPDIR/pi-background-terminal/ and removed at real session shutdown. Output files cap at 50 MiB: beyond that the file stops growing and a marker records what was dropped (the task itself keeps running). Tasks are isolated by session id. If Pi itself crashes, stale logs older than 24 hours are swept the next time the extension loads.

Deliberate limits

• Pure background: no foreground wait, no inline output (that is bash's job)
• No override of any built-in tool (the 600s input default is the only touch)
• No PTY or interactive stdin
• No custom cwd or environment input
• No configurable defaults (600s lifetime / 50 MiB cap are fixed)
• No daemon, tmux dependency, Web UI, or cross-session persistence
• No output pagination in tool results—read handles large output

Development

npm --workspace @bytetrue/pi-background-terminal test
npm --workspace @bytetrue/pi-background-terminal run typecheck
npm pack --workspace @bytetrue/pi-background-terminal --dry-run