@buyong/pi-background-exec
Background shell jobs for Pi that wake the agent with their results, and Herdr agent state that stays working until those jobs finish.
Package details
Install @buyong/pi-background-exec from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@buyong/pi-background-exec- Package
@buyong/pi-background-exec- Version
0.1.3- Published
- Nov 16, 2026
- Downloads
- 490/mo · 490/wk
- Author
- buyong
- License
- Apache-2.0
- Types
- extension, skill
- Size
- 47.5 KB
- Dependencies
- 0 dependencies · 1 peer
Pi manifest JSON
{
"skills": [
"./skills"
],
"themes": [],
"prompts": [],
"extensions": [
"./src/background-exec.ts",
"./src/herdr-agent-state.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-background-exec
English | 한국어
Runs long shell commands such as builds, tests, and simulations in the background, so the agent can end its turn instead of waiting. When a job finishes, the package wakes the agent with the job's status and the end of its log. Inside Herdr, the Pi pane stays working until those jobs finish and the agent has handled their results.
Requirements
- Pi 1.5.0 or later, and Node.js 22.19 or later.
background_execworks only in interactive (TUI) and RPC sessions.- Herdr state reporting follows Herdr 0.9.5 (Pi integration version 9) and works only in the TUI.
Install
pi install npm:@buyong/pi-background-exec
If you already load your own copy of background_exec, for example ~/.pi/agent/extensions/background-exec.ts, remove it first. Two extensions that register the same tool name collide.
What you get
| Name | Type | What it does |
|---|---|---|
background_exec |
Tool | Starts a shell command in the session's working directory and returns its jobId right away. timeout (seconds) is optional. |
background_job |
Tool | Shows the status of a job or cancels it. |
background-exec |
Skill | Tells the model when to use these tools and how to handle their results. |
| Herdr agent state | Extension | Reports working, blocked, and idle to Herdr. |
When a job finishes while the agent is idle, the agent starts a new turn with a background-job-finished message. Jobs that finish during a turn are held and sent together at the next turn boundary as background-jobs-finished. Each message carries the status, the exit code, up to 1 KiB or 12 lines of the log, and remainingJobs.
Switching, reloading, or quitting the session cancels its running jobs. Ending a turn does not. Each job keeps output.log and result.json under <session directory>/background-exec/<session id>/<job id>/. The files are readable only by you and are not deleted automatically.
Use with Herdr
Herdr accepts state reports for a Pi pane from one reporter only. Replace Herdr's own Pi integration with this package's:
- Run
herdr integration uninstall pi. - In Pi, run
/reloadafter your running jobs finish, because a reload cancels them.
While Herdr's Pi integration is installed (herdr-agent-state.ts in Pi's extensions directory), this package does not report to Herdr, and Herdr's integration reports alone. To switch back, run herdr integration install pi and /reload.
With this package reporting:
- The pane stays
workingafter the agent ends a turn with jobs still running, and becomesdoneafter the agent handles the last result.herdr agent prompt --waitreturns at that point. - Pressing Escape to stop a run makes the pane
idleat once, even with jobs still running. - Another extension can keep the pane
workingby answering thebackground-work:query-pendingevent for its own pending work. pi-notify waits on the same event before it notifies "Ready for input".
To use only the background jobs without Herdr reporting, select the extension in your Pi settings:
{
"packages": [
{
"source": "npm:@buyong/pi-background-exec",
"extensions": ["src/background-exec.ts"]
}
]
}
Verify
From apps/pi-background-exec in this repository:
pnpm run lint
pnpm run typecheck
pnpm run test:unit
To check a running Pi, start it from the repository root with only this package's extensions (pi --no-extensions -e ./apps/pi-background-exec) and ask: Use background_exec to run "sleep 5 && echo done", then end your turn. A background-job-finished message with "status":"succeeded" and the log tail done should arrive about five seconds later. This check needs a model.
License
Apache-2.0. The Herdr reporter is derived from Herdr's Pi integration; see NOTICE.