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.