Oh My Pi (OMP): Install, Connect Providers, and Start Coding

OMP (Oh My Pi) is a terminal coding agent from Stencil Labs, forked from Mario Zechner's Pi. It keeps Pi's terminal-first workflow and ships a larger built-in surface: built-in subagents, plan and review workflows, and a broader tool set. This guide covers the practical path: install OMP, connect one provider, choose a model, and run a small inspect → change → verify → resume loop.

OMP vs Pi in one minute

Pi is intentionally small. Its core stays lean, and workflow-specific behavior lives in extensions, skills, and prompt templates. OMP starts from that codebase but includes more of the everyday workflow out of the box.

Pi already has provider logins and resumable sessions. If you want the smallest possible harness and plan to assemble the rest yourself, start with Pi. If you want built-in subagents, plan and review workflows, and a larger tool set in one install, OMP is the fork to try.

Before you install

Install OMP

macOS and Linux

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

The installer uses a matching-architecture Bun when it is available and new enough. If Bun is missing or its architecture does not match the host, it fetches the prebuilt binary and checks its SHA-256 before installing it. If a Bun build matching your CPU architecture is installed but older than 1.3.14, the installer stops rather than silently falling back. Upgrade Bun, or force the documented prebuilt path:

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

Windows

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

Homebrew or Bun

# Homebrew
brew install can1357/tap/omp

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

Verify the install

omp --version

omp --version prints a line such as omp/18.12.6.

Optional dependency checks are separate and not required for onboarding: omp setup python --check and omp setup speech --check.

If omp is not found, open a new terminal first. If it still fails, check the installer output for the install directory and add that directory to your PATH.

Start OMP in a project

Start from the repository you want to work in:

cd ~/code/my-app
omp

That opens the interactive terminal UI. To send an opening request immediately, pass it as an argument:

omp "Read README.md and package.json, then explain how this repo is organized. Do not edit files."

Start in the project directory, not your home directory. OMP switches to a temporary directory when launched in ~ unless you pass --allow-home. Do not use --allow-home for normal repository work.

Connect a provider

OMP supports many providers. These four cover the common beginner paths:

For the login-based providers below, run omp login without a provider to open the picker.

Anthropic

Use Anthropic API-key billing. Create a key at platform.claude.com/settings/keys, then export it:

export ANTHROPIC_API_KEY="sk-ant-..."

Put that export in your shell profile if you want it available in every new terminal. For authentication details, see the Claude API overview.

OMP also technically supports omp login anthropic for Claude Pro/Max OAuth. That is a supported software capability, but Anthropic says OAuth is designed for native Anthropic applications and restricts third-party applications that route subscription credentials. For ordinary third-party use, prefer API-key billing. That is a provider-policy distinction, not legal advice; see Anthropic's legal and compliance page.

If you already have a stored Anthropic OAuth login, it takes precedence over ANTHROPIC_API_KEY. To switch to API-key billing, run /logout in an OMP session and relaunch.

OpenAI

The direct OpenAI API provider reads an API key:

export OPENAI_API_KEY="sk-..."

Direct API models are addressed as openai/....

For a ChatGPT Plus/Pro Codex subscription, use the separate openai-codex provider:

omp login openai-codex

Use openai-codex/... models with that login. They are separate providers: a Codex login is not the same credential as an OpenAI API key.

OpenCode Go

Subscribe in the OpenCode Console, copy the API key, then run:

omp login opencode-go

Follow the key prompt. You can also supply the key through the environment:

export OPENCODE_API_KEY="..."

The same OPENCODE_API_KEY variable authenticates both opencode-go and opencode-zen.

Pick a model

List the catalog, or narrow it to one provider:

omp models
omp models anthropic
omp models opencode-go

Model IDs are written as provider/model-id. These examples were valid in OMP 18.12.6:

omp --model anthropic/claude-sonnet-5
omp --model openai-codex/gpt-6-luna
omp --model opencode-go/kimi-k3

Inside a session, /model opens the model selector. By default, Ctrl+P cycles the slow, default, and smol role models; --models customizes that cycle. Alt+M opens role selection. See keybindings.

To choose a default for new sessions, run the setup wizard:

omp setup

Choose the default model in the wizard. You can also pin it in ~/.omp/agent/config.yml:

modelRoles:
  default: anthropic/claude-sonnet-5

New sessions pick up the change. If a model you just unlocked is missing, refresh the catalog:

omp models refresh

A small everyday workflow

1. Inspect the repository

Limit the first pass to a small built-in tool set and make the tour a no-edit request:

omp --tools read,grep,glob --no-extensions "Give me a read-only tour of this repository. Read README.md, the package manifest, and the main entry point. Report how the app starts, where tests live, the documented test command, and three areas a beginner should avoid changing. Do not edit files."

--tools restricts the enabled built-in tools; the edit, write, and bash built-ins are not in this list. --no-extensions disables extension discovery, though explicit -e/--hook loads can still add extensions. Treat this as a scoped request with a limited built-in tool set, not a filesystem or security sandbox.

2. Request a bounded change

Name the file, the acceptance criterion, the boundaries, and the verification step:

omp --approval-mode=always-ask "In src/auth/session.ts, add a 30-second clock-skew allowance to the token-expiry check. Change only that file and its focused test. Do not rename public APIs or refactor unrelated code. Run the focused test and report the exact command and result. If the test cannot run, stop and explain why."

Replace the path and test with real ones from your repository. --approval-mode=always-ask prompts before edits, writes, and executable actions, subject to per-tool policies; ordinary reads do not prompt. The built-in default is yolo. Approval modes are a confirmation layer, not a sandbox. See approvals.

If the agent needs a hint, attach files with @:

omp @src/auth/session.ts @src/auth/session.test.ts "Explain how expiry is checked. Do not edit files."

3. Verify the change yourself

Do not rely on the agent's summary. Inspect the working tree and run the test command yourself:

git status --short
git diff

Run the same focused test the agent reported. If the repository has lint or typecheck scripts, run those too.

4. Resume the session

Sessions are saved by default. From the same project directory, continue the latest session for that project:

omp --continue

Or open the picker and choose a session:

omp --resume

Resume by ID prefix or path when you know which session you want:

omp --resume SESSION_ID

Replace SESSION_ID with the ID prefix or session path.

Inside a session, /resume opens the same picker. For a throwaway run that should not be saved, start with --no-session.

Project instructions

OMP loads project context before the first turn. Start with a repository-root AGENTS.md; OMP also discovers CLAUDE.md and the user-level ~/.omp/agent/AGENTS.md.

Example AGENTS.md:

# Project instructions

- Package manager: pnpm. Do not run npm or yarn.
- Focused test: pnpm test -- path/to/test
- Typecheck: pnpm typecheck
- Read src/app/router.ts and src/lib/config.ts before changing routing or config.
- Do not edit files under src/generated/.

Replace the commands with your repository's real ones. Keep the file short and imperative; it is read at the start of every session.

.omp/AGENTS.md is an optional OMP-specific alternative. At the same level it shadows the root AGENTS.md rather than being concatenated with it. Context-file changes load in a new session (/new) or after a restart. See context files.

Use .omp/RULES.md for short, always-apply constraints that must survive a long conversation. Put durable background and conventions in AGENTS.md.

On-demand skills

Skills are optional folders with a SKILL.md file. OMP loads the name and description at startup, then reads the body only when the skill is used. That keeps a library of procedures available without paying the context cost on every turn.

A project skill lives here:

.omp/skills/release-check/SKILL.md

Example:

---
name: release-check
description: Run the release checklist before tagging a version.
---

1. Run the full test suite.
2. Compare the changelog against merged pull requests.
3. Confirm the version bump and the tag command.
4. Report anything that is still unresolved.

After adding or editing a skill, run /reload-plugins or start a new session before invoking it. Some bundled plugin hooks and tools require a full restart. Then invoke it with /skill:release-check, or ask for it by name. Create a skill only when the same procedure repeats; one-off instructions belong in the prompt or AGENTS.md. See skills.

Troubleshooting

Sources

• OMP README
• OMP quickstart
• OMP CLI reference
• OMP providers
• OMP approvals
• OMP keybindings
• OMP context files
• OMP skills
• OMP sessions
• OpenCode Go plans and endpoints
• Claude API overview
• Anthropic legal and compliance
• OpenAI API quickstart