Pi's built-in bash is the right tool for commands that finish during the current call. This extension adds two things on top of it—without overriding any built-in tool:

• a separate background path for dev servers, watch mode, and long-running work; and
• a default 10-minute timeout for built-in bash/powershell calls that do not pass one.

Install

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

Restart or reload Pi, then ask naturally:

Start the development server in the background.

The Agent starts the command, returns immediately, and receives a follow-up when the process exits on its own. 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 | Starts a command and returns a task id plus output-file path | | background_status | id | Returns status, exit code, line count, output path, and recent output | | background_kill | id | Stops a running task |

All three schemas contain required parameters only. There are no timeout, working-directory, environment, list, or pagination arguments.

Default shell timeout

Pi's built-in bash (and powershell on Windows) runs with no timeout at all unless the model passes one—which means a single runaway foreground command (find /, a wedged build) can hang the agent for hours.

This extension listens to Pi's tool_call event and injects timeout: 600 into shell tool calls that did not pass their own:

• the model explicitly passing timeout is respected as-is;
• background tasks (background_run) are not affected—they are supposed to run long;
• the built-in tools themselves are never overridden or re-registered.

[!NOTE] Full stdout and stderr stream to the output file returned by background_run. The Agent uses Pi's built-in read tool when it needs more than the recent preview.

Manage tasks yourself

Run /background to open the human-facing task menu. It lists running tasks for the current session and lets you inspect their output or stop them with confirmation.

The footer shows bg:N while tasks are running.

Lifecycle

A task ends when:

• the command exits;
• background_kill stops it; or
• the owning Pi session shuts down.

Natural completion wakes an idle Agent. 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. Tasks are isolated by session id.

Deliberate limits

• No PTY or interactive stdin
• No custom cwd or environment input
• No configurable default timeout value (600 seconds is fixed)
• No daemon, tmux dependency, Web UI, or cross-session persistence
• No replacement for Pi's built-in bash or read

Development

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

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