🤝 pi-agentteam

Multi-agent team orchestration for pi

Coordinate a leader with specialized teammates — researcher, planner, and implementer — each running in a visible tmux pane, collaborating through shared tasks and typed messages.

---

✨ Highlights

	Feature
🖥️	tmux-native teamwork	Each teammate is a real pi session in its own pane — watch them work in real time
📋	Shared task board	Create, claim, update, complete — full lifecycle tracking across the team
💬	Typed messaging	assignment · question · blocked · completion_report · fyi — each with auto-wake semantics
🎯	Role-based tool guard	Researcher/Planner (read-only) → Implementer (full tools) — least privilege by default
📡	Event-driven wake	Teammates auto-wake on actionable messages; no polling, no wasted tokens
📊	Unified /team console	Browse state, recover old teams, remove stale teammates, and cleanup without memorizing extra commands
🔗	Peer handoff	Workers coordinate directly (researcher → planner) without going through the leader
🧹	Zero footprint	One folder, file-based state, no database — delete and it's gone

---

📦 Install

pi install npm:pi-agentteam

Requirements: pi ≥ 0.60 · tmux. The leader pi session must run inside tmux.

---

🚀 Quick Start

You (leader):
  Create a team and spawn a researcher to analyze the build pipeline.

  > agentteam_create({ team_name: "my-project", description: "Optimize the build pipeline" })
  > agentteam_spawn({ name: "research", role: "researcher",
                      task: "Analyze the build pipeline and report bottlenecks" })
  > agentteam_spawn({ name: "plan", role: "planner" })

  ... researcher works in its own tmux pane ...

  > agentteam_send({ to: "plan", message: "Research done, draft an optimization plan",
                     type: "fyi" })

  ... planner drafts plan ...

  > agentteam_receive()   ← pick up completion_report from planner

Or open the unified local console:

/team          ← local console for status, recovery, and cleanup

---

🎮 /team Console

/team is the only slash command exposed by agentteam. It opens a local console instead of a pile of maintenance commands.

Attached to a team:

/team
→ Members · Tasks · Mailbox · Details
→ select an item
→ Enter opens contextual actions

Not attached to a team:

/team
→ AgentTeam Console
→ list saved teams and stale panes
→ recover an old team as current leader, delete a team, or cleanup all agentteam state

Key	Action
Tab	Cycle sections
↑ ↓	Move selection
Enter	Open action menu / choose action
Esc	Step back / close

The panel intentionally does not focus tmux panes or perform task/message CRUD. Use tmux for pane navigation, and use tools for collaboration work. /team is for local runtime visibility, recovery, and cleanup. Expanded Details use an internal reader so long notes/messages remain readable without flooding terminal scrollback.

Available action-menu operations include:

• refresh/reconcile tmux pane bindings;
• sync leader mailbox projection without marking messages read;
• remove selected teammate;
• delete selected/current team;
• recover an existing team as the current leader;
• cleanup all agentteam state and stale panes while keeping the current pane alive and clearing its agentteam label.

---

💬 Messages & Wake Behavior

Messages carry an implicit wake hint that controls how the recipient reacts. Mailbox lifecycle is created → delivered → read: wake marks messages as delivered, while only agentteam_receive marks them read.

Type	Purpose	Wake	Typical Flow
assignment	Leader → worker task assignment	hard	Leader delegates work
question	Clarification request	soft	Anyone asks a question
blocked	Escalation needing attention	hard	Worker hits a wall
completion_report	Work finished	hard (leader) · soft (teammate)	Worker reports back
fyi	Informational update	none*	Context sharing

* Peer handoff exception: when a non-leader sends fyi to an idle teammate, wake is auto-upgraded to soft so the handoff doesn't stall silently.

Peer completion_report and blocked messages are also mirrored to team-lead so the leader can always converge completed work and blockers.

---

👥 Built-in Roles

agentteam intentionally keeps a small fixed role set for predictable permissions and prompts.

🔬 researcher — read grep find ls + collab

Fact finding: relevant files, constraints, risks, and evidence-backed findings

📋 planner — read grep find ls + collab

Advisory planning for complex work: options, risks, dependencies, and acceptance criteria

🛠 implementer — read grep find ls bash edit write + collab

Focused code changes, checks, and validation evidence

collab = agentteam_send + agentteam_receive + agentteam_task

---

⚙️ Model Configuration

Create ~/.pi/agent/agentteam/config.json to assign models per role:

{
  "agentModels": {
    "planner": "glm-5.1",
    "researcher": "glm-5.1",
    "implementer": "gpt-5.3-codex"
  }
}

Values are model selectors from ~/.pi/agent/models.json. Empty string or missing key = use the default model. The leader always uses your current session model.

Runtime state is stored under ~/.pi/agent/agentteam/ (teams/, mailboxes/, session-bindings, and worker-sessions). config.json lives in the same directory. Set PI_AGENTTEAM_HOME only for testing or temporary sandboxes.

---

🛠 Tools & Commands

Tools

Tool	Description
agentteam_create	Create a new team
agentteam_spawn	Spawn a teammate (omit task for idle)
agentteam_send	Send a typed message
agentteam_receive	Pull unread mailbox messages
agentteam_task	Manage shared tasks (create · claim · update · complete · list · note)

Command

Command	Description
/team	Unified local console for status, recovery, teammate removal, team deletion, and cleanup

---

🏗 Architecture

index.ts              ← Extension entry point
├── tools/            ← Thin tool registrations plus team/message/task/worker services & policy helpers
├── commands/         ← /team console command and runtime action handlers
├── hooks/            ← Thin hook registrations plus lifecycle/context services and tool guard
├── teamPanel/        ← Interactive console (layout, view model, input, actions)
├── state.ts          ← State facade
├── state/            ← File-based stores (team, mailbox, bindings, merge policy)
├── runtime.ts        ← Runtime facade (session helpers, team lookup, leader mailbox projection)
├── runtimeRules.ts   ← Pure naming, owner, and spawn-task classification rules
├── runtimeWake.ts    ← Worker/leader wake prompts and wake status updates
├── runtimePanes.ts   ← Pane reconciliation and team pane cleanup
├── runtimeStorage.ts ← Team storage/mailbox readiness cache
├── runtimeService.ts ← Leader mailbox sync, digest injection
├── protocol.ts       ← Message type defaults & wake hints
├── orchestration.ts  ← Leader digest (coordination counters)
├── policy.ts         ← Leader delegation policy
├── agents.ts         ← Role discovery & agent loading
├── tmux.ts           ← tmux facade
├── tmux/             ← tmux client, pane/window/wake/label helpers
├── messageLifecycle.ts ← Mailbox created/delivered/read helpers
├── types.ts          ← Shared type definitions
└── agents/           ← Bundled role prompts (markdown)
    ├── researcher.md
    ├── planner.md
    └── implementer.md

Design Principles

• Removable — delete the folder and reload; no core modifications
• Observable — each teammate is a visible tmux pane you can watch
• Minimal prompt burden — role behavior in markdown, not inflated system prompts
• File-based state — JSON + lock files + atomic writes; no database
• Event-driven — teammates wake on actionable messages, not polling

---

✅ Tests

npm test
npm run test:e2e   # optional local tmux smoke; requires tmux

Suite	Covers
Tools + state flow	create → spawn → send → receive → task lifecycle
Command	/team unified console
Protocol + orchestration	Wake defaults, leader digest injection
Panel rendering	Visual output across terminal widths
Wake + permission guards	Role-based access control
Service unit helpers	Pure worker/message/task/context helper behavior

---

⚠️ Limitations

• Workers are separate pi sessions in tmux panes, not in-process subagents
• Passing task to agentteam_spawn starts work immediately; omitting it creates an idle teammate for later send/task follow-up
• State is local to one machine (no remote/distributed support)
• Requires tmux; Windows terminals not supported (WSL works)

---

📄 License

MIT © 2026 linys77