pi-team

Turn a Pi coding-agent session into a context-light team lead. You type a plain-language task like "fix the flaky auth test with a debugger, test, and review team", and pi-team spins up a small team of specialist agents in a shared git worktree, coordinates them over a peer-to-peer message bus, and hands you back a pushed branch and a PR. You stay in the lead seat — the specialists own the code, tests, and review.

pi-team ships alongside two sibling agent networks in this repo — a flat pi- specialist network and a governed IDC role network — all riding the same coms-net bus. It builds on the Pi Coding Agent.

Adapted from disler/pi-vs-claude-code (IndyDevDan, MIT — see LICENSE) as the starting point for a personal set of communication-specialized Pi agent harnesses.

Prerequisites

pi-team checks these for you (pi-team doctor / pi-team init print the exact install command when one is missing — it never installs anything for you):

| Tool | Purpose | Install | |---|---|---| | Bun | Runtime & package manager | curl -fsSL https://bun.sh/install \| bash | | Pi CLI | The coding agent pi-team drives | npm install -g @mariozechner/pi-coding-agent | | git | Worktrees + branches | xcode-select --install (macOS) |

Optional but recommended: just (brew install just) for the launcher recipes, and gh (the GitHub CLI) so /team finalize can open PRs for you.

Platform: macOS is the supported target. Linux is best-effort (the multi-window launcher fan-out is macOS-only). Windows is unsupported.

60-second quickstart

# 1. Install the pi-team CLI + Pi extension (see the from-checkout alternative below)
bun add -g pi-team-harness          # puts `pi-team` (and `pi-`) on your PATH
pi install -l npm:pi-team-harness   # registers the /team Pi extension

# 2. Prepare the repo you want a team to work in
cd ~/dev/my-app
pi-team init   # seeds .pi/team-lead.yaml + a .gitignore block

# 3. Launch Pi and start a team
pi

Then, inside Pi:

/team on "fix the flaky auth test with a debugger, test, and review team"

pi-team activates lead mode, creates a shared worktree, launches the agents, and sends each one its assignment. Watch progress with /team status, read what agents report with /team inbox, and when the work is committed and green, wrap it up:

/team finalize

/team finalize pushes the shared branch and opens a PR — it never merges, force-pushes, or deletes the worktree.

From-checkout alternative: the quickstart above installs from the published npm package. To run from a clone of this repo instead (for local development on the harness itself):

git clone https://github.com/llamallamaredpajama/pi-harnesses && cd pi-harnesses
bun install
scripts/pi-team install     # symlinks pi-team + pi-, registers the extension, adds a PATH block

After that, the on-PATH pi-team … commands work from any repo just like the registry install. The clone's registry steps map to: skip bun add -g pi-team-harness and pi install -l npm:pi-team-harness (the scripts/pi-team install above already put the commands on PATH and registered the extension); pi-team init in your target repo works the same either way.

npm name: the published package is pi-team-harness (the shorter pi-team was taken on the registry by an unrelated publisher). The commands you type stay pi-team and pi- — only the install identity differs. The package also ships a pi-team-harness bin alias for the same CLI, so the no-install form is bunx pi-team-harness <verb> (e.g. bunx pi-team-harness doctor). Never run bare bunx pi-team … — that fetches the other package.

Commands at a glance

Two surfaces: /team … inside a Pi session, and pi-team … in your shell. Full reference with examples: docs/commands.md.

In-session (/team) — type /team and press Tab for autocomplete:

| Command | Purpose | |---|---| | /team on <preset\|workflow\|task> | Start a run and launch agents | | /team status [agent] | Show run + agent status | | /team inbox [agent] | Read agents' status packets | | /team send <agent> <message> | Message one agent | | /team broadcast <message> | Message every agent | | /team add <specialist[:N]> [task] | Add more specialists | | /team resend [assignment-id\|agent\|all] | Retry a failed initial assignment | | /team refresh [agent] | Replace an agent with a fresh generation | | /team kill [agent] | Stop one agent or the whole run | | /team doctor | Team + install health | | /team catalog | List launchable specialists/roles | | /team lesson [incident\|pattern\|fix\|note] <summary> | Record a lesson | | /team models | Show model override syntax | | /team list · /team resume [run-id] | List / reload durable runs | | /team tidy [--apply] | Clean up finished worktrees | | /team finalize | Push the branch and open a PR | | /team off | Leave lead mode (agents keep running) |

Shell (pi-team) — run pi-team help for the verbatim usage:

| Command | Purpose | |---|---| | pi-team install / repair / uninstall | Manage the CLI + extension install | | pi-team doctor | Check install + prerequisite health | | pi-team init | Seed the current repo for a team run | | pi-team e2e | Run the no-LLM end-to-end test harness | | pi-team smoke | Operator-only real-agent smoke (dry-run by default) |

Something not working? Every failure line maps to a fix in docs/troubleshooting.md.

What's in the box

This repo is three agent networks on one shared message bus:

1. pi-team — the team-lead network above (extensions/pi-team/, scripts/pi-team). A context-light lead over generic specialists and governed roles.
2. pi- specialist network — a flat peer team of single-skill Pi agents (config/specialists.yaml + profiles/**), launched by scripts/pi-, guarded by specialist-guard.ts. See docs/pi-specialist-harness.md.
3. IDC role network — 7 governed roles (think → plan → sequence → ripple → build), launched by scripts/idc-pi. See docs/idc-pi-network.md.

They talk only over coms-net (scripts/coms-net-server.ts, an HTTP/SSE hub). pi-team orchestrates the other two over the same bus.

Shared extensions

These are the shared extensions the networks load (pi -e extensions/<name>.ts):

| Extension | File | Description | |---|---|---| | minimal | extensions/minimal.ts | Compact footer: model name + a 10-block context meter [###-------] 30% | | theme-cycler | extensions/theme-cycler.ts | Ctrl+X/Ctrl+Q + /theme to cycle custom themes | | coms-net | extensions/coms-net.ts | Networked Pi-to-Pi over a shared HTTP/SSE hub. Tools: coms_net_* | | dev-knowledge | extensions/dev-knowledge.ts | Read-only wiki_search / logbook_search over the local Research Wiki + Engineering Logbook | | xcode-mcp | extensions/xcode-mcp.ts | Profile-scoped Xcode MCP wrapper for pi- apple | | review-orchestrator | extensions/review-orchestrator.ts | Risk-tiered review harness for pi- review (/review-diff, /review-pr, /review-status) | | specialist-guard | extensions/specialist-guard.ts | Path/bash write-guard for the pi- network | | idc-role-harness | extensions/idc-role-harness.ts | Path/bash write-guard for the IDC role network | | pi-team | extensions/pi-team/index.ts | The /team team-lead extension |

Providing API keys

Pi does not auto-load .env — provider keys must be in your shell environment before you launch pi. Copy the template and fill it in:

cp .env.sample .env   # then edit .env with your keys
source .env && pi     # or `just pi`, which loads .env automatically

.env.sample covers OpenAI, Anthropic, Google, and OpenRouter, plus many other providers. If agents launch but never respond, missing keys are the usual cause — see troubleshooting.

Pi-to-Pi Agent-to-Agent Communication

📺 Watch: Pi to Pi: Two-Way Agent Orchestration with the Pi Coding Agent

pi-team is an orchestrator, but the bus underneath it — coms-net — is a different primitive you can use on its own: two equal Pi agents that talk to each other peer-to-peer, on the same machine or across the network. No orchestrator, no parent/child hierarchy. Prompt → response → prompt → response, between agents who are equals. That unlocks bidirectional flows a top-down hierarchy can't.

Why this matters in practice:

• Cross-device work. A production agent on one box, a dev agent on your laptop. The prod side keeps PII redacted while still answering the dev side's questions.
• Heterogeneous teams. Run claude-opus-4-7, gpt-5.5, and deepseek in the same pool — different models catch what the others miss.
• Focused context windows. Each agent stays on its slice instead of one bloated context juggling everything.

coms-net at a glance

| | coms-net | | --- | --- | | Transport | HTTP + Server-Sent Events | | Scope | Same machine, LAN, or remote URL | | Discovery | Shared hub at ~/.pi/coms-net/projects/<project>/server.json | | Server | bun scripts/coms-net-server.ts (Bun HTTP hub) | | Tools | coms_net_list, coms_net_send, coms_net_get, coms_net_await | | Auth | PI_COMS_NET_AUTH_TOKEN (auto-generated for localhost, required for LAN/remote) |

The entire surface is four tools: list peers, send a prompt, then either poll (_get, non-blocking) or block for the reply (_await). A reply travels back through the same channel — when an inbound prompt triggers a turn, the receiver's final message is packaged as the response.

Quick start — networked

# Terminal 1 — hub
just coms-net-server                # binds 127.0.0.1, OS-claimed port
just coms-net-server-lan            # binds 0.0.0.0 — requires PI_COMS_NET_AUTH_TOKEN

# Teardown / restart
just kill-all                       # SIGINT: hub exits and connected sessions exit too
just kill-server                    # SIGTERM: hub only; clients survive and reconnect

# Terminals 2 & 3 — clients (auto-discover server.json)
just coms  --name dev
just coms2 --name prod              # …pinned to claude-opus-4-7

For remote / cross-LAN: set PI_COMS_NET_SERVER_URL and PI_COMS_NET_AUTH_TOKEN in .env. Front the hub with TLS for anything beyond a trusted LAN.

Safety rails baked in

• Hop limit — every prompt envelope carries hops; default MAX_HOPS=5 (PI_COMS_NET_MAX_HOPS). Stops runaway A→B→A→B loops.
• Audit log — every send/receive appends to coms-net-log (msg_id, sender, hops only — never prompt bodies).
• Self-heal — heartbeats every 10s; peers marked stale/offline on miss.
• Localhost-by-default — the hub refuses any bind other than 127.0.0.1 unless PI_COMS_NET_AUTH_TOKEN is set.

Safety Guards

The pi- specialist and IDC role networks enforce structured path/bash write-guards (specialist-guard.ts, idc-role-harness.ts) sharing one core (guard-shell-core.ts). See docs/pi-specialist-harness.md and docs/idc-pi-network.md.

Extension Author Reference

Conventions used across every extension in this repo:

• RESERVED_KEYS.md — reserved keybindings and safe keys for extension authors.
• THEME.md — color token → UI role mapping.
• TOOLS.md — signatures for the built-in tools available inside extensions (read, bash, edit, write).

Hooks & Events

Side-by-side comparison of lifecycle hooks in Claude Code vs Pi Agent.

| Category | Claude Code | Pi Agent | In | |---|---|---|---| | Session | SessionStart, SessionEnd | session_start, session_shutdown | Both | | Input | UserPromptSubmit | input | Both | | Tool | PreToolUse, PostToolUse | tool_call, tool_result, tool_execution_* | Both | | Bash | — | BashSpawnHook, user_bash | Pi | | Compact | PreCompact | session_before_compact, session_compact | Both | | Agent / Turn | — | before_agent_start, agent_start, agent_end, turn_* | Pi | | Sub-agents | SubagentStart, SubagentStop | — | CC | | Worktree | WorktreeCreate, WorktreeRemove | — | CC |

Contributing

Work in this repo is tracker-driven. Before changing pi-team, read the pi-team V2 tracker (the source of truth for what's done vs. remaining) and CLAUDE.md / AGENTS.md for the workflow. Verify with bun test (the canonical gate) and scripts/pi-team e2e (the no-LLM harness).

Resources

| Doc | Description | |---|---| | docs/commands.md | Every /team and pi-team command, with examples | | docs/troubleshooting.md | Every failure line → its fix | | docs/pi-specialist-harness.md | The pi- specialist network | | docs/idc-pi-network.md | The IDC role network | | Pi Coding Agent docs | Upstream Pi — SDK, RPC, providers, extensions |

License

Released under the MIT License — fork it, ship it, use it however helps you build.

Master Agentic Coding

Learn tactical agentic coding patterns with Tactical Agentic Coding, and follow the IndyDevDan YouTube channel.