.pi - Personal AI Coding Agent Configuration

Note

: This repository contains the personal configuration for the Pi Coding Agent CLI. It implements a sophisticated multi-agent workflow system, custom security controls, and specialized skills for AI-assisted software development.

🚀 Overview

.pi extends the base Pi CLI capabilities by introducing a specialized multi-agent architecture. Instead of a single generalist AI, this configuration deploys a team of experts—scouts, planners, workers, reviewers, and researchers—coordinated through a custom Subagent Delegation Framework.

Key Features

• 🤖 Multi-Agent System: 6 specialized personas (Scout, Planner, Worker, Reviewer, Librarian, Oracle) optimized for specific stages of development.
• 🔗 Subagent Delegation: A powerful framework allowing agents to spawn child processes, pass context, and execute tasks in parallel or sequential chains.
• 🛡️ Custom Security Model: A three-tier permission system (my-permissions.ts) that enforces strict controls on shell execution and file writes while allowing safe read operations.
• 🌐 Browser Automation: A persistent dev-browser skill for web scraping, testing, and interaction using Playwright.
• 🎨 Frontend Design Skill: A dedicated module for generating production-grade, high-quality UI/UX designs.
• ⚡ Workflow Templates: Pre-defined prompts (e.g., /implement) that orchestrate multi-step workflows like "Scout → Plan → Code".
• 🧭 ask_user Tool: A tabbed, multi-question prompt tool for collecting structured answers (custom overlay UI).

---

📂 Architecture

The configuration is contained within the agent/ directory:

~/.pi/
├── agent/
│   ├── agents/                     # 🧠 Agent Definitions
│   │   ├── scout.md               # Reconnaissance & context gathering
│   │   ├── planner.md             # Implementation planning
│   │   ├── worker.md              # Code execution & file modification
│   │   ├── reviewer.md            # Code review & security auditing
│   │   ├── librarian.md           # Open-source research
│   │   └── oracle.md              # Strategic technical advisory
│   │
│   ├── extensions/                 # 🔌 Custom Extensions
│   │   ├── subagent/              # Delegation framework core
│   │   ├── my-permissions.ts       # Security policy implementation
│   │   └── ask-user.ts             # Tabbed multi-question prompt tool
│   │
│   ├── skills/                     # 🛠️ Reusable Capabilities
│   │   ├── dev-browser/           # Playwright-based browser automation
│   │   └── frontend-design/       # UI/UX design expert
│   │
│   ├── prompts/                    # 📋 Workflow Templates
│   │   ├── scout-and-plan.md
│   │   ├── implement.md
│   │   └── implement-and-review.md
│   │
│   ├── sessions/                   # Runtime data (gitignored)
│   ├── auth.json                   # Credentials (gitignored)
│   └── settings.json               # Global settings

---

🤖 The Agents

Each agent runs with a distinct system prompt and toolset optimized for its role:

Agent	Role	Capabilities	Model
Scout	Reconnaissance	Fast codebase analysis. Compresses findings into structured context.	Claude Haiku
Planner	Architecture	Creates detailed, step-by-step implementation plans. Read-only access.	Gemini 3 Pro
Worker	Execution	General-purpose coder. Writes code, runs commands, modifies files.	Claude Opus
Reviewer	Quality Control	Audits code for bugs, security flaws, and style issues. Read-only.	Claude Opus
Librarian	Research	Searches documentation and open-source code. Provides permalinks.	Claude Sonnet
Oracle	Strategy	High-level technical advisor for complex architectural decisions.	GPT-5.2 Codex

---

🔗 Subagent Framework

The core innovation of this configuration is the Subagent Extension (agent/extensions/subagent/). It allows the main agent to delegate tasks using three patterns:

1. Single Delegation: Offload a specific task to a specialist.

   { "agent": "scout", "task": "Find the authentication logic in src/auth" }
   

2. Parallel Execution: Run multiple independent tasks concurrently.

   { "tasks": [
     { "agent": "scout", "task": "Analyze frontend dependencies" },
     { "agent": "scout", "task": "Analyze backend API routes" }
   ]}
   

3. Sequential Chains: Pass context from one agent to the next.

   { "chain": [
     { "agent": "scout", "task": "Map out the user profile feature" },
     { "agent": "planner", "task": "Create a migration plan based on: {previous}" },
     { "agent": "worker", "task": "Execute the plan: {previous}" }
   ]}
   

---

🛡️ Security Model

Permissions are managed by agent/extensions/my-permissions.ts, enforcing a "safety-first" policy:

• READ: Always allowed (grep, ls, find, read).
• WRITE: Requires user confirmation per file, or a session-wide "Allow All Writes" approval.
• BASH:
  • Dangerous Binaries: rm, sudo, chmod, sh, bash, curl, etc. are always prompted.
  • Complex Commands: Commands with pipes (|), redirects (>), or chaining (&&) are always prompted.
  • Local Execution: Relative paths (./script.sh) and traversal (..) are always prompted.
  • Simple Commands: Safe binaries (e.g., git status, npm test) can be whitelisted for the session.

---

🛠️ Skills

🌐 Dev Browser (agent/skills/dev-browser/)

A comprehensive browser automation tool built on Playwright.

• Capabilities: Navigate URLs, click elements, fill forms, take screenshots, extract text.
• Smart Selectors: Uses AI to identify elements robustly.
• Persistent State: Maintains cookies and local storage across sessions.

🎨 Frontend Design (agent/skills/frontend-design/)

A design expert that guides the creation of modern, polished UIs.

• Focus: Avoids generic "AI aesthetic".
• Output: Production-ready CSS/HTML/React components with distinctive typography and layout.

---

📋 Workflows

Pre-defined prompts in agent/prompts/ automate common development loops:

• /implement: Scout analyzes context → Planner creates a plan → Worker executes it.
• /scout-and-plan: Scout gathers info → Planner delivers a strategy (no code changes).
• /implement-and-review: Worker writes code → Reviewer critiques it → Worker fixes issues.

License

Personal configuration. Use at your own risk.