@miadi/agent-pi

---

What is this?

Pi is a terminal-based AI coding agent by @badlogic. Out of the box it's a single-agent assistant with tool use, conversation memory, and a TUI.

agent is a Pi package — 43 extensions, 11 themes, and 20+ skills that transform Pi into something more:

• 6 operational modes — NORMAL, PLAN, SPEC, PIPELINE, TEAM, CHAIN
• Multi-agent orchestration — dispatch teams, run sequential chains, or execute parallel pipelines
• Security hardened — pre-tool-hook guard blocks destructive commands, detects prompt injection, prevents data exfiltration
• Browser-based viewers — interactive plan review, completion reports with rollback, spec approval with inline comments
• 11 themes — Catppuccin, Dracula, Nord, Synthwave, Tokyo Night, and more

Everything is configuration — no forks, no patches. Just extensions, agent definitions, and YAML.

Install

One-line installer (recommended)

Don't have Pi installed? No problem. The installer handles everything — installs Pi, registers the package, and configures settings in one go:

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

Already have Pi?

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

Pi discovers all extensions, themes, and skills automatically.

First Steps

1. Type a task — Pi operates in plan-first mode. It will ask you to define tasks before using tools.
2. Shift+Tab — Cycle through operational modes (NORMAL → PLAN → SPEC → PIPELINE → TEAM → CHAIN)
3. Ctrl+X — Cycle themes
4. /agents-team — Switch between agent teams
5. /chain — Switch between chain workflows
6. /tex — Open Text Tools in the browser

Package Structure

├── package.json         Pi package manifest
├── extensions/          43 TypeScript extensions + lib/
├── themes/              11 custom terminal themes
├── skills/              20+ skill packs
├── agents/              Agent definitions + chain/pipeline/team YAML
├── commands/            Toolkit slash commands
├── prompts/             Prompt templates
└── tex/                 Text Tools — standalone text manipulation app

Extensions

Core UI

Extension	Description
agent-banner	ASCII art banner on startup, auto-hides on first input
footer	Status bar — model name, context %, working directory
agent-nav	F1-F4 navigation shared across agent widgets
theme-cycler	Ctrl+X to cycle through installed themes
escape-cancel	Double-ESC cancels all running operations

Task Management

Extension	Description
tasks	Task discipline — define tasks before tools unlock; idle → inprogress → done lifecycle
commander-mcp	Bridge exposing Commander dashboard tools as native Pi tools
commander-tracker	Reconciles local tasks with Commander; retries failed sync

Operational Modes

Extension	Description
mode-cycler	Shift+Tab cycles NORMAL / PLAN / SPEC / PIPELINE / TEAM / CHAIN

Each mode injects a tailored system prompt. PLAN mode enforces plan-first workflow. SPEC mode drives spec-driven development. TEAM/CHAIN/PIPELINE modes activate their respective orchestration systems.

Multi-Agent Orchestration

Extension	Description
agent-team	Dispatch-only orchestrator — primary agent delegates to specialists via dispatch_agent
agent-chain	Sequential pipeline — each step's output feeds into the next via $INPUT
pipeline-team	5-phase hybrid — UNDERSTAND → GATHER → PLAN → EXECUTE → REVIEW
subagent-widget	Background subagent management with live status widgets
toolkit-commands	Dynamic slash commands from markdown files

Security

Extension	Description
security-guard	Pre-tool-hook: blocks rm -rf, sudo, credential theft, prompt injection
secure	/secure — full AI security sweep + protection installer for any project
message-integrity-guard	Prevents session-bricking from orphaned tool_result messages

Viewers & Reports

Extension	Description
plan-viewer	Browser GUI — plan approval with checkboxes, reordering, inline editing
completion-report	Browser GUI — work summary, unified diffs, per-file rollback
spec-viewer	Browser GUI — multi-page spec review with comments and visual gallery
file-viewer	Browser GUI — syntax-highlighted file viewer with optional editing
reports-viewer	Searchable /reports browser view for all persisted artifacts

Developer Tools

Extension	Description
debug-capture	VHS-based terminal screenshots for visual TUI debugging
web-test	Cloudflare Browser Rendering — screenshots, content extraction, a11y audits
tool-registry	In-memory index of all tools with categories and search
tool-search	Meta-tool — discover and inspect tools at runtime
tool-caller	Meta-tool — invoke any tool programmatically (dynamic composition)
lean-tools	Toggle lean mode — agent uses tool_search + call_tool instead of all tools

Session & Context

Extension	Description
memory-cycle	Memory-aware compaction — saves/restores context across compaction
session-replay	/replay — scrollable timeline of conversation history
system-select	/system — switch system prompt by picking agent definitions

Operational Modes

Mode	Trigger	Behavior
NORMAL	Default	Standard coding assistant
PLAN	Shift+Tab	Plan-first workflow — analyze → plan → approve → implement → report
SPEC	Shift+Tab	Spec-driven — shape → requirements → tasks → implement
TEAM	Shift+Tab	Dispatcher mode — primary delegates, specialists execute
CHAIN	Shift+Tab	Sequential pipeline — step outputs chain into next step
PIPELINE	Shift+Tab	5-phase hybrid with parallel dispatch

Multi-Agent Orchestration

Teams

Teams are defined in agents/teams.yaml. Each team is a list of agent names. Agent definitions live in agents/*.md with YAML frontmatter.

plan-build:
  - planner
  - builder
  - reviewer

Chains

Chains are sequential pipelines defined in agents/agent-chain.yaml. Each step specifies an agent and a prompt template with $INPUT (previous output) and $ORIGINAL (user's original prompt).

plan-build-review:
  description: "Plan, implement, and review"
  steps:
    - agent: planner
      prompt: "Plan the implementation for: $INPUT"
    - agent: builder
      prompt: "Implement the following plan:\n\n$INPUT"
    - agent: reviewer
      prompt: "Review this implementation:\n\n$INPUT"

Pipelines

Pipelines are defined in agents/pipeline-team.yaml and combine sequential phases with parallel agent dispatch.

Security

The security system operates at three layers:

1. tool_call hook — Pre-execution gate blocks dangerous commands before they run
2. context hook — Content scanner strips prompt injections from tool results
3. before_agent_start hook — System prompt hardening reminds the agent of security rules

The /secure command runs a comprehensive AI security sweep on any project and can install portable protections.

Themes

11 themes included. Cycle with Ctrl+X:

Catppuccin Mocha · Cyberpunk · Dracula · Everforest · Gruvbox · Midnight Ocean · Nord · Ocean Breeze · Rose Pine · Synthwave · Tokyo Night

Text Tools

A lightweight, zero-dependency text manipulation app bundled in tex/. Open it with /tex or directly at tex/index.html.

• 15 stackable operations — trim, dedupe, sort, case transforms, regex replace, and more
• Before/after diff view — see exactly what changed
• No backend, no build step — single HTML page, works offline
• Dark theme — matches the terminal aesthetic

Troubleshooting

Problem	Fix
Extensions not loading	pi install git:github.com/ruizrica/agent-pi — reinstall the package
No themes available	Same as above — themes are auto-discovered from the package
Shift+Tab not working	Ensure mode-cycler extension loaded — check pi config
No chains/pipelines	Agent configs at agents/ are loaded automatically by extensions

Built on Pi

This project is a configuration and extension layer for Pi Coding Agent by Mario Zechner (@badlogic). Pi provides the core runtime, TUI framework, LLM integration, and extension API.

---

By Ricardo Ruiz

Inspired by the work of IndyDevDan — check out his excellent video on Pi that helped shape this project.

License

MIT