pi-crews0.1.0

Named child agents, background delegation and Git worktrees for Pi

oswa1d99 Published 1 month ago MIT ~385 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Reports 0

No reports yet.

Readme

██████╗ ██╗        ██████╗██████╗ ███████╗██╗    ██╗███████╗
██╔══██╗██║       ██╔════╝██╔══██╗██╔════╝██║    ██║██╔════╝
██████╔╝██║█████╗ ██║     ██████╔╝█████╗  ██║ █╗ ██║███████╗
██╔═══╝ ██║╚════╝ ██║     ██╔══██╗██╔══╝  ██║███╗██║╚════██║
██║     ██║       ╚██████╗██║  ██║███████╗╚███╔███╔╝███████║
╚═╝     ╚═╝        ╚═════╝╚═╝  ╚═╝╚══════╝ ╚══╝╚══╝ ╚══════╝

Your crew. Your rules. Their work.

Named child agents, background delegation and Git worktrees for Pi.

pi-crews lets the main Pi agent hand work to named child agents. Each child is a normal Pi session, the same as one you would open yourself. A child that writes code works in its own Git worktree and returns a patch. The main agent has the patch reviewed, then applies it.

Features

Named children. Delegate 1–8 tasks per call. Children run in the background, up to 4 at a time.
Real Pi sessions. Children get your AGENTS.md, skills, extensions, settings and MCP tools. Approval prompts from your policy extensions appear on the main screen, tagged with the child's name.
Parallel work in worktrees. Worker agents run in their own worktree, so pi-crews does not change your checkout, index or HEAD. If files in your checkout change during a worker's run, its result lists them (ignored files are not checked).
Review loop. Reviewers enter a worker's worktree with target, so they check the real change.
Two-way talk. Children can notify or ask the parent. The parent answers with send_agent and the same conversation continues.
Time budgets. Every run has a work-time budget. Waiting for approvals or answers is not counted.
Live TUI. A panel under the input box shows each child. Open any child's full conversation with Enter.
Crew settings screen. /crew creates and edits agent definitions without touching YAML.

Requirements

Pi 1.0.4 or later (tested with 1.0.4 and 1.2.0)
Node.js 22 or later
Git
macOS or Linux

Install

pi install npm:pi-crews

Pi installs the package's dependencies for npm and Git sources, so pi install git:github.com/Oswa1d99/pi-crews works too. A local checkout is for development: Pi loads it in place and installs nothing, so run npm ci in it first. After installing, run /reload in Pi.

Quick start

The main model calls spawn_agent:

{
  "tasks": [
    { "name": "auth-scout", "agent": "scout", "task": "Find where the login token is refreshed." },
    { "name": "auth-fix", "agent": "worker", "task": "Retry when the token expires. Verify with npm test." }
  ]
}

By default the call waits until both children finish and returns each result. The worker's result includes the path of its patch. The main agent then:

Asks reviewer to check the patch with target: "auth-fix".
Applies the patch itself.
Runs the checks.

You can also use the bundled commands:

Command	What it does
`/crew-ship <change>`	Worker implements, reviewers sized to the change check it, the worker fixes, the reviewers whose findings were fixed re-check (up to 3 rounds), then the parent applies the patch and runs checks. After 3 rounds it stops and asks you what to do with what remains.
`/crew-review [focus]`	One reviewer per risk the change carries inspects your current work (default: uncommitted changes). Nothing is fixed unless you ask.
`/crew`	Open the crew screen (TUI) or print a report of all children (other modes).

Tools

For the parent agent

Tool	Purpose
`spawn_agent`	Start 1–8 named children. Waits by default, at most 10 minutes. `background: true` returns at once.
`send_agent`	Message a child. Resumes a finished or waiting child with the same conversation.
`wait_agent`	Wait for results, questions or important messages (default 30 s, max 10 min). Children keep running on timeout.
`cancel_agent`	Stop children. File changes and worktrees stay. This is not a rollback.

completed only means the run ended. It does not mean the goal was met or tests passed.

For children

Tool	Purpose
`notify_parent`	Send information. Only `important` messages wake a waiting parent.
`ask_parent`	Ask for a decision and pause until the parent answers.

Children cannot delegate further. pi-crews is not loaded in child sessions.

Agents

One Markdown file is one agent. The file name is the agent name.

---
description: Review database migrations
tools: [read, bash, grep, find, ls]
model: openrouter/z-ai/glm-5.3-flash
thinkingLevel: low
budgetMinutes: 60
---

Review the migration for data loss and locking. Run the migration tests.

The body becomes part of the child's system prompt. Lookup order (a later .md with the same name replaces an earlier one):

agents/ in this package
~/.pi/agent/agents/
.pi/agents/ in a trusted project

To change only settings, such as the model of a bundled agent, put a <name>.yml with those fields in the second or third folder. The instructions stay those of the agent beneath it.

Bundled agents:

Name	Purpose	Tools
`scout`	Answers one question about the code with file and line evidence	read-only
`worker`	Implements in a worktree, runs checks, returns a patch	read, write, bash
`reviewer`	Reports confirmed defects as P0–P2 with evidence, and lists what it could not verify. Use with `target`	read, bash
`critic`	Challenges the assumptions that could change a decision, with alternatives	read-only

Field reference, validation rules and error codes: docs/usage.md.

Applying a worker's patch

Every worktree run leaves two things:

a patch file at …/runs/<n>/changes.patch
a result commit at refs/pi-crews/<parent session id>/<child name>/<n>

git apply --check --binary <patchPath>
git apply --binary <patchPath>            # on conflict: git apply --3way --binary <patchPath>

A patch holds all of the worker's changes since its worktree was created. Apply only the latest one, or after applying an earlier one, the difference between the two result commits (details).

Documentation

Document	Content
docs/usage.md	Agent fields, worktrees, run budgets, TUI panel, `/crew` screen, storage, limits, constraints
docs/archive/ADR.md	Why pi-crews works the way it does

Limitations

Worktrees and tool lists are not an OS sandbox. write and edit refuse paths outside a child's worktree, but bash can reach any path your account can.
A worktree result lists files in your checkout that changed during the run (sourceChanges). It does not check ignored files, files inside submodules, or anything outside your checkout. It cannot tell who made a change.
Child cost shows in results, the panel and /crew. It is not added to Pi's /session total.
A worktree has no ignored files (node_modules, .env) unless the agent lists them in worktreeIncludes. Otherwise the worker installs what it needs.
/crew remove keeps a worktree that has files, staged changes, commits or a populated submodule outside its latest result, and says why. It deletes ignored files without checking them.
Only Pi processes that share ~/.pi/agent take turns on git worktree commands. A git worktree command from another program at the same moment can still fail; run it again.
Worktree children cannot start in a read-only repository.
refs/pi-crews/* is pushed by git push --mirror, not by a normal git push.

Development

npm ci
npm run check        # TypeScript
npm test             # product tests: real Pi SDK and Git, model replies are fixtures
npm run format       # Prettier (format:check only checks)
npm run benchmark    # diagnostic timings, no real model requests

npm ci runs no dependency install scripts on npm versions that support package.json#allowScripts: it denies the four packages that have them, and the binaries the tests need come from optional dependencies. On older npm, add --ignore-scripts for the same behavior.

Optional live checks (they send real requests and cost money):

PI_CREWS_LIVE_MODEL=provider/model-id npm run test:live

If your Pi already loads this checkout as a package (for example ../../pi-crews in ~/.pi/agent/settings.json), also set PI_CREWS_LIVE_INSTALLED=1; otherwise every crew tool is registered twice and Pi refuses to start. The tests then run the code that package points to, so it must point at this checkout. PI_CREWS_LIVE_CLI selects the pi CLI to run.

CI typechecks against Pi 1.2.0 and runs the product tests with Pi 1.2.0 on Ubuntu and macOS, and with Pi 1.0.4 on Node.js 22, the oldest supported pair. Recorded shell-duration rendering is checked on 1.2.0; older Pi versions retain their own rendering. A weekly run (.github/workflows/weekly.yml) adds Node.js 22 to 26, both Pi versions on macOS, the previous Ubuntu image, three runs in a row to surface flaky tests, and the benchmark. Node.js 22 applies the 30 s test timeout to each test file as a whole (Node.js 24 and later do not), so on Node.js 22 npm test warns about files that take more than two thirds of it. A scheduled job (.github/workflows/pi-compat.yml) tests each new Pi release and opens a baseline-bump PR; a failing release files an issue. Pushing a v* tag runs .github/workflows/release.yml: it repeats the CI checks, attaches the package tarball to a GitHub release, and publishes to npm when the version is not there yet. npm publishing uses trusted publishing, configured once with npm trust github pi-crews --file release.yml --repo Oswa1d99/pi-crews --allow-publish. The first release is published by hand from a clean checkout on main; npm records that commit as gitHead, and the tag must name it. The source layout and the Pi-version upgrade rule are in docs/usage.md.