pi-teams

Project-local Pi extension for persistent, communicating specialist teams. A team session is owned by one parent Pi session and contains one child Pi conversation per assigned member.

When to use it

Use pi-teams when a task benefits from explicit ownership, dependency ordering, independent testing/review, inspectable handoffs, or later reuse. A single subagent is usually faster and cheaper for a small isolated task.

Good fits:

• feature work with design → tests → implementation → review
• risky correctness, security, or data-migration changes
• parallel independent research feeding one implementation owner
• follow-up revisions that should retain specialist context

Avoid it for one-file trivial edits or when several agents would concurrently edit the same production files.

Install

From npm:

pi install npm:@aggarwal0897/pi-teams

Or try it for one Pi process:

pi -e npm:@aggarwal0897/pi-teams

Team definitions remain project-specific under .pi/teams/<team>/. After creating or changing a team definition, run /reload. For local development, Pi auto-discovers .pi/extensions/pi-teams/index.ts.

Recommended prompt

Give the main Pi agent the shared goal, acceptance criteria, ownership, and true dependencies. Let it call team_start; do not ask every member to solve the whole problem.

Copy and adapt this:

Use pi-teams with the development team for this task.

Shared goal:
<one concrete outcome>

Acceptance criteria:
- <observable requirement>
- <observable requirement>
- <exact verification command, if known>

Create one new saved, reusable team session in the background.
Assign:
- architect: inspect the current design and return the smallest implementation
  contract; do not edit files.
- tester: create or update focused tests from the agreed contract; depend on
  architect if requirements need interpretation.
- implementer: own all production edits and make the tests pass; depend on
  architect and tester.
- reviewer: independently inspect the final diff and run verification; depend
  on implementer. Request a revision only for a material defect.

Keep each assignment narrow, name allowed paths, avoid duplicate production
file ownership, and report the team session ID. Do not duplicate the team's
work in the main agent.

Faster parallel variant

Architect and tester may start together only when the contract is already precise. Put the exact same units, error behavior, paths, and edge cases in the shared goal or both assignments. Otherwise make tester depend on architect; parallel ambiguity can produce conflicting tests and correctly block the team.

Use pi-teams/development. The specification below is authoritative and needs no
interpretation: <precise specification>.
Run architect and tester in parallel, implementer after both, and reviewer after
implementer. Only implementer owns production files. Save the session and run
in the background.

Reuse an existing team session

Reuse team session <team-session-id> with team_continue.
Give architect/tester/implementer/reviewer these related follow-up assignments:
<assignments and dependencies>.
Do not create a new team session.

Reuse works only when the original session used save: true, ephemeral: false, and the current Pi session owns it.

One-off inspectable session

Use pi-teams for this one-off task with save: true and ephemeral: true.
I want persisted transcripts and statistics, but the session must not be
reusable.

Use save: false instead when no team state or child JSONL should be written. That session exists only until the current extension process ends.

Tool flow

Tool	Purpose
team_start	Always creates a new team session
team_status	Returns current member status and dependency waits
team_result	Optionally waits and returns structured results
team_continue	Reuses a saved, non-ephemeral session
team_steer	Sends guidance to one running member
team_close	Parks, archives, or deletes a session

Minimal direct call:

{
  "team": "development",
  "goal": "Add and verify a strict parser",
  "assignments": [
    { "member": "architect", "task": "Define the minimal contract; do not edit." },
    { "member": "tester", "task": "Write focused tests from the contract.", "depends_on": ["architect"] },
    { "member": "implementer", "task": "Implement and run the tests.", "depends_on": ["architect", "tester"] },
    { "member": "reviewer", "task": "Review the final behavior and rerun tests.", "depends_on": ["implementer"] }
  ],
  "background": true,
  "save": true,
  "ephemeral": false
}

Dependency-ready members run concurrently. A dependent member receives its completed dependencies' summaries and handoffs in its task prompt.

Monitoring

While a team is running, the fleet is displayed below the editor:

1. Empty the main prompt.
2. Press ↓ or ← to activate the fleet.
3. Use ↑/↓ and press Enter on a member.
4. Scroll with ↑/↓, j/k, PgUp/PgDn, Home, or End.
5. Press Enter inside a running conversation to steer it.
6. Press Esc or q to return.

Commands:

/teams
/teams <team-session-id>
/team-stats

/teams also opens completed persisted conversations after the live fleet has disappeared.

Team definitions

Definitions are project-specific:

.pi/teams/<team>/
├── team.json
├── members/
│   ├── architect.md
│   ├── tester.md
│   ├── implementer.md
│   └── reviewer.md
└── memory/

Member Markdown frontmatter supports:

• name, display_name, role, description
• tools: allowed built-in tools
• skills: exact Pi skill names, or none
• model, thinking
• memory: shared project-memory access
• max_turns: per-assignment hard limit
• can_request_revisions: authorize targeted revision requests

Keep one production owner. Give reviewers can_request_revisions: true; normal informational messages never reopen completed work.

Storage and ownership

.pi/teams/
├── <team>/
│   ├── team.json
│   ├── members/
│   └── memory/
└── session/<team-session-id>/
    ├── state.json
    ├── architect.jsonl
    ├── tester.jsonl
    ├── implementer.jsonl
    └── reviewer.jsonl

state.json records the owning parent Pi session ID. Resume that same Pi session with /resume to restore its team sessions. Another Pi session receives an ownership error and cannot attach.

Options	Disk	Reusable
save: true, ephemeral: false	yes	yes
save: true, ephemeral: true	yes	no
save: false	no	no

Project memory is shared across parent sessions under .pi/teams/<team>/memory/. Store durable decisions and conventions there, not secrets or transient progress.

Legacy .pi/teams/runs/ data is ignored and retained to avoid data loss.

Prompting rules that matter

1. Put universal requirements in the shared goal.
2. Give each member one deliverable and one owner role.
3. Use dependencies for information that must be agreed before later work.
4. Parallelize only genuinely independent work.
5. Name exact paths and verification commands.
6. State who may edit production code versus tests.
7. Ask the reviewer for observable evidence, not a generic approval.
8. Reuse a session only for closely related follow-up work.
9. Use an ephemeral session for benchmarks and disposable experiments.
10. Do not over-team trivial work; role overhead costs tokens and time.

Verification

node --experimental-strip-types --test .pi/extensions/pi-teams/*.test.ts
pi -e ./.pi/extensions/pi-teams/index.ts --list-models