AI/oh-my-pi.md

Table of Contents

Oh My Pi — Coding Agent Reference

What is OMP?

Oh My Pi is the coding agent harness that runs in this session. It provides:

  • The system prompt, contract rules, and environment
  • Built-in tools (read, edit, bash, ast_grep, lsp, etc.)
  • Config discovery from .omp/ directories
  • MCP server connectivity
  • Skills, prompts, hooks, extensions, custom tools, and rules

Where config comes from

Config is discovered at startup through a capability provider system. Providers are ordered by priority:

Provider Priority Source
Native .omp 100 .omp/ (project) + ~/.omp/agent/ (user)
Claude 80 .claude/ directories
Codex/Agents 70 .codex/ directories
Gemini 60 .gemini/ directories

Discovery order per source: user-level first, then project-level. Within each root, .omp is checked before .claude, .codex, .gemini.

Deduplication: capabilities define a key() — first match by name wins (highest priority provider). Settings are not deduplicated; later values deep-merge over earlier ones.

Config roots (precedence order)

  1. ~/.omp/agent / .omp
  2. ~/.claude / .claude
  3. ~/.codex / .codex
  4. ~/.gemini / .gemini

Settings: ~/.omp/agent/config.yml (global, writable) + .omp/settings.json (project capability, read-only). Layered: defaults → global → project → runtime overrides.

What lives where

Feature Location Format
Skills .omp/skills/<name>/SKILL.md Markdown with YAML frontmatter
Prompts .omp/prompts/*.md Markdown
Rules .omp/rules/*.{md,mdc} Markdown with YAML frontmatter
Hooks .omp/hooks/pre/*, post/* (shell); also TS/JS module hooks Shell scripts or TS modules
Custom Tools .omp/tools/*.{ts,js,sh,bash,py} Executable modules
Extensions .omp/extensions/<name>/ TS/JS modules
Commands .omp/commands/*.md Markdown
Instructions .omp/instructions/*.md Markdown
MCP servers .omp/mcp.json, ~/.omp/agent/mcp.json, root mcp.json JSON
Settings ~/.omp/agent/config.yml YAML
AGENTS.md Project root AGENTS.md or CLAUDE.md Markdown

Skills

  • Directory: <skill-name>/SKILL.md with YAML frontmatter (name, description, globs, alwaysApply)
  • Accessed via skill://<name> and skill://<name>/path/to/file
  • Native .omp provider requires description in frontmatter
  • Togglable via skills.enabled, ignoredSkills, includeSkills
  • Subagents inherit the session's skill list

Prompts

  • Simple markdown files in .omp/prompts/
  • Retrieved by name via mcp__qwestly_get_prompt
  • 18 Qwestly prompts: code-review, write-unit-tests, security-review, planning-doc, etc.

Rules

  • .omp/rules/*.{md,mdc} with YAML frontmatter
  • Three buckets: TTSR (condition-triggered), alwaysApply (injected into system prompt), Rulebook (listed by name, read on demand via rule://<name>)
  • Dedup by rule.name; native provider wins at priority 100
  • Also loaded from .cursor/rules/, .windsurf/rules/, .clinerules

MCP servers

  • Config: .omp/mcp.json or ~/.omp/agent/mcp.json
  • Transports: stdio (command + args), http (url), sse (url — legacy)
  • Auth: oauth or apikey with token management
  • disabledServers in user config to suppress servers from other providers
  • Env vars resolve: literal value → env var lookup → fallback to literal

Hooks

  • Legacy shell hooks: .omp/hooks/pre/*, post/*
  • Modern JS/TS hooks: module with default export, receive HookAPI
  • Can block tool calls (tool_call → { block: true }), modify tool results (tool_result → { content, details }), filter context (context → { messages })
  • Runner order: registration order within load order

Extensions

  • Unified system: events + tools + commands + renderers + provider registration
  • Module exports default factory receiving ExtensionAPI
  • Lifecycle: load (register only) → ExtensionRunner.initialize() → events fire
  • Can sendMessage (steer/followUp/nextTurn), setModel, setThinkingLevel, appendEntry
  • Events: session, tool, prompt/turn, reliability signals

Custom Tools

  • Model-callable functions with Zod parameter schemas
  • Module exports factory receiving CustomToolAPI (includes pi.exec, pi.zod, pi.cwd)
  • Wrapped via CustomToolAdapter into agent tool registry
  • Name must be globally unique; conflicts with built-ins rejected

Built-in tools

read, edit, write, bash, search, find, ast_grep, ast_edit, lsp, eval (Python/JS kernels), browser, task (subagents), todo_write, web_search, resolve, debug, ask

MCP integrations (tool namespaced as mcp__<server>_<tool>)

MCP servers are referenced from Claude config — OMP reads the same MCP server definitions (from .claude/mcp.json, mcp.json, etc.) rather than defining its own. So the MCP ecosystem isn't an OMP differentiator; it's inherited from whatever Claude already has configured.

Currently available servers:

  • Asana — task/project CRUD, search, users, teams, portfolios
  • Chrome DevTools — multi-tab browser, snapshots, screenshots, performance, network
  • Desktop Commander — filesystem operations, shell processes, REPLs, code search
  • Granola — meeting transcripts and AI summaries
  • Personal Notes — markdown knowledge base (CRUD + search)
  • Qwestly Docs — project-specific docs (same shape)
  • Qwestly Prompts — prompt templates + markdown-to-Asana-HTML

OMP vs. Claude Code

Real differentiators

1. Tool sophistication

  • ast_grep / ast_edit — structural code search and rewrite at the AST level, not regex. Rename symbols, find call sites, apply codemods without false positives from strings, comments, or formatting.
  • LSP integration — go-to-definition, find-references, rename, hover, code-actions. TypeScript/Python-aware refactors without manual grepping.
  • Structured editing — line-anchored patches with content hashes. Edits stay precise even as file state shifts during a session.
  • eval — persistent Python and JS kernels for quick compute, data munging, diff analysis.

Claude Code has file reading/editing and bash, but no AST-level or LSP-level code intelligence.

2. Parallel subagents The task tool spawns specialized subagents (explore, plan, oracle, reviewer, task, quick_task) that run concurrently. A multi-file refactor can farm out disjoint scopes to parallel workers. Subagents can coordinate via irc. Claude Code is single-threaded per session.

3. Model independence OMP is a harness, not a model API. You can plug in any provider (OpenAI, Anthropic, DeepSeek, Groq, open-source via Ollama) while keeping the same tooling, skills, and workflow. The harness doesn't care which model is behind it.

4. Quality contracts The contract system enforces non-negotiable behaviors at the harness level (not just prompt-level):

  • Never yield incomplete work
  • Verify changes with tests, not just "it compiles"
  • Never silently shrink scope
  • Never substitute the user's problem with an easier one

In Claude Code, these behaviors depend entirely on prompting.

5. Skills system Pre-built, loadable expertise modules for specific domains (Vercel ecosystem, Next.js, SVG generation, PDF conversion, etc.). Loaded on demand via skill://<name>. More reliable than hoping the model's weights happen to know the latest APIs.

6. Artifact retention Previous tool outputs are retrievable — artifact://<id> gives the full untruncated output of any prior command. Build output, test failures, logs — nothing is lost to truncation.

7. Capability provider system Config is discovered from multiple sources (.omp/, .claude/, .codex/, .gemini/) with explicit priority ordering. You can use Claude's MCP config, Codex's prompts, and OMP's rules — they compose rather than conflict.

Internal URL protocols

  • skill://<name> — resolve skill SKILL.md
  • skill://<name>/path — resolve file inside skill directory
  • rule://<name> — resolve rule content
  • agent://<id> — full agent output artifact
  • artifact://<id> — artifact content
  • memory://root — project memory summary
  • local://<name>.md — plan artifacts
  • mcp://<uri> — MCP resource
  • omp:// — harness documentation

Sessions

  • Stored: ~/.omp/agent/sessions/--<cwd-encoded>--/<timestamp>_<sessionId>.jsonl
  • JSONL format: header (v3) + append-only entry tree with id/parentId + mutable leafId pointer
  • Entry types: message, compaction, branch_summary, custom, label, thinking_level_change, model_change, etc.
  • Context reconstruction walks parent chain from leaf to root
  • Blob externalization for large content (>500K chars) and images (base64 → blob store)
  • Non-persistent sessions via inMemory

Theming

  • Built-in themes: dark, light, and defaults/*.json
  • Custom themes: ~/.omp/agent/themes/<name>.json
  • Settings: theme.dark, theme.light, symbolPreset, colorBlindMode
  • Watcher auto-reloads custom theme on file change
  • Color modes: truecolor, 256-color, or terminal default

Key directories

Path Purpose
~/.omp/agent/ User config: config.yml, MCPs, sessions, themes, skills, prompts, rules
.omp/ Project config: skills, prompts, rules, hooks, tools, MCPs
~/.omp/agent/sessions/ Session JSONL files
~/.omp/agent/blobs/ Externalized blob storage
~/.omp/agent/themes/ Custom theme JSON files
~/.omp/agent/history.db Prompt history SQLite with FTS5
~/.omp/agent/terminal-sessions/ Terminal-to-session breadcrumbs