pi-baton

v0.7.2

Published

13 days ago

Pi-native workflow baton runner with per-step model switching and isolated step context.

0High
0Medium
0Low

eiei114

pi-package pi pi-extension workflow review-loop typescript

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:[email protected]

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.

License

MIT