pi-agents-team Guide: Background RPC Worker Agents with Dashboard in Pi CLI

pi-agents-team Guide: Background RPC Worker Agents with Dashboard in Pi CLI

pi-agents-team by KristjanPikhof turns one Pi coding session into a multi-agent command center. One Pi session acts as the orchestrator while background RPC workers do the heavy lifting. The orchestrator never sees worker transcripts — only compact summaries and a single structured deliverable block per worker. The extension includes 7 built-in roles (explorer, fixer, reviewer, librarian, observer, oracle, designer), a keyboard-first dashboard overlay for monitoring, per-worker token tracking, and async background execution that survives session switches. (Source: github.com/KristjanPikhof/pi-agents-team)

The Real Problem

Pi CLI sessions bloat when the orchestrator must track every detail of subagent work. A code review spawning 4 subagents would normally require each transcript to return to the orchestrator, polluting its context 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 solution: workers return compact summaries only. The orchestrator never sees reasoning, tool calls, or intermediate steps.

[ STAT ] Orchestrator context pollution is the primary failure mode for multi-agent Pi sessions. — pi-agents-team architecture documentation, June 2026

What This Workflow Actually Does

pi-agents-team spawns background RPC workers that run in isolated sessions. The orchestrator delegates tasks via delegate_task, waits with zero-token wait_for_agents, and retrieves compact summaries.

[TOOL: delegate_task] Spawns a background RPC worker. Specify role, task, tools, skills, and output contract.

[TOOL: wait_for_agents] Zero-token wait. Wakes early on worker relay questions. Does not consume context.

[TOOL: Dashboard] Keyboard-first overlay. Shows workers with status, token usage, aggregate costs.

Who This Is Built For

For Pi CLI developers running complex code reviews: 4 agents analyze different aspects without filling the main session with transcripts.

For developers who multitask: start a background agent on a long task while continuing work in the main session.

For engineering leads monitoring Pi usage: the dashboard shows all workers, their status, token usage, and output — without reading transcripts.

How It Runs Step by Step

1. Orchestrator Setup: Load pi-agents-team. Tools delegate_task, wait_for_agents, agent_result register.

2. Worker Delegation: Call delegate_task with role, task, tool access, and output contract.

3. Background Execution: Worker runs in isolated RPC session. Orchestrator sees only status updates.

4. Orchestrator Continuation: While workers run, the orchestrator handles other tasks. Spawn more workers, answer questions, write code.

5. Result Retrieval: agent_result returns compact summary and structured deliverable block.

6. Dashboard: /team opens the overlay. Shows workers, token usage, aggregate costs.

Setup and Tools

pi-agents-team: pi install git:github.com/KristjanPikhof/pi-agents-team. 7 built-in roles, async execution. Gotcha: requires Pi >=0.69.0 and Node >=20.

Config: agents-team.json managed via /team-init, /team-enable, /team-disable. Global and project levels.

The Numbers

▸ Context pollution: 60-80% transcript bloat → 0% with compact summaries ▸ Parallel throughput: 1 sequential task → 5+ async background workers ▸ Monitoring time: 10-15 min reading transcripts → 30 seconds dashboard scan ▸ Cost visibility: zero → per-worker and aggregate tracking ▸ Time to first ROI: first background review runs without blocking main session (Source: pi-agents-team docs, June 2026)

What It Cannot Do

1. RPC workers use --no-session. Worker crashes lose all progress.
2. Project config fully replaces global config. No merge logic.
3. Dashboard is keyboard-only. No mouse interaction.

Start in 10 Minutes

1. (2 min) Install pi-agents-team: pi install git:github.com/KristjanPikhof/pi-agents-team
2. (3 min) Scaffold config: /team-init local
3. (5 min) Delegate your first task: Delegate a review task to a background worker via the orchestrator

Frequently Asked Questions

Q: Can workers use Pi skills? A: Yes. The delegate_task call accepts a skills parameter. Worker skill discovery is enabled and the worker loads the requested skills from its available context.

Q: What happens when a worker needs clarification? A: Workers enter a needs_input status. The orchestrator receives a relay question and can respond. The worker resumes once the orchestrator answers.

Q: How do I see what workers are doing? A: The /team dashboard shows all workers with status, model, turn count, and token usage. /team <workerId> opens the inspector for that worker's details.