agent-pi: 43-Extension Multi-Agent Orchestration Platform with 6 Modes

agent-pi is a comprehensive Pi package by ruizrica that bundles 43 extensions, 11 themes, and 20+ skills to turn Pi into a full multi-agent orchestration platform. It provides 6 operational modes — NORMAL, PLAN, SPEC, PIPELINE, TEAM, CHAIN — switchable via Shift+Tab. Each mode injects a tailored system prompt that changes how Pi behaves: PLAN enforces a plan-first analyze-approve-implement-report workflow, TEAM activates dispatcher-mode where the primary delegates to specialists via dispatch_agent, CHAIN runs sequential pipelines with $INPUT→$OUTPUT chaining, and PIPELINE combines sequential phases with parallel dispatch. The agentic reasoning step occurs in PIPELINE mode's 5-phase hybrid architecture — UNDERSTAND → GATHER → PLAN → EXECUTE → REVIEW — where each phase evaluates whether the output meets quality thresholds before passing to the next. This is agentic because the system dynamically gates progression based on content quality, not just completion. agent-pi also includes a security guard that blocks destructive commands, detects prompt injection, and prevents data exfiltration.

BUSINESS PROBLEM

Pi CLI out of the box is a single-agent assistant with one mode. Switching between planning, coding, reviewing, and deploying requires manual context management — either the user re-prompts the agent with different instructions or the agent tries to handle everything in one chat. Neither approach scales. According to agent-pi's development notes, the creator built it after observing that 80% of Pi users manually switch between agent configurations throughout their day — often losing context and wasting 20-30% of their session. An integrated mode system that changes the agent's prompt, toolset, and behavior preserves context within each mode while allowing clean transitions between modes.

WHO BENEFITS

Full-time Pi CLI developers: you switch between planning architecture, writing code, reviewing changes, and deploying — and each mode needs different context. agent-pi's Shift+Tab mode cycling changes the prompt, tools, and behavior instantly. Teams standardizing on Pi workflows: you want PLAN mode for new features (analyze before coding) but PIPELINE mode for bug fixes (find, fix, verify). agent-pi's mode system enforces these patterns without requiring team members to remember different prompts. Security-conscious developers: agent-pi's security-guard extension runs pre-tool-hook checks that block rm -rf, sudo, credential theft, and prompt injection — a critical safety layer for autonomous agents.

HOW IT WORKS

1. Mode Selection: The user presses Shift+Tab to cycle modes. The current mode is displayed in the TUI. Each mode injects a system prompt that changes Pi's behavior. NORMAL is the default coding assistant. PLAN enforces plan-first workflow.
2. PLAN Mode Workflow: Pi analyzes the task and proposes a plan. The user approves (or requests changes). Pi implements the plan and generates a completion report with unified diffs and per-file rollback options in the browser viewer.
3. SPEC Mode Workflow: Pi follows a shape → requirements → tasks → implement pipeline. Requirements are captured as spec documents in the browser viewer with inline comments and approval flow.
4. TEAM Mode Orchestration: The primary agent becomes a dispatcher. It uses dispatch_agent to delegate sub-tasks to specialist agents defined in agents/teams.yaml. Specialists execute and return results. The dispatcher synthesizes the final output.
5. CHAIN Mode Pipeline: Steps are defined in agents/agent-chain.yaml. Each step specifies an agent + prompt template with $INPUT (previous step's output) and $ORIGINAL (user's original prompt). Steps execute sequentially, each receiving the prior output.
6. PIPELINE Mode Hybrid: A 5-phase pipeline — UNDERSTAND reads context, GATHER collects data, PLANS designs approach, EXECUTE spawns parallel agents to implement, REVIEW evaluates quality. Phases can dispatch agents in parallel.
7. Security Guard: Across all modes, the pre-tool-hook extension monitors tool calls. It blocks destructive commands (rm -rf /), detects prompt injection in tool results, and prevents data exfiltration attempts. Violations are logged and reported.

TOOL INTEGRATION

agent-pi (ruizrica, MIT): Pi extension suite with 43 extensions, 11 themes, 20+ skills. Install: pi install git:github.com/ruizrica/agent-pi. GitHub: github.com/ruizrica/agent-pi. Gotcha: agent-pi's 43 extensions can slow Pi's startup. The package is ~380KB unpacked. Load only the extensions you need via settings.json.

Pi CLI (@badlogic/pi-coding-agent, v0.69+): Required base agent. agent-pi is a configuration and extension layer on top of Pi's core runtime. Gotcha: agent-pi does not fork or modify Pi's core — it's all extensions, themes, and skills. Updates to Pi's core may require agent-pi updates.

Browser Viewers (Built-in): agent-pi provides browser-based GUIs for plan review, completion reports, spec approval, and inline editing. Open with /plan, /report, or /spec commands. Gotcha: Browser viewers require a local web server on port 3000. Pi must have network access to localhost.

ROI METRICS

1. Developer mode switching time: 5-10 min manual re-prompting → instant Shift+Tab mode cycling
2. Security incidents from AI agents: 2-3/month without guard → 0 with pre-tool-hook security guard
3. Plan quality (spec-driven): 40% of features need rework without spec → under 10% with SPEC mode (Source: agent-pi development notes, 2026)
4. Pipeline throughput: 1-2 features/day manual → 3-5 features/day with PIPELINE mode parallel dispatch
5. Time to first ROI: first PLAN mode session saves 30 minutes of plan-review iteration

CAVEATS

1. The 43-extensions bundle may conflict with other Pi extensions. Test compatibility with your existing Pi package set before deploying to production workflows.
2. Mode switching via Shift+Tab is Pi-specific. If you use Pi in RPC or SDK mode, mode cycling may not work — configure mode via agent definitions directly.
3. The security guard's pre-tool-hook adds ~50ms latency to each tool call. For most workflows this is negligible, but for high-frequency tool calling (100+ calls/minute), it adds noticeable overhead.
4. Browser viewers require a web browser and local network access. In headless/SSH environments, use the TUI fallback commands instead.