What It Does

• Installs a global pi-spawner CLI through npm.
• Opens a terminal settings manager with pi-spawner.
• Shows friendly preflight guidance with pi-spawner doctor.
• Stores user settings in ~/.pi/pi-spawner/models.json.
• Manages aliases such as sonnet, gpt, kimi, deepseek, qwen, and gemini.
• Maps task routes such as code, plan, writing, review, and design.
• Generates Codex, Claude Code, Cursor, and Hermes Agent adapters that call pi-spawner delegate.
• Keeps Pi workers read-only by default, with explicit write tasks captured for host review.

Install

Prereqs:

• Node 20+
• Python 3.9+
• Pi CLI installed with pi on PATH
• At least one Pi provider/API key configured before delegation

Install the CLI:

npm install -g pi-spawner

Check setup:

pi-spawner doctor

Open the settings manager:

pi-spawner

If doctor reports a missing step, fix that Pi/Python/provider setup first and rerun it. Pi Spawner does not install Pi or manage provider secrets; it detects the Pi setup and gives concrete next steps.

Settings Manager

The TUI opens a guided setup wizard. It starts with doctor checks, then walks through model aliases, routes, the read-only worker parallel limit, host detection, multi-select host installation, and install results. Prompts support arrow keys, Enter, Esc, and Ctrl+C. If aliases/routes target providers that are not currently authenticated, the wizard offers to pick one available model and repair the default routes.

• Aliases: provider/model/thinking triples
• Routes: task type to alias/model mappings
• Runtime settings: default parallel read-worker limit
• Model picker: searchable full pi --list-models catalog filtered to authenticated providers
• Hosts: detected Codex, Claude Code, Cursor, and Hermes Agent installs, with selected adapters installed by the wizard

Settings live at:

~/.pi/pi-spawner/models.json

Config precedence is:

spec config_path > PI_SPAWNER_CONFIG > ~/.pi/pi-spawner/models.json > bundled defaults

Host Adapters

Generate adapters:

pi-spawner hosts

The recommended path is to run pi-spawner and use the setup wizard. It detects installed hosts, lets you select one or more, then runs the required install steps. Generated adapters are thin: each host skill/plugin calls the global pi-spawner delegate command, so updating the npm package updates the runtime without rewriting host prompts. Set PI_SPAWNER_ADAPTER_COMMAND before running the wizard if adapters must call a custom wrapper.

Manual fallback:

codex plugin add pi-spawner@personal
claude plugin marketplace add ~/.pi/pi-spawner/adapters/claude-marketplace --scope user
claude plugin install pi-spawner@pi-spawner --scope user
ln -sfn ~/.pi/pi-spawner/adapters/cursor ~/.cursor/plugins/local/pi-spawner
hermes skills install ~/.pi/pi-spawner/adapters/hermes/skills/pi-spawner

The repository itself is not the install target for host plugins. Install the npm package, then let pi-spawner hosts generate host-specific adapters that call the installed CLI.

CLI Usage

Dry-run a delegation before calling models:

pi-spawner delegate --dry-run <<'JSON'
{
  "cwd": "/path/to/repo",
  "orchestrator_name": "Codex",
  "tasks": [
    {
      "id": "design",
      "route": "design",
      "prompt": "Review the dashboard UI hierarchy and interaction polish."
    },
    {
      "id": "review",
      "alias": "deepseek",
      "thinking": "high",
      "prompt": "Find regression risks in the recent diff."
    },
    {
      "id": "edit",
      "route": "code",
      "permission": "write",
      "prompt": "Make the smallest direct edit needed for the failing test."
    }
  ]
}
JSON

Run without --dry-run to execute workers.

Useful commands:

pi-spawner doctor --json
pi-spawner models openrouter
pi-spawner config path
pi-spawner config init --reset
pi-spawner config set max_concurrency 3
pi-spawner aliases list
pi-spawner aliases set sonnet --provider openrouter --model '~anthropic/claude-sonnet-latest' --thinking high
pi-spawner routes set review deepseek

Model Selection

Resolution order for each worker is:

task alias/model > top-level alias/model > task route > default route > config defaults > Pi settings > Pi CLI defaults

Thinking is resolved separately:

task thinking > top-level thinking > selected alias/model thinking > config defaults > Pi settings

Read-only workers run concurrently up to max_concurrency, which defaults to 3. Any run containing a write-enabled task still executes sequentially so direct file changes can be attributed.

Pi Spawner does not silently switch models. If a provider is not authenticated, a model is unavailable, or thinking is unsupported, the wrapper returns a structured failure so the host agent can ask which alias, route, provider, or auth setup should be used next.

Repository Layout

package.json
src/
dist/
skills/pi-spawner/SKILL.md
skills/pi-spawner/models.json
skills/pi-spawner/scripts/pi_delegate.py
assets/
docs/

src/ is the npm CLI and TUI layer. skills/pi-spawner/scripts/pi_delegate.py remains the delegation engine for v1 compatibility.

Development

npm install
npm test

Useful local checks:

node dist/cli.js doctor
node dist/cli.js delegate --dry-run < spec.json
python3 /Users/johnnybae/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/pi-spawner

Publishing

The public npm package is unscoped:

npm publish --access public

The GitHub Packages variant must be scoped to the GitHub owner. The included GitHub Actions workflow publishes the same version as @jbaehova/pi-spawner by rewriting package.json only inside CI.

Before pushing a release tag, add an npm automation token as the repository secret NPM_TOKEN. GitHub Packages uses the workflow GITHUB_TOKEN.

node -p "require('./package.json').version"
npm test
npm pack --dry-run
git tag "v$(node -p "require('./package.json').version")"
git push origin HEAD --tags

License

MIT. See LICENSE.