oh-my-pi (omp) Mental Model Wiki

Pages

1. The Mental Model — One Picture of the Whole SystemThe simplest useful model of omp: what it is, how its layers relate, what the invariants are, and which facts let you predict behavior without reopening the code.
2. Agent Loop — The Turn Cycle & Harmony Safety LayerHow the agent loop drives LLM turns, executes tool calls, coerces malformed results, and detects GPT-5 Harmony protocol leakage — the core invariant that keeps session files valid.
3. Native Layer — Rust Crates & N-API AddonThe ~27k-line Rust underbelly: pi-natives (N-API cdylib), pi-shell (embedded bash/PTY), pi-ast (tree-sitter summarizer), pi-iso (workspace isolation), and how each module eliminates fork/exec on the hot path.
4. Four Run Modes — Interactive, Print, RPC, and ACPSame engine, four wrappers: the TUI interactive mode, one-shot print mode, NDJSON RPC over stdio, and ACP/JSON-RPC for editors. Understand which mode owns the I/O boundary, what framing it uses, and when tool calls route through the host.
5. Tools, LSP & DAP — What the Agent Can TouchThe 32 built-in tools (read, write, bash, search, eval, fetch, gh…), the 13 LSP operations wired through workspace/willRenameFiles, and the 27 DAP operations that attach real debuggers. State ownership, caching boundaries, and what differs between tool categories.
6. Extension Model — Providers, Plugins, Skills & Safe-Change RulesHow omp stays model-agnostic: the 40+ provider adapters in pi-ai, the plugin/marketplace loader, slash-command and skill registration, hook injection, MCP wiring, and the discovery pass that inherits rules from .claude/.cursor/.windsurf on first run. Closes with invariants for adding providers or extensions without breaking the session contract.