System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- packages/coding-agent/DEVELOPMENT.md
- packages/coding-agent/src/prompts/system/system-prompt.md
- packages/coding-agent/src/prompts/agents/plan.md
- packages/coding-agent/src/prompts/agents/init.md
- packages/coding-agent/src/prompts/system/orchestrate-notice.md
- packages/coding-agent/src/prompts/system/plan-mode-active.md
- packages/coding-agent/test/discovery/agents-monorepo-skills.test.ts
The Oh My Pi (omp) system is built as a multi-agent coding harness designed for complex software engineering tasks. It utilizes a hierarchical agent structure where a primary agent orchestrates specialized subagents to perform exploration, planning, and implementation. The architecture emphasizes high-level project guidance through discovery of local rules and skills, alongside a robust tool-based execution environment.
The system is structured as a monorepo, primarily centering on the pi-coding-agent package which serves as the CLI entry point. It integrates various backends for execution, including shell environments, language servers (LSP), and specialized web scrapers, all coordinated through an AgentSession lifecycle.
Sources: packages/coding-agent/DEVELOPMENT.md:1-10, packages/coding-agent/src/prompts/system/system-prompt.md:14-25
Command Execution & Boot Flow
The system initiates via the CLI, which handles argument parsing and dispatches commands to specific adapters. The boot flow transitions from raw argument processing to the creation of an AgentSession, which can run in several modes including Interactive (TUI), Print (one-shot), or RPC.
The boot process includes a worker-host dispatch mechanism in cli.ts to manage hidden worker scripts.
Sources: packages/coding-agent/DEVELOPMENT.md:27-44
Agent Hierarchy and Specialization
The architecture relies on specialized agent personas, each governed by specific prompts and toolsets. Agents are categorized by their role in the software development lifecycle:
Core Agent Roles
| Agent | Purpose | Key Tools |
|---|---|---|
| init | Generates repository guidelines (AGENTS.md) | explore agents, task tool |
| plan | Software architect for complex multi-file decisions | grep, glob, lsp, ast_grep, explore |
| explore | Fast read-only codebase scout | read, grep, glob, web_search |
| designer | UI/UX specialist for visual refinement | edit, write, read, design tokens |
| librarian | Researches external libraries/APIs | git clone, ast_grep, web_search |
| oracle | Senior engineer for debugging and architecture | explore, reasoning from first principles |
Sources: packages/coding-agent/src/prompts/agents/init.md:1-15, packages/coding-agent/src/prompts/agents/plan.md:1-10, packages/coding-agent/src/prompts/agents/explore.md:1-15, packages/coding-agent/src/prompts/agents/designer.md:1-10, packages/coding-agent/src/prompts/agents/librarian.md:1-15, packages/coding-agent/src/prompts/agents/oracle.md:1-10
Orchestration Pattern
When complex tasks are encountered, the system uses an orchestration pattern. The orchestrator decomposes requests into a todo list and dispatches work to parallel task subagents.
Planning and Execution Modes
The system operates in two distinct states: Plan Mode and Implementation Mode.
Plan Mode
Plan mode is a strictly read-only state. The agent acts as an architect to produce an "execution spec" (a markdown file at local://<slug>-plan.md).
- Constraint: No files may be edited or created except the plan file.
- Output: A decision-complete document that allows an implementer to execute without further design choices.
- Verification: The
resolvetool withaction: "apply"is required to exit this mode.
Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:1-15, packages/coding-agent/src/prompts/system/plan-mode-subagent.md:1-10
Implementation Lifecycle
Implementation follows a strict protocol of Scope -> Research -> Decompose -> Implement -> Verify -> Cleanup. Verification is prioritized, requiring proof through tests or LSP diagnostics before work is yielded as complete.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:110-145
Discovery and Context Management
The architecture includes a discovery system that scans for project-level configurations and capabilities. This allows the agent to adapt to the specific conventions of the target codebase.
Project-Level Discovery
The system performs a "walk-up" search from the current working directory to the repository root to find specialized configuration directories:
.agent/or.agents/- Sub-directories:
skills/,rules/,prompts/,commands/ - Context Files:
AGENTS.md(repository guidelines) andSYSTEM.md(custom system prompts).
Internal URL Schemes
The system utilizes specialized URL schemes to reference internal resources and state, which are auto-resolved by most file system and bash tools.
| Scheme | Description |
|---|---|
skill://<name> | Access to specialized skill instructions and files. |
rule://<name> | Project-specific domain rules. |
agent://<id> | Artifacts generated by agent outputs. |
local://<name>.md | Plan artifacts or shared content for subagents. |
memory://root | Project-wide memory summary. |
issue:// / pr:// | GitHub issues and PRs, typically disk-cached. |
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:40-60
Data Layout and Subsystems
The src/ directory of the coding agent is organized by responsibility, separating the TUI/interactive logic from the core execution backends.
- Execution Backends:
exec/,eval/,ssh/, andlsp/handle the actual interaction with the code and environment. - Memory Subsystems:
memories/,mnemopi/, andhindsight/manage long-term and short-term agent state. - Tooling Framework:
tools/contains built-in tool implementations, whilemcp/handles the Model Context Protocol for external tool integration. - Natives: The system utilizes high-performance native bindings (via
crates/pi-natives) for tasks like text search pipelines, PTY management, and code summarization.