oh-my-pi (omp): the batteries-included terminal coding agent that gets edits right the first time
oh-my-pi (omp) is a fork of Pi that adds hash-anchored edits, LSP integration, DAP debugging, 40+ providers, 32 tools, and subagent orchestration—all in ~27k lines of Rust. Installation, architecture, and when to choose omp over Claude Code or Cursor.
oh-my-pi (omp) is the terminal coding agent that answers a blunt question: why do agents keep failing edits that should work? Built by Can Bölük as a fork of Mario Zechner's Pi — see our Pi harness guide for upstream Pi — omp adds the harness engineering missing from most agent surfaces—hash-anchored edits that eliminate whitespace battles, LSP integration so renames propagate correctly, DAP-driven debugging against live binaries, 40+ model providers with per-role routing, and subagent orchestration across isolated worktrees. The repository has climbed to 5.5k+ stars in months, with a 458-fork ecosystem and 177 contributors—signals that teams want production-grade tools, not demo prompts.
This article is a field guide: what problem it solves, the core architecture, installation paths, feature comparison, and when to choose omp over Claude Code, Cursor, or a custom harness.
TL;DR
Question
Short answer
What is it?
A batteries-included terminal coding agent forked from Pi, adding hashline edits, LSP/DAP, 40+ providers, 32 tools, and subagent fan-out.
Regex search, parallel/sequential, glob & type filters, fuzzy find
1,900
pi-ast
tree-sitter structural summaries and ast-grep pattern matching/rewrites
1,040
Plus keys (Kitty keyboard protocol), text (ANSI-aware width/truncation), highlight (syntect), pty (portable-pty), glob (ignore + globset), image (decode/encode/resize), tokens (tiktoken BPE), html (HTML→Markdown), and more—all in-process on the libuv thread pool. No fork/exec on the hot path.
Platform targets: linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64. The same omp binary runs on macOS, Linux, and Windows—no WSL bridge.
Feature 01: Hash-anchored edits (hashline format)
Problem:str_replace diffs fail when whitespace, line endings, or model hallucination makes old_string not match.
Solution: The model references content hashes as anchors instead of retyping lines. If anchors diverge (the file changed since the agent read it), the patch is rejected before it corrupts anything.
Impact: Grok 4 Fast spends 61% fewer output tokens on the same work. Gemini 3 Flash gains +5 pp over str_replace. MiniMax doubles its pass rate—same weights, same prompt, different edit format.
The replacement count previews before apply; the change is staged, then accepted with a reason.
Feature 02: LSP integration—everything your IDE knows, the agent knows
Problem: The agent renames a symbol in one file but misses re-exports, barrel files, or aliased imports.
Solution: The lsp tool exposes diagnostics, navigation (go-to-definition, references), symbols, renames, code actions, and raw LSP requests. When the agent renames, it goes through workspace/willRenameFiles, so downstream updates happen correctly.
Problem: Most harnesses lock you into one API. If that provider hits quota, throws 429s, or has a model outage, the session dies.
Solution: omp routes by role (default, smol, slow, plan, commit). Each role can have a fallback chain; when the primary throws 429s, the next entry takes the rest of the turn—restored on cooldown. Round-robin credentials per provider rotate with session affinity and per-credential backoff.
Ollama (local), LM Studio (local), llama.cpp (local), vLLM (local), LiteLLM
Custom providers: Declare anything that speaks openai-completions, anthropic-messages, google-generative-ai, or google-vertex in ~/.omp/agent/models.yml.
omp ships 32 tools in the same namespace as read and bash. The active set is controlled by --tools read,edit,bash,...; the rest stay hidden but indexed—search_tool_bm25 pulls them back mid-session when tools.discoveryMode allows.
Feature 07: web_search with 14 providers and site-aware extraction
Problem: Generic web fetch returns stripped HTML; the agent loses link structure and can't cite or follow anchors.
Solution:web_search chains 14 providers (auto mode walks the chain; pin one by name). Site-aware extraction turns GitHub, arXiv, Stack Overflow, npm, PyPI, crates.io, docs.rs, and more into structured markdown with anchors and link targets intact.
✓ web_search: "inference-time compute scaling"
Provider: perplexity
10 ranked sources
✓ read https://arxiv.org/pdf/2604.10739v1
Extracted: structured markdown with sections, equations, citations
Agent: "The paper reports a 3.2× improvement on MATH with 64 test-time samples vs greedy decoding (Table 2, page 5)."
Feature 08: Time-traveling stream rules
Problem: The model goes off-script; you want to inject a correction mid-stream without paying context tax on every turn.
Solution:Stream rules sit dormant until a regex match aborts the stream mid-token, injects the rule as a system reminder, and retries from the same point. Injections survive compaction, so the fix sticks.
Example:
text
✓ Reading src.rs
Agent: "Let me use Box::leak to..."
⚠ Request aborted
⚠ Injecting rule: box-leak
"Don't reach for Box::leak in production code paths."
Agent: "On second thought, Arc<str> is safer here. Should I proceed?"
Feature 09: Hindsight—memory the agent curates
Problem: The agent forgets codebase facts between sessions.
Solution:Hindsight lets the agent write facts mid-run with retain, pull them back with recall, and compress each session into a mental model that loads on the first turn of the next one. Project-scoped by default.
Tools:
retain — queue durable facts into the active Hindsight bank
recall — search the bank for raw memories
reflect — ask Hindsight to synthesize an answer over the bank
Feature 10: Four entry points—interactive, one-shot, RPC, ACP
Same engine, four wrappers:
Mode
When to use
Interactive (TUI)
Default. Tool calls render as cards, edits preview before apply, ambiguity routes through the ask tool.
One-shot (omp -p)
Single prompt, exit. Useful in CI or scripts.
Node SDK
Embed the session in a Node/TypeScript process. @oh-my-pi/pi-coding-agent exposes ModelRegistry, SessionManager, createAgentSession.
RPC (omp --mode rpc)
NDJSON commands over stdio. For non-Node embedders or process isolation.
ACP (omp acp)
Agent Client Protocol (JSON-RPC). When the editor advertises capabilities, tool I/O routes through it and writes are gated by session/request_permission.
Interactive IDE workflows, fast prototyping, single-provider simplicity
Bottom line: Use Claude Code/Cursor for interactive IDE workflows with strong UX. Use omp when you need terminal workflows, edit accuracy, LSP/DAP integration, custom provider routing, or subagent orchestration.
Monorepo structure
omp is a TypeScript + Rust monorepo. Key packages:
Package
Description
@oh-my-pi/pi-ai
Multi-provider LLM client with streaming and model/provider integration
@oh-my-pi/pi-agent-core
Agent runtime with tool calling and state management
@oh-my-pi/pi-coding-agent
Interactive coding agent CLI and SDK
@oh-my-pi/pi-tui
Terminal UI library with differential rendering
@oh-my-pi/pi-natives
N-API bindings for grep, shell, image, text, syntax highlighting
No migration script. The config your team wrote last quarter works tonight.
Extensions: TypeScript modules loaded from ~/.omp/extensions or project-local .omp/extensions. Same tool API, same slash-command registry, same hotkey table the built-ins use.
Example: Ask omp to write the piece you're missing, then /reload-plugins.
Benchmarks and evidence
Model
Metric
What changed
Grok Code Fast 1
6.7% → 68.3%
Tenfold lift when hashline format stops eating the model alive
Gemini 3 Flash
+5 pp
Over str_replace—beats Google's own best attempt at the format
Grok 4 Fast
−61% tokens
Output collapses once the retry loop on bad diffs disappears
MiniMax
2.1× pass rate
Pass rate more than doubles—same weights, same prompt
read tool: summarized snippets, ideal defaults, selector hit rate
search tool: fastest in the west (in-process ripgrep)
lsp tool: everything your IDE knows, the agent knows
prompts: adjusted relentlessly for each model
Repository stats, model support, and CLI features change frequently. Treat this as May 21, 2026 context—verify installation commands and provider lists before production deployment. oh-my-pi is MIT-licensed; contributions welcome.
