Delegate bounded coding tasks to exact models available through your local Pi installation.
Pi Worker is a small CLI and coding-agent skill. Your primary agent remains the orchestrator; Pi Worker starts one to three workers in parallel, keeps results in request order, and returns each worker's status and final explanation.
Using the primary agent for every subtask can consume an expensive or limited quota. Pi may already expose a lower-cost model or a model billed through a separate account. Pi Worker removes the manual prompt-and-result copying while enforcing an exact provider/model choice and reporting the effective thinking level.
You need Node.js 22.20.0 or newer and a Pi CLI with provider authentication.
Pi 0.84.1 is verified; other semantic versions run with an explicit warning.
Install the npm package:
npm install -g pi-workerThe npm package supports only macOS and Linux on arm64 and x64. It includes the
native binary and provider-neutral skill. npm install attempts to install the
skill for detected coding agents through pinned skills@1.5.22; it never
overwrites an unrecognized existing skill.
Native archives are available from GitHub Releases. Windows users must build from source; Windows is compile-checked but not runtime-tested. Source builds are documented in detailed usage. The Go binary can also be installed directly without the bundled skill:
go install github.com/arasovic/pi-worker/cmd/pi-worker@latestThe binary lands in go env GOBIN, or in $(go env GOPATH)/bin when GOBIN
is unset. That directory must be on PATH:
command -v pi-workerSafety: Workers can modify the current writable workspace and execute
bashwith the current user's host permissions. Pi Worker is not a sandbox or worktree layer. Use a trusted workspace; parallel tasks must be disjoint.
Choose an exact selector, check readiness, save a default, and run a task.
Replace provider/model with one exact selector printed by pi-worker models
before config set:
pi-worker models
pi-worker doctor
pi-worker config set default-model provider/model
pi-worker run --thinking high --task "Review this module and explain the main risks"Doctor is read-only. Its five checks, in order, are pi-executable,
pi-version, config, model-catalog, and default-model.
Thinking is separate from model identity. Accepted values are off, minimal,
low, medium, high, xhigh, and max. An unsupported explicit effort
keeps the same model, uses Pi's confirmed default, and reports the fallback.
The requested model/provider never silently changes.
From a coding agent, a request can be as short as:
Use pi-worker with provider/model at high effort to complete this task.
Run up to three independent tasks by repeating --task or --task-file.
Parallel writes must target disjoint files because every worker shares the
current writable workspace.
Pi Worker is not a sandbox. bash has the current user's host permissions, and workers can edit the current workspace. Use one worker for overlapping work.
An exact requested model never silently changes. Thinking fallback stays on the same model and reports the fallback. Installer state is recorded in a durable receipt; the stable identity marker distinguishes recognized Pi Worker content.
Show foreground installer diagnostics and inspect skill state:
npm install -g --foreground-scripts pi-worker
pi-worker skill status
pi-worker skill status --json
pi-worker skill receipt-path
npx --yes skills@1.5.22 list -gA separately installed recognized skill is externally managed and may be stale. Markerless, foreign, or mixed content is never overwritten automatically. After backing up and verifying every affected path as Pi Worker content, recovery may require:
npx --yes skills@1.5.22 remove pi-worker -g -y
npm install -g --foreground-scripts pi-workerDo not use the global remove command for unrecognized content.
- Detailed usage
- Versioned JSON contracts
- Architecture
- Pi compatibility surface
- Release snapshot runbook
- Contributing
- Security
See LICENSE and THIRD_PARTY_NOTICES.