Let your coding agent hand small, well-defined tasks to a cheaper model.

Quick start · Detailed usage · Architecture

How it works

• You keep your agent. Claude Code, Codex or Hermes stays the orchestrator.
• Small tasks go to cheaper models. Pi Worker runs up to three Pi workers in parallel, each on the exact model you asked for.
• Results come back in order. Every worker returns its status and a final explanation, in request order.
• Your agent already knows how. npm install also installs the pi-worker skill into Claude Code, Codex, Hermes and 70+ other detected coding agents, so the agent calls pi-worker itself.

Already on Pi? This is pi with a queue, parallelism and a result contract.

Quick start

Requirements: Node.js 22.20+, a Pi CLI with provider authentication, macOS or Linux on arm64 or x64.

1. Install. This also installs the skill for every detected coding agent.

   npm install -g pi-worker

   If npm warns that pi-worker has install scripts not yet covered by allowScripts, the warning did not stop it: the install script still ran. Check the skill with pi-worker skill status. To stop the warning on later updates, run npm config set allow-scripts=pi-worker --location=user; if you already allow other packages, list them too, separated by commas.

   go install github.com/arasovic/pi-worker/cmd/pi-worker@latest gives you the binary without the skill.

2. Pick a model. Replace provider/model with one exact selector printed by pi-worker models.

   pi-worker models
   pi-worker doctor
   pi-worker config set default-model provider/model

3. Run a task

   pi-worker run --thinking high --task "Review this module and explain the main risks"

4. Or let your agent do it. Paste this into your coding agent:

   Use pi-worker with provider/model at high effort to complete this task.
   

The requested model never silently changes. Repeat --task for up to three independent tasks that touch disjoint files. Thinking levels, pi-worker skill status, source builds and other platforms are in detailed usage.

Safety: Pi Worker is not a sandbox. Workers can edit the current workspace and run bash with the current user's permissions. Parallel tasks must touch disjoint files.

Documentation

• Detailed usage — every command, flag, exit code and edge case.
• JSON contracts — the versioned --json output shapes.
• Architecture — how a run is admitted, supervised and measured.

Also: Versioning · Contributing · Security · Release runbook · Pi compatibility surface

License

See LICENSE and THIRD_PARTY_NOTICES.