Getting the Most Out of Oh My Pi

Oh My Pi — omp on the command line — is a terminal coding agent built by Can Bölük as a ground-up rebuild of the Pi framework. It runs as a single Bun process with a native Rust core for the heavy lifting, drives whatever model provider you have credentials for, and ships an unusually deep toolbox: a real language server, a real debugger, parallel subagents, and an editing strategy designed so the model's patches don't quietly corrupt your files.

This is a practical guide to getting the most out of it — and, at the end, to running it entirely on your own machine against a local DeepSeek V4 Flash model.

What makes it different#

Most coding agents shell out, read text, and hope the model reproduces it faithfully. omp's design leans the other way — toward atomic, verifiable capabilities instead of prose round-trips. It speaks the Language Server Protocol for refactors, the Debug Adapter Protocol for debugging, and anchors every edit to a content hash so a stale read can't clobber a file. It's terminal-first (also usable as an SDK or an ACP server), and it's provider-agnostic by design.

Install & first run#

omp needs Bun ≥ 1.3.14. Pick whichever install path you like:

# one-liner
curl -fsSL https://omp.sh/install | sh

# or Homebrew
brew install can1357/tap/omp

# or Bun (global)
bun install -g @oh-my-pi/pi-coding-agent

Authenticate a provider (any of ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, … work out of the box, or use the built-in credential vault), then point it at a repo:

omp "what does this service do, and where are the tests?"
omp -p "generate a conventional-commit message for my staged changes"   # print mode, exits

Config and state live under ~/.omp/agent/ — config.yml for settings, models.yml for providers, plus sessions, skills, and rules.

Model roles & providers#

omp doesn't have one model — it has roles, and you map each role to whatever model fits. This is the single most useful thing to configure well.

Set a role from the CLI or pin it in config:

omp --model opus                         # one run, fuzzy match
omp --smol haiku --slow opus             # override roles for this session
omp config set modelRoles '{"default":"anthropic/claude-opus-4-5"}'   # persist the default

Providers — including any OpenAI- or Anthropic-compatible endpoint — are declared in ~/.omp/agent/models.yml:

# ~/.omp/agent/models.yml
providers:
  my-openai-compatible:
    baseUrl: "https://api.example.com/v1"
    api: "openai-completions"      # also: anthropic-messages, google-generative-ai, …
    models:
      - id: "some-model"
        contextWindow: 200000

The features that matter#

omp's surface area is large. Rather than list everything, here are the capabilities worth knowing by name — what each is, and when to reach for it. Filter by facet, click any card to expand.

A few of these deserve emphasis:

• Hashline edits are the quiet workhorse. By anchoring edits to per-line content hashes instead of line numbers, omp rejects a patch the moment a file has drifted — omp's own benchmarks report a large jump in edit success on tricky patches and roughly 50–60% fewer output tokens versus reproducing whole lines.
• Snapcompact is a genuinely novel take on context limits: instead of paying a model to summarize old history, it renders the discarded transcript into dense pixel-font images and hands them back for near-verbatim re-reading — instant, local, and free.
• Subagent fanout turns a sequential chore into a parallel one, with each agent isolated in its own git worktree and coordinating over an in-process IRC bus.

CLI essentials#

A handful of flags and subcommands cover most of day-to-day use.

# sessions
omp -c                       # continue the last session
omp -r                       # resume via a picker
omp --no-session "quick q"   # ephemeral, don't save

# control
omp --thinking high          # off · minimal · low · medium · high · xhigh · auto
omp --no-tools               # chat only, no tools
omp --auto-approve           # skip approval prompts (unattended runs)
omp --approval-mode write    # always-ask · write · yolo
omp --plan opus              # set the planner model for plan mode
omp --profile work           # isolated auth/sessions/config

Useful subcommands:

omp models                   # list available models (omp models find <q> to search)
omp config list              # every setting and its current value
omp bench opus gpt-5.2       # compare time-to-first-token and throughput
omp usage                    # provider spend & limits;  omp stats for history
omp commit                   # generate a commit message + update changelogs
omp tiny-models download     # local models for titles/memory (offline, free)
omp worktree                 # list/clear agent-managed git worktrees

Workflows that pay off#

• Incremental development. Stay interactive, keep edits small, and lean on --thinking to dial reasoning up only for the hard parts. Preview patches before they land.
• Big refactors → subagents. Split independent modules across subagents in isolated worktrees; let LSP carry renames across files so references don't break.
• Debugging → DAP. When a bug is about runtime state, let the agent attach a debugger and inspect it instead of sprinkling print statements.
• Cost-aware routing. Cheap model for reads and drafts, strong model for writes and review; fallback chains for resilience.
• Plan → approve → execute for anything risky or multi-step; a budgeted goal for long migrations.
• CI / scripting. omp -p (and --mode json) make omp a one-shot tool you can drop into pipelines — code review, commit messages, release notes.

Power tips & gotchas#

• Match the approval mode to the task. always-ask for high-stakes work, write for balanced day-to-day, yolo only for trusted unattended runs.
• Enable the advisor for review passes, disable it when you want the snappiest iteration — it runs its own turn on its own model.
• Keep sessions private. Transcripts under ~/.omp/agent/sessions/ are plain text; the credential vault is separate.

Running omp 100% locally#

Here's the part that makes omp genuinely fun on a capable Mac: point it at a model running on your own machine, and nothing leaves your laptop. I run antirez/ds4 — a purpose-built Metal inference engine for DeepSeek V4 Flash (a 284B mixture-of-experts model, 13B active) — which serves an OpenAI- and Anthropic-compatible API on 127.0.0.1:8000.

The wiring is three small steps. First, serve the model:

# build once, then serve (loads ~80GB into unified memory)
~/Developer/_infra/ds4/serve.sh        # listens on 127.0.0.1:8000

Second, declare it as a provider and pin it as the default:

# ~/.omp/agent/models.yml
providers:
  ds4:
    baseUrl: "http://127.0.0.1:8000/v1"   # OpenAI-compatible endpoint
    api: "openai-completions"
    auth: "none"
    models:
      - id: "deepseek-v4-flash"
        contextWindow: 1000000
        compat:
          reasoningContentField: "reasoning_content"   # DeepSeek puts CoT here

omp config set modelRoles '{"default":"ds4/deepseek-v4-flash"}'

Third — optional but lovely — a shell wrapper that lazy-starts the server the first time you run omp, so plain omp "just works" without keeping 80GB resident when you're not coding.

The context window trade-off#

DeepSeek V4 Flash supports a one-million-token context. Because its compressed attention keeps the KV cache tiny, that's actually practical on 128GB — the 81GB model is wired no matter what, and context only adds KV on top. Drag the size below to see how it plays out (measured on an M5 Max):

The payoff: a frontier-class coding agent, with full LSP/DAP/subagent tooling, running against a model that never sends a token to the cloud.

Credits & sources#

Oh My Pi is built by Can Bölük (can1357); the local model engine is Salvatore Sanfilippo's ds4. This is a community write-up, not official documentation — verify specifics against the project itself, which moves fast.

Worth reading:

• github.com/can1357/oh-my-pi and omp.sh
• Snapcompact — compaction by rendering history to images
• Hindsight memory integration
• BetterStack's Oh My Pi guide
• antirez/ds4 — DeepSeek V4 Flash on Metal