Pi Route (@cary222/pi-route)

Capability-aware Mode Router & Workflow Orchestrator for Pi Coding Agent

中文文档 (Chinese)

---

What is Pi Route?

Pi Route is a capability-aware mode router that sits in front of other Pi plugins. When given a natural language requirement, it:

1. Classifies intent across 11+ lifecycle domains (planning, implementation, audit, research, browser automation, mobile device, security, etc.).
2. Inspects runtime capability truth directly from pi.getCommands() and pi.getAllTools().
3. Aligns with scenario profiles (e.g. App Development, Full-stack Web, Deep Research, Security Audit).
4. Discovers missing plugins on npm / Pi Packages Gallery in Explore Mode.
5. Generates graceful degraded workflows if the user declines third-party installations or works offline.
6. Prefills the optimal next command (e.g. /plan, /goal, /reach, /audit) into the editor for execution without taking over agent execution.

/route <your requirement>
       ↓
  Intent Analysis & Local Inventory Inspection
       ↓
  Recommend Optimal Pipeline: /plan → /goal → Browser QA → /audit
       ↓
  User Confirms / Degrades / Cancels
       ↓
  Prefill first command into editor

---

Key Features

• Authoritative Runtime Inventory: Checks pi.getCommands() rather than guessing from static configuration.
• Pure Domain Core: Clean layered architecture with 100% decoupled unit testability.
• Scenario Profiles: Pre-configured and customizable workflows for specific engineering disciplines.
• Preset vs. Explore Strategy: Fast deterministic local matching by default; on-demand npm market discovery when requested.
• Graceful Degraded Fallbacks: Never hallucinates missing tools—clearly explains capability losses and substitutes with standard Pi prompts.
• Zero Side-Effect Cancellation: Clean abort with zero modifications when cancelled.
• Safe Subprocess Execution: Packages are installed using execFile with argument arrays (no shell: true) and sensitive token masking.
• Dual Presentation: Interactive TUI components for terminal users; versioned pi-route.ui.v1 JSON event protocol for RPC / Pi Web clients.

---

Installation

From Pi Packages / npm

pi install npm:@cary222/pi-route

Try Without Installing

pi -e npm:@cary222/pi-route

Local Development Installation

git clone https://github.com/earendil-works/pi-route.git
cd pi-route
npm install
npm run build
pi -e .

---

Command Reference

Command	Description
/route	Opens the interactive Route Center dashboard
/route <requirement>	Analyzes requirement using active profile and recommends workflow
/route --profile <id> -- <req>	Temporarily uses a specific profile for requirement analysis
/route explore -- <requirement>	Enters Explore Mode to search npm marketplace for missing capabilities
/route profile list	Lists all built-in, global, and project scenario profiles
/route profile create [name]	Launches the interactive profile creation wizard
/route profile use <id>	Switches the active profile for the current session
/route profile default <id>	Sets the default profile for future sessions
/route profile clone <id> [new-id]	Clones an existing profile
/route profile edit <id>	Opens profile JSON in editor for direct editing
/route profile delete <id>	Deletes a custom profile (built-in general is protected)
/route status	Displays runtime commands, active tools, and installed plugins
/route help	Displays the help manual

Tip: Use the -- separator to ensure natural language containing keywords like profile or explore is not misinterpreted as subcommands.

---

Built-in Profiles

1. General Coding (general): Standard full-lifecycle workflow (/plan → /goal → /audit).
2. App Development (app-dev): Tailored for Android, iOS, and Expo (pi-android-cli + ADB + Logcat).
3. Full-stack Web (web-fullstack): Tailored for frontend QA and DOM verification (pi-agent-browser-native).
4. Deep Research (deep-research): Multi-source technical research and literature synthesis (pi-web-access + Feynman).
5. Security Audit (security-audit): Vulnerability scanning, Semgrep rules, and permission checks (pi-lens + piolium).

---

Architecture & Security

• Architecture Details: See docs/architecture.md
• Security Policy: See docs/security.md
• Catalog Maintenance: See docs/catalog-maintenance.md
• Pi Web / RPC Integration: See docs/pi-web-integration.md

---

License

MIT © 2026 Pi Extension Contributors