GitHub - ruizrica/agent-pi: An extension suite that turns Pi into a multi-agent orchestration platform

An extension suite that turns Pi into a multi-agent orchestration platform - ruizrica/agent-pi

Summary

agent-pi is a Pi package that layers 43 TypeScript extensions, 11 themes, and 20+ skills on top of the Pi terminal coding agent to add multi-agent orchestration, structured operational modes, and built-in security guards. It works as pure configuration—no forks or patches of Pi itself—and ships with browser-based viewers for plans, completion reports, and specs. The project is MIT-licensed and written in TypeScript.

What it is useful for

• Engineers who want a plan-first workflow. In PLAN mode, Pi must define tasks before tools unlock, and plan-viewer opens a browser GUI for approving the plan with checkboxes, reordering, and inline editing.
• Coordinating multiple specialists. TEAM mode dispatches a primary agent to specialists; CHAIN mode runs sequential pipelines where each step's output feeds the next via $INPUT; PIPELINE is a 5-phase hybrid (UNDERSTAND → GATHER → PLAN → EXECUTE → REVIEW) that mixes sequential phases with parallel dispatch.
• Safer shell work. security-guard installs a pre-tool hook that blocks rm -rf, sudo, credential theft, and prompt injection patterns, while message-integrity-guard prevents session-bricking from orphaned tool results.
• Reviewing changes visually. completion-report shows unified diffs and per-file rollback; spec-viewer supports multi-page spec review with comments.
• Carrying context across compaction. memory-cycle saves and restores state, and /replay scrolls a timeline of conversation history.

How engineers can use it

The README provides two install paths. The one-line installer handles Pi, package registration, and settings:

git clone https://github.com/ruizrica/agent-pi.git && cd agent-pi && ./install.sh

If Pi is already installed, the package can be added directly:

pi install git:github.com/ruizrica/agent-pi

After install, Pi auto-discovers the extensions, themes, and skills. The day-to-day workflow documented in the README is: type a task to start; press Shift+Tab to cycle through NORMAL, PLAN, SPEC, PIPELINE, TEAM, CHAIN; press Ctrl+X to cycle themes like Catppuccin, Dracula, Nord, or Tokyo Night; use /agents-team and /chain to switch configurations; and /tex to open the bundled zero-dependency text manipulation page.

A few documented limitations are worth noting. The bundled models.json references models across several providers, so engineers should create a user-level ~/.pi/agents/models.json to route agents to providers available in their environment—otherwise agents may use unexpected defaults. The Commander MCP bridge is optional and off by default; enabling it requires setting COMMANDER_MCP_SERVER_PATH to a local build, and when unset its tools simply report "not configured" rather than spawning a server. Teams, chains, and pipelines are defined as YAML under agents/ (for example, plan-build: [planner, builder, reviewer]) and load automatically, so reconfiguration does not require code changes.