Pi Agent

Enterprise-grade AI coding agent system with modular architecture.

English | 中文

---

Overview

Pi Agent is an autonomous AI orchestrator for software development — a monorepo containing the agent core, a multi-channel gateway, 40+ skills, 30+ extensions, and 20+ specialized subagents.

• 5-Phase Workflow: Context retrieval → Analysis → Prototyping → Implementation → Audit
• Multi-Model Orchestration: Claude, Gemini, and specialized tool routing
• Multi-Channel Gateway: Telegram, Discord, WebChat via single-port HTTP+WS server
• Plugin Architecture: Skills (prompt injection), Extensions (runtime hooks), Agents (task delegation)
• Enterprise Protocols: Code sovereignty, sandbox security, SSOT documentation

Prerequisites

• Bun >= 1.1.0
• Pi Agent Core (pi CLI installed)
• Node.js >= 18 (for some skills)

Installation

Windows

# Install Bun
powershell -c "irm bun.sh/install.ps1 | iex"

# Restart terminal after Bun installation

Clone with Submodules

# Option 1: Clone with submodules
git clone --recurse-submodules <repo-url> ~/.pi/agent

# Option 2: If already cloned, initialize submodules
git submodule init
git submodule update --init --recursive

Install Dependencies

# Install dependencies for all extensions with package.json
cd extensions/pi-context && bun i
cd ../pi-files && bun i
cd ../pi-interactive-shell && bun i
cd ../pi-messenger && bun i
cd ../pi-subagents && bun i

Quick Start

# Use workflow commands in any project
/scout authentication flow      # Fast code reconnaissance
/analyze database schema        # Deep analysis
/brainstorm caching strategy    # Design exploration

# Start the multi-channel gateway
cd ~/.pi/agent/pi-gateway && bun install && bun run start

Project Structure

~/.pi/agent/
├── pi-gateway/            # Multi-channel AI gateway (Telegram/Discord/WebChat)
├── extensions/            # Runtime extensions (30 modules)
│   ├── pi-interactive-shell/  # Interactive CLI overlay (vim, psql, ssh)
│   ├── pi-subagents/          # Multi-agent chains & parallel execution
│   ├── plan-mode/             # Read-only planning with command interception
│   ├── role-persona/          # Per-role memory & personality isolation
│   ├── games/                 # Mini-games (Snake, Tetris, 2048, Minesweeper)
│   ├── answer.ts              # Interactive Q&A TUI (Ctrl+.)
│   ├── workflow-commands.ts   # /scout, /analyze, /brainstorm, /research
│   ├── safety-gates.ts        # Destructive operation interception
│   └── ...
├── skills/                # Prompt-injectable capabilities (40 modules)
│   ├── ace-tool/              # Semantic code search (AugmentCode MCP)
│   ├── web-browser/           # Chromium automation (CDP)
│   ├── tmux/                  # Remote terminal session control
│   ├── workhub/               # Issue/PR documentation management
│   ├── office-combo/          # Excel, PPT, PDF, Word support
│   └── ...
├── agents/                # Subagent definitions (20+ markdown specs)
├── prompts/               # Workflow templates (init, handoff, implement, etc.)
├── roles/                 # Role-based persona configurations
├── commands/              # Slash command definitions (/scout, /analyze, etc.)
├── messenger/             # Inter-agent session registry & event feed
├── landing-page/          # Marketing site (Vite + Lit + Tailwind)
├── docs/                  # System protocols, guides, knowledge base
├── APPEND_SYSTEM.md       # Agent system prompt
├── settings.json          # Agent runtime settings
├── models.json            # Model provider configurations
└── auth.json              # Authentication credentials

Pi Gateway

Single-port HTTP+WebSocket gateway that routes messages from Telegram, Discord, and WebChat into isolated pi agent RPC processes.

cd pi-gateway
bun install
bun run start                    # Start gateway (default port 18800)
bun run dev                      # Start with hot-reload
bun run src/cli.ts doctor        # Health check
bun run src/cli.ts config show   # Show current config

Key capabilities:

• 3 built-in channels: Telegram (polling/webhook, multi-account, media), Discord (slash commands), WebChat (browser UI)
• RPC process pool: Min/max scaling, capability-based matching, idle eviction
• Session routing: agent:{agentId}:{channel}:{scope}:{id} key format with role mapping
• Plugin system: 14 lifecycle hooks, register channels/tools/HTTP routes/WS methods/commands/services
• Cron & Heartbeat: Scheduled jobs (cron/every/at), periodic agent wake-up
• Media pipeline: Receive/send images with HMAC-SHA256 signed URLs
• OpenAI-compatible API: /v1/chat/completions endpoint
• Config: pi-gateway.jsonc with JSON5 support, deep merge, hot-reload

→ Architecture docs

Extensions

Runtime hooks that enhance the agent's UI, commands, and behavior. → Details

Skills

Prompt-injectable capabilities — each skill is a SKILL.md file injected into the agent's system prompt at runtime.

Agents

Specialized subagents defined as markdown files with YAML frontmatter. → Examples

Messenger

Inter-agent session registry and event feed for multi-agent coordination.

• messenger/registry/ — JSON metadata per agent (PID, session, model, activity)
• messenger/feed.jsonl — JSONL event log (messages, test results, agent activities)
• messenger/inbox/ — Per-agent message directories

Roles

Role-based persona system mapping project paths to agent identities.

• roles/config.json — Path-to-role mapping (e.g., ~/.pi/agent → "zero")
• roles/default/ — Default role configuration
• Each role can have isolated memory, personality, and workspace context (via role-persona extension)

Core Workflow

graph LR
    A[Phase 1: Context Retrieval] --> B[Phase 2: Analysis]
    B --> C[Phase 3: Prototyping]
    C --> D[Phase 4: Implementation]
    D --> E[Phase 5: Audit]

Workflow Commands

Design Principles

1. Code Sovereignty — External AI code is reference only; must refactor to production quality via Unified Diff Patch
2. Sandbox Security — External models cannot write directly; human-in-the-loop for all modifications
3. SSOT — One authoritative source per knowledge domain; reference over copy; filesystem as memory
4. Token Efficiency — Information-dense docs; reference links over duplication; context holds paths, files hold content

Configuration

See Also

• Gateway Architecture — System design and module reference
• Core Modules — RPC pool, session router, message queue
• Plugins & Channels — Plugin system and channel implementations
• Extension Development — Guide to building pi extensions
• Agent Examples — Subagent usage patterns

License

MIT