Usage
omp [options] [@files...] [messages...]
omp <command> [args] [flags]Bare omp opens an interactive session in the current directory. With -p it prints one answer and exits. A subcommand dispatches to that tool instead of launching the agent. Every flag that takes a value also accepts --flag=value. Anything prefixed with @ is treated as a file, even if it sits between flags.
Precedence
CLI flag > env var > ~/.omp/agent/config.yml > built-in default. --api-key overrides everything for that one run and is never persisted; see Providers for how each provider then resolves the key. Most flags have an env-var fallback documented in Environment variables.
Modes
omp speaks five output protocols. Pick one with --mode, or use -p for the most common case (one-shot text).
| Option | Description | Default / notes |
|---|---|---|
--print, -p | One-shot: send the prompt, stream the answer, exit. No TUI. | |
--mode <mode> | Output protocol. | text | json | rpc | acp | rpc-ui |
--export <file> [out] | Render a recorded jsonl session as HTML and exit. Positional out path optional. | |
--allow-home | Permit launching from $HOME without auto-chdir into a temp directory. |
| Mode | Description |
|---|---|
text | Default. Plain text streamed to stdout. Pairs with -p for scripts. |
json | Newline-delimited JSON events on stdout. Stable shape for piping into other tools. |
rpc | JSON-RPC over stdio. Used by the SDK and programmatic clients. |
rpc-ui | Same as rpc with the in-TUI tool-call UI surfaced to the client. |
acp | Agent Client Protocol over stdio. Same wire format as omp acp. |
For rpc, rpc-ui, and acp, see RPC mode and ACP for the wire format and the SDK client.
Models
Pick the active model and the role overrides. For role semantics see Model roles; for credentials and OAuth see Providers.
| Option | Description | Default / notes |
| ------------------------- | ---------------------------------------------------------------------------- | --------------------------------- | ----------------------------------------- | ------------------------------------------ |
| --model <id> | Active model. Fuzzy-matched against the registry (e.g. sonnet, gpt-5-codex). | last used or modelRoles.default |
| --provider <name> | Provider hint. Mostly legacy; —model is enough. | — |
| --smol <id> | Override the smol role for this run (fast/cheap helper tasks). | PI_SMOL_MODEL or settings |
| --slow <id> | Override the slow role (deep reasoning, planning). | PI_SLOW_MODEL or settings |
| --plan <id> | Override the plan role used when plan mode runs. | PI_PLAN_MODEL or settings |
| --models <p1,p2,…> | Comma-separated patterns for role cycling. Each item is “id[:effort]”. | See roles. |
| --list-models [pattern] | Print discovered models and exit. Optional pattern filters the list. | Doubles as an auth probe. |
| --thinking <level> | Reasoning effort. | minimal, low, medium, high, xhigh |
| --api-key <key> | Use this key for authentication. | | r the selected provider for the run only. | Not persisted. See providers. |
Sessions
Resume, fork, and isolate runs. Session UX lives at Sessions; the JSONL format itself is in Session format.
| Option | Description | Default / notes |
| ---------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | --- |
| --continue, -c | Open the most recent session in this directory. | |
| --resume, -r [id\\ | path] | Resume by session id prefix or jsonl path. With no value, opens an interactive picker. | |
| --session <value> | Alias of —resume. | |
| --fork <message-id> | Branch the resumed session from a specific message id. | Use with -r. |
| --no-session | Don’t persist this run to ~/.omp/agent/sessions/. | |
| --session-dir <dir> | Override the directory used for session storage and lookup. | |
| --provider-session-id <id> | Carry an externally issued provider session id through to the model API. | Mostly for integrations. |
| --no-title | Skip the background “generate a title” model call. | |
Tools & extensions
Constrain which built-in tools the model can call, and which extensions, skills, and rules load at startup. --no-extensions and --no-skills are run-scoped — they don’t modify the saved config.
| Option | Description | Default / notes |
| ------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------- | --- |
| --tools <a,b,…> | Allow only these built-in tools. Unknown names warn and are dropped. | See tools. |
| --no-tools | Disable every built-in tool. Plugin tools still load. | |
| --no-lsp | Skip starting language servers for the lsp tool. | |
| --no-pty | Run bash without a PTY. Same as PI_NO_PTY=1. | |
| --extension <path>, -e | Load an extension file. Repeatable. | |
| --hook <path> | Load a hook/extension file. Repeatable; same loader as -e. | |
| --plugin-dir <path> | Treat a directory as a plugin root. Repeatable. | |
| --no-extensions | Disable extension discovery. Also drops explicit -e paths for the run. | |
| --no-skills | Disable skill discovery and loading. | |
| --skills <p1,p2,…> | Comma-separated glob patterns to keep only matching skills. | |
| --no-rules | Disable RULES.md discovery and injection. | |
| --system-prompt <text\\ | @file> | Replace the system prompt. Accepts inline text or an @file path. | |
| --append-system-prompt <text\\ | @file> | Append to the default system prompt instead of replacing it. | |
Output
One-shot output and transcript export. -p reads STDIN into the prompt, so cat README.md | omp -p "Summarise" works without ceremony. --export turns a recorded JSONL session into a standalone HTML page. --allow-home permits launching from $HOME without auto-chdir into a temp directory.
Context
Any positional starting with @ is resolved before the prompt is sent. omp detects images by content, not extension.
-
Text files are decoded as UTF-8 and inlined as
<file name="/abs/path">…</file>blocks at the top of the user message. Files over 5 MB are replaced with a path-only stub. -
Images (PNG/JPEG/WebP/GIF/…) attach as native multimodal parts. Auto-resized when
images.autoResizeis on (the default). Image cap: 25 MB. -
Missing or unreadable files abort the run with a non-zero exit. There is no silent skip.
@filesare not supported in--mode rpcorrpc-ui; pass content through the RPC protocol instead.
Misc
| Option | Description |
|---|---|
--cwd <dir> | Start in this directory (overrides the launch cwd). |
--config <file> | Load an extra config.yml-style overlay for this run. Repeatable. |
--approval-mode <mode> | Override tools.approvalMode for this session: always-ask, write, yolo. |
--auto-approve, --yolo | Auto-approve all tool calls (skip approval prompts). |
--hide-thinking | Hide thinking blocks in TUI output. Display only — does not disable model thinking. |
--help, -h | Print help and the env var / tool reference. |
--version, -v | Print the version and exit. |
Subcommands
A subcommand short-circuits the agent launcher and runs a dedicated tool. Every one accepts --help.
| Command | Description |
|---|---|
acp | Speak Agent Client Protocol over stdio. Used by editor integrations (Zed, Neovim) to embed omp. |
agents | Manage agent definitions. omp agents unpack writes the bundled subagents to ~/.omp/agent/agents/ (or ./.omp/agents/ with —project). |
auth-broker | Run or administer the remote credential vault: serve, token, login, logout, list, import, migrate, status. See Providers. |
auth-gateway | Forward-proxy that injects broker credentials into OpenAI Chat, Anthropic Messages, and OpenAI Responses requests. serve, token, status, check. See Providers. |
commit | Generate a commit message and update CHANGELOG.md from the staged diff. Flags: —push, —dry-run, —no-changelog, —legacy, —context, —model. |
completions | Print a shell completion script for bash, zsh, or fish, generated from the live command metadata. |
config | Read/write settings: list, get, set, reset, path, init-xdg. Source of truth is the settings schema. |
grep | Run the native grep wrapper standalone. Flags: —glob, —limit, —context, —files, —count, —no-gitignore. |
grievances | Inspect the auto-QA tool-issue log written by report_tool_issue. list / clean / push. |
install | Install or link an extension package — local paths route to plugin link, package specs to plugin install. |
join | Join a shared collab session from a link (same as /join). |
plugin | Plugin and marketplace lifecycle: install, uninstall, list, link, doctor, features, config, enable, disable, marketplace, discover, upgrade. |
read | Invoke the read tool from the shell on any path or *:// URI. Useful for archives and tool outputs. |
search (q) | Run web search through the configured provider stack. omp q is the short alias. Flags: —provider, —recency, —limit, —compact. |
setup | Bare omp setup runs the onboarding wizard. omp setup python provisions the Python kernel; omp setup stt provisions speech-to-text. Pass —check to probe without installing. |
shell | Drop into an interactive REPL backed by the same brush-core shell used by the bash tool. Flags: —cwd, —timeout, —no-snapshot. |
ssh | Manage SSH host definitions used by the ssh tool: add, remove, list. |
stats | View usage statistics (cost, premium request counts, tokens) across all sessions. Flags: —summary, —json, —port. |
update | Self-update. Uses bun if available, otherwise pulls a release binary. Flags: —force, —check. |
usage | Show provider usage limits for every authenticated account. Flags: —provider, —redact, —history, —days, —json. |
worktree (wt) | List or clear agent-managed git worktrees under ~/.omp/wt: list, clear. Flags: —all, —dry-run, —json. |
Recipes
# Continue the most recent session here
omp -c
# Pick a session interactively
omp -r
# Resume by id prefix and branch from a specific message
omp -r 1f9d2a --fork msg_8c1e "Try a different approach"
# One-shot, no TUI
omp -p "Summarise CHANGELOG.md since the last release"
# Read-only audit: no edits, no shell, no LSP
omp --tools read,find,search --no-lsp -p "Find dead code in src/"
# Role cycling: sonnet for slow/plan, haiku for smol
omp --models 'sonnet:high,haiku:low'
# Attach files and an image in one shot
omp @prompt.md @screenshot.png "Implement what's drawn"
# Render an old session as standalone HTML
omp --export ~/.omp/agent/sessions/proj/2026-05-01.jsonl out.html
# Pipe stdin: anything on stdin becomes the prompt
git diff | omp "review this diff and flag risky changes"
# JSON event stream for CI
omp --mode json --no-session -p "$PROMPT" > events.jsonl
```\n