pi-baton

Pi Baton

Run YAML-defined review loops in Pi with per-step model switching and isolated step context.

What this is

Pi Baton is a Pi-native workflow baton runner. Define implement → review → fix loops in YAML, and let Pi Baton execute them with automatic baton handoff between isolated subagent steps.

Features

• Per-step model switching — fast model for implement, strong model for review
• Isolated step context — no shared conversation pollution between steps
• Structured review contract — accept/reject with mandatory findings or acceptance notes
• Live progress widget — see which step is running, its agent, and judgment in real time

Install

Install the published npm package with Pi:

pi install npm:pi-baton

Pin a specific version when you want reproducible installs:

pi install npm:pi-baton@0.7.1

Install into the current project instead of your user Pi settings:

pi install npm:pi-baton -l

Or install from GitHub:

pi install git:github.com/eiei114/pi-baton

Try it without permanently installing:

pi -e npm:pi-baton

Quick start

Try this package locally from a clone of this repository:

pi -e .

Then run:

/baton:new        create a workflow scaffold
/baton:start      choose workflow + task brief → idle run
/baton:run        execute run to terminal state (with live widget)
/baton:status     show the active run summary

The builtin Default Review Loop workflow (implement → review → fix) works out of the box — no agent setup required.

Prerequisites

Pi Baton ships builtin worker and reviewer subagents under agents/. They work with your current Pi model.

To override with custom agents, place .md files under:

.pi/agents/worker.md
.pi/agents/reviewer.md

Discovery order: project .pi/agents/ → user ~/.pi/agent/agents/ → pi-baton builtin.

Workflow authoring

/baton:new

Pick a name and a scaffold from default-review-loop is written to .pi/baton/workflows/ and opened in editor. The scaffold includes <your-fast-model> / <your-strong-model> placeholders for step-level model overrides.

Workflow YAML reference

name: My Review Loop
iteration_cap: 5
steps:
  implement:
    agent: worker
    model: openai/gpt-5.4        # optional: fast model
    prompt: work prompt
    next: review
  review:
    agent: reviewer
    model: anthropic/claude-opus-4-5  # optional: strong model
    prompt: review prompt
    on_accept: _complete         # or a step name
    on_reject: fix
  fix:
    agent: worker
    model: openai/gpt-5.4
    prompt: fix prompt
    next: review

• on_accept: _complete ends the run.
• iteration_cap prevents infinite review loops — the run fails at the cap.
• Review agents must return accept/reject with findings or acceptance notes.

Package contents

Path	Purpose
extensions/	Slash-command entrypoints (/baton:new, /baton:start, /baton:run, /baton:status)
lib/	Workflow parser, run engine, subagent runner, review contract, UI widget
agents/	Builtin worker and reviewer subagent definitions
workflows/	Builtin default-review-loop.yaml
assets/	README / package branding assets
docs/	Release and maintainer documentation

Development

npm install
npm run ci

Release

This package uses npm Trusted Publishing with GitHub Actions OIDC — no NPM_TOKEN is required.

npm version patch
git push

On main, version bumps trigger auto-release and publish workflows. See docs/release.md for setup details.

Security

Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.

For vulnerability reporting, see SECURITY.md.

Links

• npm: https://www.npmjs.com/package/pi-baton
• GitHub: https://github.com/eiei114/pi-baton
• Issues: https://github.com/eiei114/pi-baton/issues

License

MIT