Non-blocking background shell jobs for Pi.
pi-bg provides a bg tool for long-running builds, tests, installs, local
dev servers, and other shell commands while the parent Pi session continues.
It does not create child Pi sessions; use pi-subagents for that.
pi install git:github.com/Bukutsu/pi-bg{ "command": "npm test", "timeoutSec": 300 }
{ "command": "npm run dev", "completion": "continue" }
{ "action": "status" }
{ "action": "stop", "pid": 1 }Results default to queue mode; use "completion": "continue" when completion
should wake the parent. Do not use sleep, polling loops, or repeated status
calls to wait.
Jobs survive session replacement (/reload, /new, /resume, /fork,
/clone, /import): the shell keeps running and the result is delivered when
the originating session is active again, matched by session id or file path.
Stopping a handed-off job requests the previous runtime to abort it. Retained
troubleshooting logs are written under <agent-dir>/pi-bg/logs (newest 50 kept)
so they survive process exit and updates.
| Event | Effect on jobs |
|---|---|
/reload, /new, /resume, /fork, /clone, /import |
Job keeps running; result handed to the origin session's next runtime |
/tree, /compact, model/thinking change |
Unaffected |
| Ctrl+Z suspend | Jobs pause with pi (process-group SIGTSTP) and resume on fg |
Quit (Ctrl+D, SIGHUP, ctx.shutdown(), pi update restart) |
Jobs are stopped; retained logs remain in <agent-dir>/pi-bg/logs |
Print mode (-p) |
Process exits after each prompt; jobs stop |
| RPC mode | Delivery works; completion:"continue" runs a turn in-process |
Extension load failure on /reload |
Old jobs keep running but nothing drains them; entries expire after 10 minutes |
If you navigate to another conversation branch, the result waits until you return to the originating branch.
| Name | Purpose |
|---|---|
action |
spawn, status, or stop |
command |
Shell command for spawn |
completion |
queue is the default; continue wakes the parent when ready |
pid |
Virtual job ID for stop |
timeoutSec |
Maximum run time in seconds; defaults to 600 |
Run /bg to list or stop active jobs. Use /bg kill <pid> or /bg kill all
for direct control.
The command runs with the current Pi working directory and session environment,
including Pi's configured shell path and command prefix.
Model-visible output is bounded at 16 KB or 400 lines. Human-facing rendering
remains descriptive while agent control results use compact JSON. Failed, stopped,
timed-out, non-zero, and truncated jobs retain a sanitized private temporary log
capped at 10 MB. The completion message includes its path; use Pi's built-in
read tool when the displayed result is not enough.
bun install
bun run check
bun testThis extension is intentionally shell-only. Child Pi sessions belong in the
separate pi-subagents extension.
MIT