agent-pi Guide: Turn Pi CLI into a Multi-Agent Platform with 43 Extensions

agent-pi is the most comprehensive Pi extension suite available — 43 extensions, 11 themes, and 20+ skills that transform Pi from a single-agent assistant into a full multi-agent orchestration platform with 6 operational modes. Press Shift+Tab to cycle between NORMAL (standard assistant), PLAN (analyze→approve→implement→report), SPEC (shape→requirements→tasks→implement), TEAM (dispatcher delegates to specialists), CHAIN (sequential pipeline with $INPUT→$OUTPUT), and PIPELINE (5-phase hybrid with parallel dispatch). It also includes a security-guard extension that blocks destructive commands, detects prompt injection, and prevents data exfiltration. (Source: github.com/ruizrica/agent-pi)

The Real Problem

Pi CLI out of the box is single-mode. Switching between planning, coding, and reviewing requires manual re-prompting or context manipulation. According to agent-pi's development analysis, 80% of Pi users manually switch between agent configurations throughout their day — losing context and wasting 20-30% of their session. An integrated mode system preserves context within each mode while enabling clean transitions.

[ STAT ] 80% of Pi users manually switch agent configurations throughout their day, wasting 20-30% of session time. — agent-pi development analysis, June 2026

What This Workflow Actually Does

agent-pi adds 6 operational modes that change Pi's system prompt, toolset, and behavior. Each mode has a tailored workflow optimized for a specific phase of development.

[TOOL: Mode Cycler] Shift+Tab cycles modes. Each mode injects a different system prompt. PLAN enforces plan-first, TEAM activates dispatcher mode.

[TOOL: Security Guard] Pre-tool-hook extension. Blocks rm -rf, sudo, credential theft, prompt injection. Runs before every tool call.

[TOOL: Browser Viewers] Plan review, completion reports, spec approval with inline comments. Open via /plan, /report, /spec commands.

Who This Is Built For

For full-time Pi CLI developers: switch between planning, coding, reviewing, and deploying with Shift+Tab. Each mode has the right prompt and tools.

For teams standardizing on Pi workflows: PLAN mode for features (analyze before coding), PIPELINE for bug fixes (find→fix→verify). The mode system enforces these patterns.

For security-conscious developers: the security guard runs on every tool call, blocking destructive commands and detecting prompt injection automatically.

How It Runs Step by Step

Mode Selection: Shift+Tab cycles NORMAL → PLAN → SPEC → PIPELINE → TEAM → CHAIN.
PLAN Mode: Pi analyzes the task, proposes a plan. User approves. Pi implements and generates a completion report with browser-based unified diffs.
TEAM Mode: The primary agent becomes a dispatcher, delegating sub-tasks to specialists via dispatch_agent.
CHAIN Mode: Steps execute sequentially, each receiving the prior step's $INPUT and the original $ORIGINAL prompt.
PIPELINE Mode: 5-phase hybrid — UNDERSTAND, GATHER, PLAN, EXECUTE (parallel dispatch), REVIEW.

Setup and Tools

agent-pi: pi install git:github.com/ruizrica/agent-pi. 43 extensions, 11 themes, 20+ skills. Gotcha: 43 extensions can slow startup. Load only what you need via settings.json.

Security Guard: Pre-tool-hook with three layers — tool_call hook (blocks dangerous commands), context hook (strips prompt injections), before_agent_start hook (hardens system prompt).

The Numbers

▸ Mode switching: 5-10 min manual re-prompting → instant Shift+Tab cycling ▸ Security incidents: 2-3/month without guard → 0 with pre-tool-hook guard ▸ Feature rework rate: 40% without spec → under 10% with SPEC mode ▸ Pipeline throughput: 1-2 features/day → 3-5 features/day with PIPELINE ▸ Time to first ROI: first PLAN session saves 30 minutes of iteration (Source: agent-pi docs, June 2026)

What It Cannot Do

43 extensions may conflict with other Pi packages. Test compatibility first.
Shift+Tab mode switching is TUI-only. RPC and SDK modes need manual agent config.
Security guard adds ~50ms latency per tool call — negligible for most workflows.

Start in 10 Minutes

(2 min) Install agent-pi: pi install git:github.com/ruizrica/agent-pi
(3 min) Press Shift+Tab to cycle through modes and experience each one
(5 min) Try PLAN mode: type a feature request and watch Pi follow the analyze→plan→implement→report workflow

Frequently Asked Questions

Q: do I need all 43 extensions? A: No. agent-pi is modular. Load only the extensions you need via the enabledExtensions setting in settings.json. The mode cycler, security guard, and your chosen orchestration extensions are the minimum.

Q: Can I define custom chains in CHAIN mode? A: Yes. Chains are defined in agents/agent-chain.yaml. Each step specifies an agent, a prompt template with $INPUT and $ORIGINAL placeholders, and optional model override.

Q: Does the security guard work with all tool calls? A: Yes. It intercepts every tool_call event before execution. It blocks destructive commands, detects prompt injection in tool results, and prevents data exfiltration attempts.