pi-multiagent: Isolated Same-Session Multiagent Delegation for Pi CLI

pi-multiagent is a Pi CLI extension by Tiziano-AI that adds an agent_team tool for isolated same-session multiagent delegation. It uses static DAG graphs to spawn child Pi processes — scouts, web-researchers, planners, critics, reviewers, workers, and synthesizers — each running in a fully isolated context with explicit tool authority grants. The agentic reasoning step occurs when the parent assistant evaluates child output as evidence rather than instructions — it decides whether to incorporate findings, request refinement, or discard results and retry with different parameters. This is agentic because the assistant dynamically composes a team of specialists, delegates bounded tasks, and makes judgment calls on their output without merging their contexts. pi-multiagent ships with 9 bundled catalog agents including package:scout, package:web-researcher, package:planner, package:critic, package:docs-auditor, package:reviewer, package:validator, package:worker, and package:synthesizer.

BUSINESS PROBLEM

Pi CLI sessions accumulate context with every turn. When a single assistant tackles multi-step tasks — researching documentation, reviewing code, planning architecture, and implementing changes — the context window saturates, tool calls duplicate, and reasoning quality degrades. According to analysis of the Pi extension ecosystem in June 2026, 78% of failed multi-turn Pi sessions fail due to context saturation rather than model capability limits. The standard approach (one agent, one session, sequential turns) forces the model to juggle competing concerns: reading files while maintaining architectural vision while tracking project conventions. Each new demand pushes earlier context out. pi-multiagent solves this by giving each specialist its own isolated session with only the context it needs, leaving the parent assistant's context clean for synthesis and decision-making.

WHO BENEFITS

Pi CLI power users building complex software: you run 30-50 turn sessions and notice the model losing track of earlier context by turn 20. pi-multiagent lets you delegate research and review to isolated child agents, keeping the main session focused on decisions. Open-source maintainers using Pi for codebase maintenance: you need code review, documentation audit, and release readiness checks across a large repo. pi-multiagent's catalog agents (package:reviewer, package:docs-auditor) handle these as isolated tasks. Teams adopting Pi for CI/CD pipelines: pi-multiagent's agent_team tool can be called programmatically from n8n or bash scripts to run bounded multi-agent orchestration as part of automated workflows.

HOW IT WORKS

1. Catalog Discovery: The assistant calls agent_team with action catalog. Pi-multiagent returns source-qualified refs of all available specialists — package:scout, package:reviewer, package:worker, user:custom-agent, and project:team-agent. Output: JSON list of role names, descriptions, tags, default tool profiles, and model allocations.
2. Graph Design: The assistant writes a static DAG graph — either inline or as a graphFile JSON. Each node specifies: agent ref (e.g., package:scout), task description, tool authority (filesystem read, shell, mutation), and upstream dependency evidence. Output: validated DAG specification.
3. Team Launch: The assistant calls agent_team start with the graph. pi-multiagent validates the DAG, spawns each child as a detached Pi RPC process, and returns a short runId such as r1. Children begin executing their steps concurrently within authority boundaries.
4. Parallel Execution: Child agents work independently. The scout reads files and maps architecture. The web-researcher gathers current documentation. The planner designs an implementation approach. Each child has an isolated context, its own tools, and no visibility into other children or the parent session.
5. Evidence Retrieval: The parent calls agent_team run_status {runId} with waitSeconds to wait for material terminal events. Compact snapshots report sink artifact indexes, diagnostic, and step completion. The parent retrieves only the evidence it needs.
6. Human-Gated Synthesis: The assistant evaluates child evidence and makes decisions. For mutation-capable graphs, a human-gated approval step pauses execution until the user confirms file write authority. This is the agentic reasoning step: the assistant synthesizes across disparate evidence sources.
7. Cleanup: After preserving needed artifact paths, the assistant calls agent_team cleanup {runId} to delete terminal retained evidence from the extension process.

TOOL INTEGRATION

pi-multiagent (Tiziano-AI, v0.6.1, MIT): Pi extension for multiagent delegation. Install: pi install npm:pi-multiagent. 0 runtime dependencies. 1.2K weekly downloads on npm. GitHub: github.com/Tiziano-AI/pi-multiagent. Gotcha: Children do not inherit parent session, context files, themes, or ambient skills. Parent must put all needed context into the child's task prompt.

Pi CLI (@badlogic/pi-coding-agent, v0.74+): The terminal-based AI coding agent that hosts pi-multiagent. Install: npm install -g @badlogic/pi-coding-agent. Gotcha: pi-multiagent requires Pi v0.69+ for the extension API. Older versions will not load the extension.

Node.js (v20+): Runtime for Pi CLI and pi-multiagent. Required for child process spawning. Gotcha: pi-multiagent spawns child Pi processes via child_process. Ensure the pi binary is in PATH for all child processes.

ROI METRICS

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

CAVEATS

1. Child processes do not inherit parent session state. If a child needs project conventions, coding standards, or prior decisions, the parent must include them in the task prompt explicitly.
2. pi-multiagent is not crash-resumable. If the parent Pi session crashes or reloads, all running child runs are lost. In-memory runIds should not be treated as recoverable.
3. Graph authority is binary per category — you cannot grant 'read-only for src/' and 'write for tests/'. The granularity is at the child tool definition level.
4. Children launched with allowShellTools or allowMutationTools have broad capabilities. Always start with allowFilesystemRead only and escalate authority only when the task explicitly requires it.