Oh My Pi (omp): Install Guide and Key Features

If you read about Pi and thought “I like it, but I don’t want to build subagents myself,” Oh My Pi is the answer a lot of people on X give. Its name comes up in almost every harness thread right now, often next to Pi. Release v18.12.4 came out on October 20, 2026.

This guide explains what Oh My Pi is, how it relates to Pi, how to install it, and which features matter most. It is based on the oh-my-pi README, the omp.sh docs, and the omp changelog.

What Oh My Pi is

Oh My Pi, run as omp, is a terminal coding agent. The README calls it “a coding agent with the IDE wired in.” The key facts:

• It is a fork of Pi. It started from Mario Zechner’s Pi and was “rewritten as a coding-first surface.”
• Who builds it. Can Bölük (@can1357) and Stencil Labs.
• License. MIT, with vendored third-party code under its own licenses.
• Stack. TypeScript on Bun, plus a native Rust core. The README puts that core at about 80,000 lines.
• Scale. The README lists 60+ providers, 31 built-in tools, 14 LSP operations, and 28 debugger operations.

Pi and omp share an origin but not a philosophy. Pi skips features like subagents and plan mode and lets you add them. omp’s own tagline is “the Pi you love, with batteries included.”

Pi vs Oh My Pi at a glance

Both are MIT licensed, both are extended with TypeScript, and both read existing agent config like AGENTS.md.

How to install omp

The quickest route on macOS and Linux:

curl -fsSL https://omp.sh/install | sh

If no usable Bun is found, the script downloads a prebuilt binary and checks its SHA-256 before installing it.

Other options from the README:

# Homebrew
brew install can1357/tap/omp

# Bun (the README's recommended route)
bun install -g @oh-my-pi/pi-coding-agent

# Nix
nix profile add github:can1357/oh-my-pi

On Windows, in PowerShell:

irm https://omp.sh/install.ps1 | iex

Add shell completions so model names and flags tab-complete:

# zsh: add to ~/.zshrc
eval "$(omp completions zsh)"

Then start it in your project:

cd /path/to/project
omp

On first run, omp picks up the rules, skills, and MCP servers already on disk (more on that below).

Connect a model

Run /login to sign in with a provider account. The README tags several providers as oauth, including Anthropic, OpenAI Codex, GitHub Copilot, Cursor, and Google Antigravity. It also supports API keys for many more, coding-plan subscriptions such as Kimi Code and Z.AI, and local servers like Ollama, LM Studio, llama.cpp, and vLLM.

The interesting part is model roles. Instead of one model for everything, omp routes work by intent:

• default for normal turns
• smol for cheap subagent work
• slow for deep reasoning
• plan for plan mode
• commit for commit messages and changelogs
• plus vision, task, advisor, and tiny

Pick models with /model, override at launch with --smol, --slow, or --plan, and set defaults in ~/.omp/agent/config.yml:

modelRoles:
  default: spark/minimax-m3

Custom OpenAI-compatible endpoints go in ~/.omp/agent/models.yml. The config also supports fallback chains when a provider hits a rate limit, and stacking several API keys per provider.

The features that matter most

The README lists 21 headline features. These are the ones that change how you work day to day.

Subagents with typed results

The task tool splits a job across workers that run in parallel, optionally in isolated worktrees. Each returns a schema-validated object instead of prose. Press Alt+A to open Agent Hub, where you can read a subagent’s live transcript, send it a steering message, or kill a stuck one without stopping the parent. If you know Claude Code subagents, the idea is similar.

LSP on every write

omp talks to language servers, so renames go through the same path your editor uses and update imports and re-exports. Diagnostics, go-to-definition, and code actions are available to the agent through the lsp tool.

A real debugger

The debug tool drives a DAP session. The README’s examples include attaching lldb to a C binary that segfaults, dlv to a hung Go service, and debugpy to a stuck Python process.

Hashline edits

Instead of retyping the lines it wants to change, the model points at content-hash anchors. If the file changed since it was read, the anchors don’t match and omp rejects the patch. The author’s post The Harness Problem explains the design and reports the benchmark gains the README cites. Those numbers are the project’s own measurements.

An advisor model

Assign a second model to the advisor role and it reads every turn, adding notes, concerns, or blockers inline. It runs with its own context and model.

Code review with a verdict

/review starts reviewer subagents that check a branch, a commit, or uncommitted work. Issues come back ranked P0 to P3 with a confidence score. It plays a similar role to Claude Code’s /code-review and ultrareview.

Much more in the box

A short list of the rest:

• eval runs persistent Python and JavaScript cells that can call the agent’s own tools.
• web_search chains many search providers, and read turns GitHub pages, arXiv PDFs, and docs into Markdown.
• browser and computer drive Chromium and the desktop.
• read pr://1428 reads a GitHub pull request like a file, and conflict://N resolves merge conflicts.
• omp commit splits changes into atomic commits.
• /collab shares a live session through a link.
• omp acp runs omp inside editors that speak the Agent Client Protocol, such as Zed.
• Memory tools (retain, recall, learn) keep project facts between sessions.

Some tools are off by default and turned on in settings, including github, security_scan, generate_image, tts, and the memory tools.

It reads the config you already have

omp reads rules, skills, and MCP servers in their existing format from .claude, .cursor, .windsurf, .gemini, .codex, .cline, .github/copilot, and .vscode. The README names Cursor MDC rules, Cline .clinerules, Codex AGENTS.md, and Copilot applyTo among the formats. If your repo already has a CLAUDE.md, skills, and an MCP setup, you don’t have to port them.

A safety note

The README is explicit: “Opening a repository loads its project inputs by design: settings, extensions, hooks, tools, commands, skills, rules, and project MCP configuration.” That is convenient for your own repos and risky for code you haven’t read. To narrow what loads:

• --no-extensions skips extension discovery.
• --trusted-extension /absolute/path/to/file.ts allows only the extensions you list.
• A YAML overlay passed with --config can set mcp.enableProjectConfig: false to skip the project’s MCP config.

With all its tools turned on, omp can run code, drive a browser, and control your desktop. For unattended or untrusted work, run it in a container or on a remote machine, the same way Pi’s docs recommend.

Should you use Pi or Oh My Pi?

Choose Pi if you want a small, readable core and you enjoy building exactly the workflow you want with extensions and packages.

Choose Oh My Pi if you want subagents, LSP, a debugger, code review, and web tools working on day one, and you’re fine with a much larger tool surface.

Choose Claude Code if you mostly use Claude models and want Anthropic’s permission modes and features like auto mode built in.

All three can run side by side. Orca, an agent development environment, lists both Pi and oh-my-pi among its supported agents, so you can give the same task to omp and Claude Code in separate worktrees and compare the diffs.

Sources

• can1357/oh-my-pi on GitHub (README and changelog)
• omp.sh, the official site and docs
• @oh-my-pi/pi-coding-agent on npm
• The Harness Problem by Can Bölük