Pi Agent Teams

Overview

A Pi extension that brings multi-agent coordination to Pi. Spawn teammates, share a task list, and let agents work in parallel — each in its own session, optionally its own git worktree.

The design follows the same primitives as Claude Code agent teams: a shared task list, mailbox messaging, and a leader that orchestrates workers. But it adds git worktree isolation, session branching (clone the leader's context into a teammate), dependency tracking between tasks, quality-gate hooks, and an interactive terminal panel for watching everything in real time.

Quick start

The fastest way:

/swarm build the auth module

The agent spawns a team and coordinates the work. Or drive it manually:

/team spawn alice
/team spawn bob branch worktree        # clone leader context + isolated git worktree

/team task add alice: Fix failing tests
/team task add Refactor auth module    # unassigned — auto-claimed by next idle teammate

/team dm alice Check the edge cases too
/team broadcast Wrapping up soon

/tw                                    # open the interactive widget panel

/team done                             # end run: stop teammates + hide widget

Or let the model drive it entirely through tool calls — no slash commands needed:

{
  "action": "delegate",
  "contextMode": "branch",
  "workspaceMode": "worktree",
  "teammates": ["alice", "bob"],
  "tasks": [
    { "text": "Fix failing unit tests" },
    { "text": "Refactor auth module" }
  ]
}

Features

• Shared task list — file-per-task on disk with pending / in-progress / completed states and dependency tracking. Blocked tasks stay blocked until prerequisites finish.
• Auto-claim — idle teammates automatically pick up the next unassigned, unblocked task.
• Messaging — direct messages, broadcast, and urgent interrupts that steer an active turn.
• Git worktrees — optionally give each teammate its own worktree so they work on isolated branches without conflicting edits.
• Session branching — clone the leader's full conversation context into a teammate so it starts with awareness of the work so far.
• Quality-gate hooks — optional scripts that run on task completion. Failures can auto-reopen tasks, create follow-up remediation tasks, or both.
• Interactive panel (/tw) — real-time view of all workers with transcript scrolling, task management, stall detection, and inline message composition.

Styles

The extension ships with three UI styles:

• normal (default): "Team leader" + "Teammate"
• soviet: "Chairman" + "Comrade"
• pirate: "Captain" + "Matey"

You can create custom styles as JSON files — override terminology, lifecycle copy, and auto-naming pools.

The panel

The interactive panel (/tw) is the main way to watch a team run. It shows:

• Per-worker status with time-in-state and stall detection
• Last assistant message summary
• Current tool activity (e.g. editing…, running…)
• Task list with dependency graph

Keyboard shortcuts: ↑/↓ to select workers, enter for transcript, t for task view, m to message, k to kill, c/p/i to change task status.

Installation

pi install npm:@tmustier/pi-agent-teams

Why?

I use Clean Slides to generate consulting-style decks. One of the first things I tried was having the agent clone itself — one clone per slide page, the original focusing on consistency and quality review. It worked well enough that I built proper infrastructure around the pattern.

The model is a team lead who can create copies of itself, give each one a task, watch progress, and intervene when needed. The constraint is that teammates can only communicate through the task list and mailbox — there's no shared memory or implicit coordination. That turns out to be a feature: it forces the work to be decomposed into discrete units that can be reasoned about independently.