Introduction & Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
Oh My Pi (omp) is a specialized coding harness and CLI agent designed for load-bearing software engineering tasks. It operates as an autonomous assistant capable of codebase exploration, planning, multi-file architectural changes, and automated verification. The system is built to favor correctness and maintainability, utilizing a diverse set of specialized tools, subagents, and execution modes to handle complex development workflows.
Sources: packages/coding-agent/DEVELOPMENT.md:1-5, packages/coding-agent/src/prompts/system/system-prompt.md:11-20
Architecture Overview
The omp architecture is structured around a central boot flow that transitions from a CLI entry point to an interactive agent session. The core logic manages themes, settings, model registries, and session persistence.
Boot Flow Logic
The execution flow begins with argument processing and moves through specialized command adapters before establishing an AgentSession.
The cli.ts module also serves as a worker host, dispatching hidden worker selectors to manage background tasks.
Sources: packages/coding-agent/DEVELOPMENT.md:27-52
System Components
The project is divided into several high-level directories, each responsible for a specific subsystem:
| Directory | Responsibility |
|---|---|
src/session/ | Manages AgentSession, JSONL trees, storage, and history. |
src/tools/ | Contains built-in tool implementations and render helpers. |
src/modes/ | Implements Interactive TUI, Print, and RPC runtimes. |
src/task/ | Handles subagent delegation, parallelism, and swarming. |
src/mcp/ | Manages Model Context Protocol (MCP) transport and lifecycle. |
Sources: packages/coding-agent/DEVELOPMENT.md:65-90
Getting Started for Developers
The development environment is primarily powered by Bun. Developers should use the provided scripts rather than invoking compilers directly.
Local Development Commands
The following commands are essential for maintaining the codebase and running tests:
| Task | Command |
|---|---|
| Full Gate Check | bun run check (Typecheck + Lint) |
| Run Tests | bun run test |
| Build Binary | bun run build |
| Autofix | bun run fix (Lint + Prompt Formatting) |
| Regenerate Tool Views | bun run gen:tool-views |
Sources: packages/coding-agent/DEVELOPMENT.md:10-24
Initializing a Repository
To prepare a new repository for omp, an init agent can be used to generate AGENTS.md. This process involves parallel scanning of core source, tests, and configurations to synthesize repository guidelines.
Core Working Modes
omp operates in two primary states: Plan Mode and Implementation Mode.
Plan Mode
Plan mode is a strictly read-only state where the agent acts as an architect. It produces an execution specification (stored as local://<slug>-plan.md) without making any system changes.
Key Directives in Plan Mode:
- No file creation, deletion, or editing (except the plan file).
- No state-changing commands like
git commitornpm install. - Verification of all claims through
grep,glob, orread. - Transition to implementation requires a
resolvecall withaction: "apply".
Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:1-15, packages/coding-agent/src/prompts/system/plan-mode-active.md:113-132
Implementation Mode
In implementation mode, the agent executes the approved plan. It follows engineering principles that prioritize correctness and the reuse of existing patterns.
Tool Usage Policy:
- Surgical Edits: Use
editfor specific changes. - Structural Discovery: Use
ast_grepandlspfor code intelligence. - Compute: Use
evalfor logic/scripts, reservingbashfor short fact-computing pipelines. - Verification: All work must be verified via unit or E2E tests before yielding.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:105-135, packages/coding-agent/src/prompts/system/system-prompt.md:196-205
Internal Resources and Discovery
The system resolves configuration and resources through a discovery layer that supports multiple tool formats and internal URL schemes.
Internal URL Schemes
skill://<name>: Specialized domain knowledge and instructions.rule://<name>: Local constraints and project-specific rules.local://<name>.md: Shared content or plan artifacts for subagents.mcp://<uri>: Model Context Protocol resources.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:46-64
Config Path Resolution
omp tracks configuration across user and project levels. It supports path resolution for various environments:
export const SOURCE_PATHS = {
native: {
userAgent: `${getConfigDirName()}/agent`,
projectDir: CONFIG_DIR_NAME,
},
github: {
projectDir: ".github",
},
vscode: {
projectDir: ".vscode",
}
}
Sources: packages/coding-agent/src/discovery/helpers.ts:40-100
Conclusion
omp provides a robust, multi-agent environment for complex software development. By separating planning from execution and enforcing strict verification gates, it ensures that autonomous changes align with repository conventions and architectural intent. Developers can leverage the CLI to automate routine tasks while maintaining high standards for code correctness.
Sources: packages/coding-agent/DEVELOPMENT.md:144-165, packages/coding-agent/src/prompts/system/system-prompt.md:214-230