⚡ OMP Cheat Sheet

Quick Start & Config

Platform	Install
macOS/Linux	`curl -fsSL https://omp.sh/install
Homebrew	brew install can1357/tap/omp
Bun (>=1.3.14)	bun install -g @oh-my-pi/pi-coding-agent
Windows	`irm https://omp.sh/install.ps1

• Launch: omp (TUI) | omp -p "prompt" (One-shot) | omp acp (Editor headless).
• Config Files: Global ~/.omp/agent/config.yml | Project <cwd>/.omp/config.yml | Keys ~/.omp/agent/keybindings.yml.
• TUI Cmds: /settings (UI) | /collab (Live Share) | /model or Alt+M (Swap) | Ctrl+R / Ctrl+O (History/Tools).
• 🚨 GOTCHAS: Local config arrays (disabledProviders) REPLACE globals (no merging). Win Terminal swallows Ctrl+V/Enter -> Use Alt+V/Ctrl+Q. Unknown /commands pass straight to LLM.

State & Sessions

• Data Structure: Append-only JSONL + snapcompact bitmaps. Memory extracts via memory://root.
• Paths: Sessions ~/.omp/agent/sessions/ | Blobs .../blobs/ | DB .../history.db.
• CLI / Chat Cmds:
  • /tree (view branch) | /branch (fork at msg) | /fork (dup session) | /resume (switch).
  • --continue (resume last) | /compact (force zip) | /export [path] (HTML) | /share (E2E link).
• 🚨 GOTCHAS: /export crashes on spaces in path. --no-session breaks fork/export. Crashed /share handlers abort without fallback. Compaction safely respects tool-call boundaries.

Workflows & Modes

• Collab: Host /collab (RW=48b link, RO=32b link). Guest /join <link>. Host isolates guests from mutating cmds (!bash).
• Handoff: /handoff [focus]. Auto-summarizes context -> new session (requires ≥2 msgs).
• RPC: omp --mode rpc (JSONL over stdio). prompt ACKs instantly -> poll for agent_end/prompt_result.
• Approval: tools.approvalMode: yolo|write|always-ask. Override: tools.approval.<tool>: allow|deny. omp acp --yolo = fully unattended.
• 🚨 GOTCHAS: Destructive bash (e.g., rm -rf) prompts EVEN in yolo unless explicitly overridden.

Extensibility & MCP

• MCP: /mcp add -> .omp/mcp.json. Marketplace: omp plugin install <name>. Action: /mcp reload/reauth.
• Extensions: Drop .ts in ~/.omp/agent/extensions/. Use ExtensionAPI (pi.on, pi.registerTool).
• Auth Evals: Env ${VAR:-def} | Shell eval !op read op://key (captures stdout).
• 🚨 GOTCHAS: Missing "type": "http" defaults to stdio (throws err). Sync actions on init throw ExtensionRuntimeNotInitializedError. Unhandled hook exceptions perma-block tools.

Coding & Toolchain

• I/O: read (File/SQL/Zip/URL :10-50) | write (Destructive overwrite!) | find (Fast glob) | search (Regex [PATH#TAG]).
• Compute: bash (Binaries only; NO complex pipes/scripts) | eval (Stateful JS/Py, agent() swarms).
• AST: ast_grep (Find full node $NAME) | ast_edit (Dry-run ops: [{pat:"A", out:"B"}] -> MUST call resolve to apply).
• IDE: lsp (rename, diag, code_actions) | debug (DAP driver).
• 🚨 GOTCHAS: edit tool REQUIRES fresh read #TAG. ast_* metavars must match full AST nodes. NEVER shell out bash grep/find.

Models & Config Precedence

• Key Order: CLI --api-key > models.yml > DB/Broker > .env > Fallback.
• Env Order: Process Bun.env > <cwd>/.env > ~/.omp/agent/.env > ~/.omp/.env > ~/.env.
• Overrides: equivalence.overrides: { proxy/a: canonical }. Disable locally via disabledProviders + path:.
• Local Auto-Discovery: ollama, lm-studio, llama.cpp.
• 🚨 GOTCHAS: Proxied Anthropic tools? Set disableStrictTools: true. apiKey parses as env-var name first, then falls back to literal string.

Customization & Context

• Context Maps: <cwd>/.omp/AGENTS.md (Advisory, walks ancestors) | .omp/RULES.md (Sticky constraints).
• Prompts: APPEND_SYSTEM.md (adds rules) | SYSTEM.md (nukes default).
• Skills: <skills-root>/<name>/SKILL.md (Exec: /skill:<name>).
• 🚨 GOTCHAS: Empty .omp/ dir HALTS ancestor walk! Shadowing: .omp > .claude > .github. Literal templates only (no Handlebars injection).

Agent Swarms & Integrations

• task: Subagents. Fan-out tasks[]. Background via async.enabled. Strict isolated workspaces.
• irc: Agent IPC (send, wait, inbox, list). DMs revive parked agents. Broadcasts (to="all") ignore parked.
• browser: open/run/close. Auto-stealth headless. Use tab.ariaSnapshot() for robust selectors.
• github / web_search / todo / ask: GH PR SQLite cache | Multi-provider search fallback | Strict 1-active-op state tracking | Headless-aborted prompts.
• 🚨 GOTCHAS: Subagents are sync-only (cannot spawn async children). todo payloads completely discarded if ANY validation fails. web_search returns errors as parsable strings, not hard throws.