PI-SPAWNER

Language
English | 中文 | 한국어 | Español | 日本語

NPM CLI and TUI settings manager for Pi Agent model workers

Configure aliases, routes, providers, models, and thinking levels once, then let Codex, Claude Code, Cursor, Hermes Agent, or another Agent Skills host call the same Pi Spawner delegation CLI.

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.