pi-agents-team: Background RPC Worker Agents with Dashboard Monitoring

pi-agents-team by KristjanPikhof is a Pi extension that turns one Pi coding session into a multi-agent team with background RPC worker agents. One Pi session acts as the orchestrator while background RPC workers do the actual work — the orchestrator never sees worker transcripts, only compact summaries and a single structured output block per worker. The agentic reasoning step occurs when the orchestrator evaluates worker results and decides whether to accept, request revision, or restart the work — it uses a structured delegate_task tool that specifies the role, task, tools, and output contract, then waits for agents with wait_for_agents (zero-token wait). This is agentic because the orchestrator actively manages worker lifecycle without loading their full contexts into its own session. pi-agents-team includes 7 built-in roles (explorer, fixer, reviewer, librarian, observer, oracle, designer) with configurable frontmatter-based definitions, and provides a keyboard-first dashboard overlay for monitoring worker status, token usage, and output.

BUSINESS PROBLEM

Pi CLI sessions get bloated when the orchestrator must track every detail of subagent work. A code review that spawns 4 subagents — security scan, architecture review, test audit, style check — would normally require each subagent's full transcript to return to the orchestrator. This pollutes the orchestrator's context window with irrelevant detail. According to pi-agents-team's architecture documentation, orchestrator context pollution is the primary failure mode for multi-agent Pi sessions — the orchestrator's context fills with subagent output until it can no longer effectively make decisions. The solution is strict context isolation: workers return compact summaries and a structured deliverable block. The orchestrator never sees the worker's reasoning, tool calls, or intermediate steps.

WHO BENEFITS

Pi CLI developers running complex code reviews: you need 4 agents analyzing different aspects of a PR but don't want the analysis transcripts filling your main session. pi-agents-team's compact summaries keep the orchestrator clean. Developers who multitask: you want to start a background agent working on a long task while you continue working in the main session. pi-agents-team's async RPC workers run detached — you can switch sessions and come back to results. Engineering leads monitoring team-wide Pi usage: the dashboard overlay shows all active workers, their status, token usage, and output — giving you observability into what agents are doing without reading their transcripts.

HOW IT WORKS

1. Orchestrator Setup: The user starts a Pi session and loads pi-agents-team. The extension registers delegate_task, wait_for_agents, and agent_result tools. The orchestrator decides whether to handle tasks directly or delegate to background workers.
2. Worker Delegation: The orchestrator calls delegate_task with: role (e.g., reviewer), task description, tool access (read-only or full), skills (optional Pi skills to load), and output contract (what the final deliverable should look like). The runtime spawns pi --mode rpc --no-session as a background process.
3. Background Execution: The worker runs in its own RPC session with its own context window. It has access to the tools and skills granted by the orchestrator. The orchestrator sees none of the worker's intermediate steps — only status updates (running, idle, needs_input, completed, error).
4. Orchestrator Continuation: While workers run, the orchestrator continues handling other tasks. It can spawn additional workers, answer user questions, or work on independent code changes. Workers are fully detached.
5. Result Retrieval: When a worker completes, the orchestrator calls agent_result to retrieve the compact summary and structured deliverable block. The summary is typically 3-5 sentences. The deliverable is a structured output (code, analysis, report).
6. Dashboard Monitoring: The user opens /team to see the keyboard-first dashboard. It shows all workers with status indicators, token usage per worker, and a Σ aggregate cost row. Workers can be inspected, steered, or cancelled from the dashboard.
7. Worker Steering: If a worker needs mid-course correction (identified via dashboard inspection), the orchestrator sends a steering message via /agent-steer. The worker receives the message as a follow-up prompt in its own session.

TOOL INTEGRATION

pi-agents-team (KristjanPikhof, MIT): Background RPC worker agents for Pi CLI. Install: pi install git:github.com/KristjanPikhof/pi-agents-team. 7 built-in roles, keyboard-first dashboard, async background execution. GitHub: github.com/KristjanPikhof/pi-agents-team. Gotcha: pi-agents-team requires Pi >=0.69.0 and Node >=20. The extension uses RPC mode extensively — ensure your terminal supports persistent child processes.

Pi CLI (@badlogic/pi-coding-agent, v0.69+): Host agent with RPC mode support. pi-agents-team spawns workers via pi --mode rpc. Gotcha: RPC workers are spawned with --no-session by default. If a worker crashes, no session state is recoverable.

Config File (agents-team.json): Configuration for worker roles, tool access, and defaults. Managed via /team-init (scaffold), /team-enable, and /team-disable commands. Available at both global (~/.pi/agent/) and project levels. Gotcha: Project config FULLY replaces global config — nothing merges. If you want both, manually copy global settings into the project config.

ROI METRICS

1. Orchestrator context pollution: 60-80% of context filled with subagent output → 0% (orchestrator only sees compact summaries) (Source: pi-agents-team architecture docs, 2026)
2. Parallel background task throughput: 1 sequential task → 5+ async background workers
3. Dashboard monitoring time: 10-15 min reading transcripts → 30 seconds scanning dashboard
4. Worker token cost visibility: zero visibility → per-worker and aggregate cost tracking
5. Time to first ROI: first background review agent runs without blocking the main session — reclaim 30+ minutes of waiting time

CAVEATS

1. RPC workers are spawned with --no-session — if a worker crashes mid-task, all work is lost. For critical tasks, break the work into smaller, checkpointed units.
2. Project config fully replaces global config — there is no merge logic. If you manage both, keep a source-of-truth config and manually sync changes.
3. The dashboard overlay is keyboard-first and terminal-native. It does not support mouse interaction. All operations use keyboard shortcuts (r to re-ping, y to copy).
4. pi-agents-team extends Pi's tool surface significantly. Other extensions that also register delegate_task or wait_for_agents tools will conflict. Check compatibility with your installed extensions.