omp (oh-my-pi): a complete guide to the functions of a CLI agent for coding

omp (a package called oh-my-pi) is an open source (MIT) CLI coding agent, a fork of the Pi project by Mario Zechner, modified by Can Bölük. Positioned as “harness” (bandage around LLM) with batteries included: 31 built-in tools, support for 60+ model providers, integration with LSP and debuggers, subagents, memory between sessions and much more.

As of September 2026, the repository has 27.7 thousand stars and 2.7 thousand forks on GitHub – that is, it is one of the notable players in the coding agent niche like Claude Code, Cursor or Codex CLI, but with an emphasis on maximum functionality and open source.

The kernel is written in Rust (~80,000 lines), the binding is in TypeScript/Bun. It runs on macOS, Linux and Windows natively, without a bridge over the WSL.

## Installation

### macOS

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

For Alpine/musl, separate libstdc++ and libgcc should be added:

apk add libstdc++ libgcc

Through Homebrew

brew install can1357/tap/omp

Through Bun (recommended method)

bun install -g @oh-my-pi/pi-coding-agent

Through Nix

start without installation
nix run github:can1357/oh-my-pi

establish in an active profile
nix profile install github:can1357/oh-my-pi

Windows (PowerShell)

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

Auto Supplements for Shell

omp is able to generate auto-additions on the fly from command metadata so that they never diverge from the real CLI:

# zsh
eval "$(omp completions zsh)"

# bash
eval "$(omp completions bash)"

# fish
omp completions fish > ~/.config/fish/completions/omp.fish

## 31 built-in tools

All instruments live in the same namespace along with read and bash. The active set can be fixed with the --tools read,edit,bash,… flag, and the rarely used ones can be hidden behind xd:// (list – read xd:// command).

### Files and search

• read reads files, directories, archives, SQLite, PDF, laptops, URLs, remote paths over ssh:// and internal :// schemas all through one interface.
• **write* – Creates or overwrites a file, archive entry, or string in SQLite.
• edit – hashline patches: edits are tied to the hash of the content of the line, not to the exact text (more below).
• ast_edit - Structural editing of code via ast-grep with preview before use.
• ast_grep - Structural code queries on 50+ tree-sitter grammars.
• grep – Regular expressions for files, glob masks and internal URLs.
• glob - Mask path search (grep).

Rantai n

• bash is a workspace shell with 46 coreutils utilities, optional PTY and background tasks built into the process.
• eval are Python and JavaScript permanent cells with a common prelude and the ability to call agent tools directly from code.

Working with code

• lsp – Diagnostics, navigation, symbols, renaming, code actions, “raw” LSP queries.
• debug - Debugging session management via DAP: breakpoints, steps, stack, variables.
• security_scan - planning and running native security reviews, including Codex Security cloud scans.

Coordination

• task - parallel launch of subagents, optionally in isolated worktree.
• hub - Messaging with live agents, waiting / canceling background tasks.
• todo - Managing an orderly list of session tasks with phase tracking.
• ask - Structured clarifying questions in interactive mode.

Desktop and web

• browser – Puppeteer tabs on top of headless Chromium, CDP connection to applications or native Chrome via relay.
• computer - permanent JS vs. real desktop: windows, screenshots, native input, accessibility tree, clipboard.
• web_search – one request for several configured search providers with citations of sources.
• github - GitHub CLI operations: repositories, PR, issues, code search, Actions tracking.
• generate_image - Image generation and editing via Gemini, GPT or Grok.
• inspect_image – local image analysis by vision model.
• **tts* - speech synthesis via Grok Voice (five voices, WAV or MP3).

Memory and skill

• checkpoint - recording the state of conversation for subsequent compression and reporting.
• rewind - cropping the research context with a short report saved.
• **retain* - adding stable facts to the memory bank.
• recall - Search by memory bank.
• **reflect* - Synthesis of a response based on the entire memory bank.
• **memory_edit* - Update, delete or recall saved memories by id.
• learn - fixing the reused lesson with optional conversion to managed-skill.
• **manage_skill* – Create, update and remove isolated managed-skills.

Some of the default tools are turned off and enabled by settings: github, security_scan, generate_image, tts, checkpoint, rewind and memory tools (depending on memory.backend). inspect_image is automatically activated if the active model cannot see.

## Key features that highlight omp against other agents

### Executing code with tool calls

Unlike most harnesses, which simply give an agent a Python sandbox, omp runs persistent Python and Bun workers, each of which can call back agent tools via a loopback bridge (read, search, task). For example, an agent can download a CSV via tool.read inside Python and immediately plot a JavaScript graph without leaving the cell.

LSP for each edit

The renaming request goes through workspace/willRenameFiles, which means that the re-exports, barrel files and import aliases will be updated before the file is moved. The agent sees the code just like your IDE.

Real debugger, not print()

For a C binary, the agent connects lldb, reaches a bad pointer and reads the frame. For the hovering Go-service - dlv and bypass gorutins. Python: debugpy with pause and inspection. Most other agents still place print articles instead.

Time-traveling stream rules

The rules sleep until the model does the wrong thing. A regex match interrupts the generation right in the middle of the token, inserts the rule as a system reminder, and restarts from the same place – with no “tax” on the context at each step. Injections outlive the composition of the context.

Complete subagents

The task tool divides the task into several workers, each with its own set of tools, and the result is a failed object according to the scheme, and not a “sheet” of text for parsing. The panel of all live subagents opens on Alt+A (Agent Hub) - there you can read a transcript, send a message, "revive" a suspended worker or kill a suspended one without interrupting the parental session.

The second model - "advisor"

The advisor role is a standalone model that reads each move of the master agent in its own context and inserts notes: a note, a warning, or a hard block. The primary agent sees the note and either corrects or explains why it won't.

Collaboration (collab)

The /collab command puts your live session on the relay server and outputs the link and QR code. A colleague connects with the omp join command from another terminal or simply opens a link in the browser. There is a read-only mode (/collab view) that can be observed but not controlled. All frames are encrypted on the client, relay itself does not see your keys.

Hashlines (edit)

The model points to “anchors” by the hash of the content instead of reprinting the entire strings – there are fewer spacefights and “no line found” cycles. If the file has become obsolete, the anchors will disperse and the patch will be rejected before the file is damaged. According to the developers, this saves 61% of output tokens on the same tasks on Grok 4 Fast.

GitHub as a File System

Instead of separate gh_issue_view, gh_pr_view and so on, PR and issues are simply read as paths: read pr://1428 returns data in the same format as read src/foo.ts.

Memory that the agent oversees

The agent remembers your codebase between sessions: captures facts on the fly through retain, saves reused lessons through learn, lifts them back through recall, and compresses each session into a “mental model” that is loaded on the first move of the next session. The memory engine is selected by setting memory.backend – local, Hindsight or Mnemopi. By default, memory is tied to the project.

ACP - management from the editor

Running omp inside Zed, you get the same agent as in the terminal, but it reads exactly the buffer that is open to you, writes through the regular editor saving mechanism and runs shells in the editor terminal. Destructive operations require permission that can be issued once and forgotten.

Inherit the configures of other agents

omp reads the formats already lying on the disk "as is": Cursor MDC, Cline .clinerules, Codex AGENTS.md, Copilot applyTo and others - without migration scripts. Config, which the team wrote last quarter, will continue to work.

## Prompt controls and slash teams

### Magical words in the Prompt text

Three separate words in lowercase letters switch the behavior of a particular move (they only work in plain text – not in code blocks, XML/HTML and paths):

ultrathink – ask the model for the maximum possible level of “thinking”
orchestrate – drive a substantial amount of independent work through parallel subagents with each phase checked
workflowz – build a deterministic multi-agent workflow through a task tool

Session-level slash teams

/vibe - "director mode": you manage permanent fast/good workbook sessions with read-only toolkit
/fresh – reset the status of the provider stream (obsolete cache of the prompt, suspended stream) without changing the local transcription

Other useful teams

/model – Change the active model in the session
/review – code review with P0–P3 priorities and the verdict to freeze
/debug - debugging, reports and profiling of the omp
/reload-plugins - reboot extensions after editing

## Models and providers: 60+ variants per /model command

omp routs the work in ten roles depending on the intention: default - normal moves, smol - cheap overclocking of subagents, slow - deep reasoning, plan - planning mode, commit - changelogs, plus vision, designer, WKNTOKEN7XN, WKNXNKENXN, WKNKNXN, WKNXNXNXN, WKNXNKNXNXN, WKNKNXNKNXN, WKNKNXNXNXN, WKNKNKNXNKNXNXN, WKNXNXNXN, WKN, WKNKNXNKNKNXNXNKNXN, WKNXNXN You can redefine the role at launch with the --smol, --slow, --plan flags; switch between active role models using Ctrl+P; change the model in the middle of the session with the /model command.

Supported groups of providers:

• Direct APIs and gateways: Anthropic, OpenAI, OpenAI Codex, Google Gemini, Google Vertex, Google Antigravity, xAI, SuperGrok, DeepSeek, Mistral, Groq, Cerebras, Fireworks, Together, Baseten, DeepInfra, Hugging Face, NVIDIA, Meta*, Amazon Bedrock, Azure OpenAI, SiliconFlow, GMI Cloud, CoreWeave, Sakana AI, OpenRouter, Synthe, Vercel Gateway, AI.
• Subscription coding plans: Cursor, GitHub Copilot, GitLab Duo, Devin, Kimi Code, Moonshot, MiniMax Coding Plan (including CN version), Alibaba Coding Plan, Qwen Portal, Z.AI/GLM Coding Plan, Zhipu Coding Plan, Xiaomi MiMo, Qianfan, Umans, NanoGPT, Novita, Venice, Kilo, ZenMux, OpenCode Go, OpenCode Zen.
• **Local launch: Ollama, Ollama Cloud, LM Studio, llama.cpp, vLLM, LiteLLM – via OpenAI-compatible /v1/models.

### OpenAI Compatible Provider

Added to ~/.omp/agent/models.yml:

providers:
  spark:
    baseUrl: http://192.168.10.223:8000/v1
    api: openai-completions
    apiKey: dummy
    models:
      - id: minimax-m3
        name: MiniMax M3
        contextWindow: 100000
        maxTokens: 32000

Check that the provider is visible: omp models spark. Next, omp setup and select the model at the default model setting step, or open /model in the session and assign the default role.

To set the default model without interactive selection, write in ~/.omp/agent/config.yml:

modelRoles:
  default: spark/minimax-m3

Four settings that make routing useful

• Castom providers – any provider speaking openai-completions, openai-responses, openai-codex-responses, azure-openai-responses, anthropic-messages, bedrock-converse-stream, google-generative-ai, google-gemini-cli or google-vertex can be declared.
• Fallback chains - under retry.fallbackChains for a role or a specific model: at 429 or quota focus, the next provider in the chain plays the turn, and the recovery occurs after cooling.
• Path-bound models - enabledModels and disabledProviders can be limited to the path: prefix to anchor your set of models on a single repository without touching the global configuration.
• Round-robin keys - you can add several API keys to one provider, and the rantime will rotate them taking into account the affinity of the session and the backoff for each key - it is useful if one key eats the quota for lunch.

## Web search: 23 backends per tool

web_search is built in, not screwed to the side. The auto mode follows a chain of 23 providers in order; you can pin a specific one by name. Behind each result is extraction taking into account the specifics of the site – GitHub, packet registries, arXiv, Stack Overflow and documentation are converted into a structured markdown with the preservation of anchors and links.

Some providers work without a key at all (duckduckgo, startpage, google, ecosia, mojeek - through a browser), some - via an API key (perplexity, exa, WKNTOKEN7X, WKNTOKEN8X, WKNTOKEN8X, WKNTOKEN9X, WKNTOKNXNX, WKNXNTOKEN, WKNX, WKNKNXNXXXX, WKNXXXN, WKN, WKNKNXXXXXN, WKNXXXN, WKNXXN, WKN, WKNKNKNXNKNKN, and others).

Separately, there are specialized processors:

• Codhostings - GitHub, GitLab
• ** Packet registers** - npm, PyPI, crates.io, Hex, Hackage, NuGet, Maven, RubyGems, Packagist, pub.dev, Go packages
• Scientific sources - arXiv, Semantic Scholar
• Forums - Stack Overflow, Reddit, Hacker News
• ** Documentation** - MDN, Read the Docs, docs.rs
• Vulnerability databases – NVD, OSV, CISA KEV (responses with a link to vendor data, not a retelling of blogs)

## Four ways to run an omp

### Interactive TUI (by default)

Just omp. Tool calls are rendered with cards, edits show previews before use, and ambiguity is resolved through the ask tool - a structured choice of option right in the middle of the turn.

One-time request

omp -p "list .ts files"

Responds to one prompt and completes the work - convenient for scripts and CI.

SDK for embedding in Node

@oh-my-pi/pi-coding-agent package:

import {
  ModelRegistry,
  SessionManager,
  createAgentSession,
  discoverAuthStorage,
} from "@oh-my-pi/pi-coding-agent";

const auth = await discoverAuthStorage();
const models = new ModelRegistry(auth);
await models.refresh();

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage: auth,
  modelRegistry: models,
});
await session.prompt("list .ts files");

RPC over stdio

omp --mode rpc --no-session

Teams come in NDJSON format, and answers and events go back in the same way. --mode rpc-ui adds tool cards, selectors, and dialogs as separate extension_ui_request frames that the host must handle.

ACP - Protocol for Editors

omp acp

Implement Agent Client Protocol over JSON-RPC. When the editor declares support for features, I/O tools go through it, and file writing goes through session/request_permission.

## Configuring the subagent orchestrator (task)

The task tool is the “orchestrater” omp: it spreads the work in parallel subagents, each in its own toolkit and (optional) in its isolated repository. All settings live in the task Config section (~/.omp/agent/config.yml - globally, .omp/config.yml in the project - locally).

### Workspace isolation

The task.isolation.mode key defines how each subagent receives its own copy of files so that parallel edits do not conflict:

task:
  isolation:
    mode: auto   # none | auto | apfs | btrfs | zfs | reflink | overlayfs | projfs | block-clone | rcopy

• none – subagents work directly in the parent’s work directory (without isolation, without the right to work in isolated mode).
• auto - omp chooses the best available backend for the file system (APFS/Btrfs/ZFS clones, reflink, overlayfs on Linux, ProjFS on Windows) and rolls back on the list of candidates if the backend is not available.
• The remaining values are an explicit indication of a specific backend.

The result of the isolated subagent is returned to the parent in one of two ways: patch mode (the patch is captured and applied to the base tree) or branch mode (committed to a separate branch of omp/task/<id> and mixed through cherry-pick). Isolated sessions are not “revived” after completion – they are disposable.

Parallelism and limits

task:
maxConcurrency: 4# How many subagents can work simultaneously
agentIdleTtlMs: 420,000 # after how many ms of downtime (default 7 minutes) the agent "parks"
maxRecursionDepth: 3 # How many nesting levels are subagent → subagent allowed
maxRuntimeMs: 0 # hard timeout per subagent, 0 = no limit
softRequestBudget: 200 # after how many requests the subagent "intended" to end
enableEffort: false # allow you to explicitly set the "effort" level (lo/med/hi) on the spawn
batch: true # allow packet spawn - several subagents at once with one task call

maxConcurrency resolves into a semaphore common to the session: if several task calls fly in parallel, all together they will not exceed this limit. agentIdleTtlMs ≤ 0 disables “parking” – sessions of subagents will hang in memory before leaving the omp.

Your agents instead of the default task

In addition to the general agent task, there are ready-made types: scout, designer, reviewer, security-reviewer, librarian, sonic. Each task call can specify agent: scout and so on for a specific type of work.

Your agent is described by a markdown file with YAML frontmatter in .omp/agents/ (in the project) or ~/.omp/agent/agents/ (globally):

-
name: db-migrator
model: anthropic/claude-opus-4-5
tools: [read, edit, bash, lsp]
adviser: true
-

You're only responsible for database migration. Never touch files outside.
`migrations/` directory. Always dry-run before applying migration.

Agent detection priority - "first found by exact name" wins: first .omp/agents project, then ~/.omp/agent/agents user, then extension-packages omp, then agents from the Claude marketplace, and only then embedded (scout, designer, reviewer, security-reviewer, security-reviewer, WKTXNTOKEN6X, WKNKNXN, WKNXN, WKNK8KNKNKENXN, WKNKNKNKNKNXN, WKNX).

Monitoring and management of subagents

• Alt+A opens Agent Hub - a panel with a list of all live, idle and parked subagents, the status and expense of tokens for each.
• From Agent Hub, you can open the transcript of any subagent, send him a message (steering), “revive” the parked person or kill the hover – without interrupting the parental session.
• The hub tool is software access to the same thing: sending messages to live agents, waiting or canceling background tasks. Writing to an existing (albeit parked) agent is usually more effective than creating a new one – it already holds the right context.
• history://<id> opens a compact transcript of a particular subagent in any instrument receiving a path; agent://<id> opens its final saved output.

Magical words for orchestration without config

Recall from the previous article – this is the fastest way to include orchestration right in the prompt, without editing the config:

orchestrate – drive a substantial amount of independent work through parallel subagents with each phase checked
workflowz – build a deterministic multi-agent workflow through the same task tool

## Setting up an advisor (advisor)

Advisor is the second model connected to the session as a Readonly Reviewer: after each move of the main agent, it reads a fresh piece of transcript (including the model reasoning, not just the text visible to the user) and can insert a note. It doesn’t edit, run commands, and can’t change session state directly—only read, search, find, and a special advise tool.

### How to turn on

You need both conditions at the same time:

modelRoles:
adviser: anthropic/claude-sonnet-4-5:medium # model-advisor + if desired, the level of "reflection"

adviser:
enabled: true

Further, you can manage the advisor directly in the session with slash commands:

/advisor – switch to the saved setting advisor.enabled
/advisor on – enable and run the advisor (if the model is assigned)
/advisor off – turn off and stop the advisor
/advisor status – active model, context, token and money consumption
/advisor dump – copy a compact transcript of the adviser to the buffer
/advisor dump raw – copy the full dump (system prompt, tools, reasoning, calls)

Three levels of notes

The advisor calls the advise tool with text and (optional) severity:

• nit (default, if no level is specified) - an optional note right now is embedded in the transcript at the next natural pause. For details: code simplification, non-critical edge cases.
• **concern* - Interrupting message: something went wrong, the limitation is missed, the model comes up with a non-existent API.
• **blocker* is also interrupting: the continuation will definitely lead to a job loss or a broken result.

concern and blocker actually interrupt the current course of the main agent through the steering channel. So that the advisor does not bombard the agent with interruptions in a circle, there is a setting advisor.immuneTurns (by default 3) - after a successfully delivered interrupt, the next concern / blocker during N moves of the main agent go as usual unobtrusive notes.

Speed synchronization: advisor.syncBacklog

The counselor reads the transcript asynchronously and may lag behind. The setup specifies whether the main agent is willing to wait a bit if the advisor is behind:

adviser:
syncBacklog: "off" # off | 1 | 3 | 5 - the "backlog" threshold, after which the agent waits (up to 30 seconds)

off is the maximum speed of the main agent, the advisor simply does not keep up with the moment. 1 is the closest synchronous review.

WATCHDOG.md - Instructions for Advisor Only

A separate file that only the advisor sees (unlike AGENTS.md/RULES.md, which the primary agent sees). An ideal place for what is important to the auditor, but would make noise to the main performer: what to pay special attention to, what APIs in the project are dangerous, where the architectural boundaries are.

Watchdog notes

Keep an eye out for:

Changes that bypass the durable queue in `src/jobs/`.
UI rendering, which displays unsanned output of tools.
- New workmen who don't go back through the CLI host.

The file is searched in several ways at once (and all found connect together, not just the nearest): ~/.omp/agent/WATCHDOG.md at the user level, and WATCHDOG.md/.omp/WATCHDOG.md at each directory level from the work directory up to the root of the git repository.

Adviser for subagents and by agent

By default, the advisor works only in the main session. To include it and for subagents raised through task:

advisor:
  enabled: true
  subagents: true

Point-by-point – you can specify advisor: true (or a specific model by string, for example, advisor: "deepseek/deepseek-v4-flash") directly in the frontmatter of a specific custom agent, or override this through the setting task.agentAdvisor (the dictionary “agent name → on/off/model”), which comes from the /agents panel.

## Extensibility

omp is built as a set of primitives: an extension is a regular TypeScript module with the same tool API, the same registry of slash commands, and the same hotkey table that use built-in functions. You can ask the omp to write the missing part and load it with the command /reload-plugins, hold it locally, arrange it as marketplace or publish it in npm.

## In Short: What You Need to Know

• omp (oh-my-pi) is an open source (MIT) CLI coding agent, fork of Project Pi, with 31 built-in out-of-the-box tools.
• Supports 60+ providers models and subscription coding plans – from direct APIs to local launch via Ollama/vLLM.
• Out of the box - LSP, real debugger via DAP, structural code edits through ast-grep, memory between sessions and subagents with isolated worktree.
• There is a collaboration mode (/collab), integration with editors via ACP and built-in web search with 23 backends.
• The subagent orchestrator (task) is configured through the task section in the config: workspace isolation, parallelism limit, TTL downtime, their agent types in .omp/agents/. Counselor (advisor) is the second read-only model-reviewer, switched on by the modelRoles.advisor + advisor.enabled: true bundle and receives separate instructions via WATCHDOG.md.
• Installation – one command: curl -fsSL https://omp.sh/install | sh (or via Homebrew, Bun, Nix).

*Source: official github.com/can1357/oh-my-pi repository, omp.sh website. *