@moontrain/pi-bg-proc

A pi extension that lets the agent run background processes without burning a turn. Dev servers, watchers, build daemons, and test runners get spawned detached, stream to a log the agent can tail later, and get killed as a whole process tree when they are no longer needed.

Without it, an agent that runs npm run dev in the foreground blocks until you interrupt it. With it, the agent starts the server, gets a task id back immediately, and reads the log whenever it wants.

Install

pi install npm:@moontrain/pi-bg-proc

Or try it for one run: pi -e npm:@moontrain/pi-bg-proc

The bg_proc tool

Action	Purpose
spawn	Start a command detached and return its task id immediately
read	Tail the live log of a running or finished task
kill	Terminate a task's entire process tree
list	Show every tracked task with status and uptime

Parameters

Name	Type	Applies to	Description
action	"spawn" | "read" | "kill" | "list"	all	Required.
command	string	spawn	Shell command to run.
cwd	string	spawn	Working directory. Defaults to the pi project directory.
name	string	spawn	Friendly label folded into the task id, e.g. dev-server.
timeout	number	spawn	Auto-kill the task after N seconds.
id	string	read, kill	Task id returned by spawn.
lines	number	read	Max tail lines. Default 2000.

Log output is truncated to the last 2000 lines or 50 KB, whichever comes first.

The /bg_proc command

/bg_proc            browse tracked tasks, live-tail logs, kill from the list
/bg_proc bg_xxx     jump straight into one task's log viewer

The log view refreshes on an interval, so you can watch a build or a server boot in real time.

How it works

Native shell. Commands run through the OS shell rather than a bundled one: cmd.exe /c on Windows, $SHELL -c (falling back to sh) elsewhere. Your aliases, PATH, and shell syntax behave the way they do in your terminal.

Whole-tree kills. Killing a task kills its children too — taskkill /T /F on Windows, negative-PID signalling against the process group on POSIX. This is the part that matters in practice: a plain kill <pid> on npm run dev leaves the actual node server holding port 3000.

Session rehydration. Tracked tasks are written into the tool result details, so on session_start the extension rebuilds its registry from the session transcript and drops any PID that is no longer alive. A resumed session still knows about the dev server it started before. Pending timeout timers are restored with their remaining time, and a task whose timeout already elapsed while pi was down is killed on startup.

Shutdown cleanup. session_shutdown kills everything still tracked, so a closed pi session does not leave orphans behind.

Notes and limits

• Logs are written to a temp directory ($TMPDIR/pi-bg-proc/), not the repo.
• Rehydration reads the most recent bg_proc tool result in the session branch. A task spawned in a session branch you have since abandoned is not recovered.
• PID reuse is possible in theory: if the OS recycles a PID after a tracked process dies, a rehydrated entry could point at an unrelated process. In practice the window is small, but do not treat list as an authoritative process table.

License

MIT © Moontrain Technologies