pi-multiagent Guide: Run Multi-Agent Teams in Pi CLI with Isolated Contexts

pi-multiagent Guide: Run Multi-Agent Teams in Pi CLI with Isolated Contexts

pi-multiagent is the first native Pi extension for isolated same-session multiagent delegation. It adds a single agent_team tool that lets your Pi assistant spawn short-lived helper agents — scouts, web-researchers, planners, critics, reviewers, validators, workers, and synthesizers — each running in a fully isolated Pi process with explicit tool authority. The parent assistant stays the lead: it designs the team, grants tool access, retrieves evidence, and makes the final judgment. Child output is evidence, not instructions. The result is a Pi session that can decompose any complex task into parallel specialist lanes without context pollution. (Source: github.com/Tiziano-AI/pi-multiagent)

The Real Problem

Pi CLI sessions accumulate context with every turn. By turn 20-30, the model has forgotten what it read at turn 5. By turn 50, it's repeating tool calls and losing track of the original goal. According to the Pi extension ecosystem analysis (June 2026), 78% of failed multi-turn Pi sessions fail due to context saturation rather than model capability limits. The fix is simple in theory: isolate each cognitive task in its own context window. pi-multiagent makes this possible in practice.

[ STAT ] 78% of failed multi-turn Pi sessions fail due to context saturation, not model limits. — Pi Ecosystem Analysis, June 2026

What This Workflow Actually Does

pi-multiagent lets the Pi assistant compose a team of specialist agents using a static DAG graph. Each child process runs independently with its own context, tools, and authority level. The parent sees only the evidence it needs.

[TOOL: agent_team] The core tool with two modes: catalog (discover available specialists) and start (validate and launch a DAG graph). Actions include catalog, start, run_status, peek, message, cancel, and cleanup.

[TOOL: package:scout] Read-only catalog agent for filesystem discovery. Uses read, grep, find, ls. Best for mapping architecture before making changes.

[TOOL: package:reviewer] Read-only catalog agent for code review. Evaluates diffs against quality rubrics and produces structured findings.

Who This Is Built For

For Pi CLI power users running 30-50 turn sessions: the model loses track by turn 20. Delegate research and review to isolated child agents and keep the main session focused on decisions.

For open-source maintainers using Pi for codebase maintenance: pi-multiagent's catalog agents handle code review, documentation audit, and release readiness checks as isolated tasks.

For teams adopting Pi in CI/CD pipelines: agent_team can be called programmatically from n8n or bash scripts as part of automated review workflows.

How It Runs Step by Step

1. Catalog Discovery: Call agent_team with action catalog. pi-multiagent returns all available specialists with their tool profiles and model allocations.

2. Graph Design: Write a static DAG graph — inline or as graphFile JSON. Each node specifies agent ref, task, tool authority, and upstream dependencies.

3. Team Launch: Call agent_team start with the graph. Children spawn as detached Pi RPC processes. Each begins working within its authority boundary.

4. Parallel Execution: The scout reads files. The web-researcher gathers docs. The planner designs approach. Each has isolated context and zero visibility into other children.

5. Evidence Retrieval: Call run_status with waitSeconds to wait for terminal events. Retrieve only the evidence you need — not the full child transcript.

6. Human-Gated Synthesis: Evaluate child evidence and make decisions. For mutation tasks, a human-approval step pauses until the user confirms.

Setup and Tools

pi-multiagent v0.6.1: pi install npm:pi-multiagent. Zero runtime dependencies. 1.2K weekly downloads. Gotcha: children do NOT inherit parent context. Put all needed instructions in the child's task prompt.

Pi CLI v0.74+: npm install -g @badlogic/pi-coding-agent. Gotcha: pi-multiagent requires Pi v0.69+ for the extension API. Verify your Pi version before installing.

The Numbers

▸ Context saturation failures: 78% of long sessions → under 10% with child isolation ▸ Research throughput: 2-3 sources/turn sequential → 8-12 sources with parallel team ▸ Parent prompt cache hits: baseline → 3-4x more (children don't pollute parent context) ▸ Session cost for complex reviews: $2-5 without delegation → $0.50-1.50 with isolation ▸ Time to first ROI: first multi-agent delegation saves 30+ minutes of context management (Source: pi-multiagent docs, June 2026)

What It Cannot Do

1. Child processes cannot access parent session state. All required context must be in the task prompt.
2. pi-multiagent is not crash-resumable. If the parent session crashes, all child runs are lost.
3. Graph authority is binary per category. Cannot grant read-only for src/ and write for tests/ at the graph level.

Start in 10 Minutes

1. (2 min) Install pi-multiagent: pi install npm:pi-multiagent
2. (3 min) View available catalog agents: call agent_team with action catalog
3. (5 min) Run the single-specialist-read-only example graph for a quick team test

Frequently Asked Questions

Q: How is pi-multiagent different from Pi's built-in subagent tool? A: pi-multiagent provides static DAG graphs, explicit authority boundaries, catalog-based agent discovery, and compact pushed notices — the built-in subagent tool is simpler but lacks DAG support, authority isolation, and detached run management. (Source: pi-multiagent README, June 2026)

Q: Can children use Pi skills and extensions? A: Children do not inherit parent skills, extensions, prompt templates, themes, or project SYSTEM.md. Skill propagation is product-configured all-or-nothing via --agent-team-subagent-skills flag.

Q: What authority levels can I grant to child agents? A: Four levels: allowFilesystemRead (read/grep/find/ls), allowShellTools (bash), allowMutationTools (edit/write), allowExtensionCode (explicit extension tool grants). Default denies everything.

Q: How do I monitor running child agents? A: Use run_status for compact snapshots, peek to inspect one step's artifacts, and pushed notices for milestone/terminal events. The agent_team:live widget shows progress in the Pi TUI.

Q: What happens when a child agent times out? A: Per-step timeout defaults to 7200 seconds. Configure timeoutSecondsPerStep in the graph. Timed-out steps are reported as terminal failures in run_status.