omp

https://omp.sh/docs
Admin
omp is a terminal-first coding agent that runs on your machine, talks to any provider, and treats...
Tokens:222,928
Snippets:1,636
Trust Score:4.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Add an MCP server with /mcp add

Source: https://omp.sh/docs/mcp

Starts the guided setup for adding an MCP server. Choose Project to make the server available to everyone in the repository, or User for personal use.

```text
/mcp add

```

--------------------------------

### Inspect and install a plugin with omp plugin list and omp plugin install

Source: https://omp.sh/docs/plugins

Lists installed plugins, previews an install with --dry-run, then installs a specific version. A successful install prints the resolved name and version; start a new omp session to load the plugin's behavior.

```bash
omp plugin list
omp plugin install --dry-run '@scope/plugin@1.2.3'
omp plugin install '@scope/plugin@1.2.3'
omp plugin list

```

--------------------------------

### Start an interactive omp session

Source: https://omp.sh/docs

Run inside a project directory to start an interactive omp session. Requires installation and provider authentication as covered in the Quickstart.

```bash
cd path/to/your-project
omp

```

--------------------------------

### Install a checked-out skill for your user

Source: https://omp.sh/docs/skills

Example of installing a checked-out skill for your user. Creates the target directory and copies the SKILL.md file into it. Keep any files referenced by the playbook in the same postgres/ directory.

```bash
mkdir -p ~/.omp/agent/skills/postgres
cp ./postgres-skill/SKILL.md ~/.omp/agent/skills/postgres/SKILL.md

```

--------------------------------

### Install a skill via a plugin

Source: https://omp.sh/docs/skills

Browse a configured marketplace and install a plugin at user or project scope. After installing, upgrading, or editing a skill, start a new session or run /reload-plugins. Plugin modules, hooks, or tools bundled beside a skill may require a full restart.

```bash
omp plugin discover [marketplace]
omp plugin install --scope user name@marketplace
# or: omp plugin install --scope project name@marketplace

```

--------------------------------

### Example task request for a skill

Source: https://omp.sh/docs/skills

Start with the task you want done; omp matches it to a skill description and loads the playbook.

```text
Review this Postgres migration for locking and rollback risks.

```

--------------------------------

### Install a plugin from a marketplace

Source: https://omp.sh/docs/plugins

Add a marketplace catalog, list available catalogs, discover plugins in the catalog, install a plugin by its full name@marketplace ID with project scope, and list installed plugins. The install command uses --scope project to record the plugin in the nearest project .omp/plugins/installed_plugins.json.

```shell
omp plugin marketplace add anthropics/claude-plugins-official
omp plugin marketplace list
omp plugin discover claude-plugins-official
omp plugin install --scope project plugin-name@claude-plugins-official
omp plugin list

```

--------------------------------

### omp CLI practical examples

Source: https://omp.sh/docs/cli

A set of omp commands demonstrating common workflows: starting a session with additional workspace roots, forking a session, running a bounded one-shot for CI, restricting tools and requiring approval, inspecting and benchmarking models, managing plugins, and checking configuration. If a command rejects an action or flag, run `omp <command> --help` for help generated from the current command registry.

```bash
# Start in another directory with an additional workspace root
omp --cwd apps/web --add-dir packages/ui "Fix the broken component test"

# Resume a session and keep the result as a separate fork
omp --fork 01JZ8Y2A "Try the smaller design"

# Bounded one-shot run for CI
omp -p --mode json --no-session --max-time 10m \
  "Check whether generated files are current" > omp-events.jsonl

# Restrict the session and require approval for writes
omp --tools read,grep,glob --approval-mode write \
  "Audit the migration without changing files"

# Inspect available models, then benchmark two choices
omp models find sonnet
omp bench sonnet gpt-5.6 --runs 3

# Manage a project-scoped marketplace plugin
omp plugin marketplace add https://example.com/marketplace.json
omp plugin install widget@example --scope project
omp plugin list

# Check configuration and storage without applying destructive work
omp config get defaultThinkingLevel
omp gc --json
omp worktree clear --dry-run
```

--------------------------------

### Verify debug adapter availability with command -v

Source: https://omp.sh/docs/debugging

After installing an adapter, check that the process starting omp can resolve it. The example checks for dlv and lldb-dap.

```shell
command -v dlv
command -v lldb-dap

```

--------------------------------

### Install the SDK package

Source: https://omp.sh/docs/sdk

Install the @oh-my-pi/pi-coding-agent package using Bun. Requires Bun 1.3.14 or newer.

```bash
bun add @oh-my-pi/pi-coding-agent

```

--------------------------------

### Start a one-off development session with omp --extension

Source: https://omp.sh/docs/extension-authoring

Run this from the directory containing hello-extension to start a development session. The -e flag is the short form.

```bash
omp --extension ./hello-extension
# -e is the short form

```

--------------------------------

### Start Vibe mode with a task in the same command

Source: https://omp.sh/docs/vibe

Use /vibe followed by the task description to start Vibe mode and delegate the work immediately.

```plaintext
/vibe Split this release into independent workstreams. Have a fast worker update the mechanical call sites and a good worker review the migration and compatibility risks. Verify both before reporting done.

```

--------------------------------

### /loop command examples

Source: https://omp.sh/docs/modes

Shows the /loop command with various forms: unlimited loop, loop with a prompt, loop with a count limit, and loop with a duration limit. The first example enables an unlimited loop and the next normal prompt becomes the repeated prompt. The second example starts an unlimited loop immediately with the given prompt. The third example allows 5 automatic re-submissions after the first turn. The fourth and fifth examples stop re-submitting when the wall-clock deadline expires.

```text
/loop
Fix the next failing test. If the suite is clean, explain that and stop.

/loop 5 Review the next unreviewed migration
/loop 30m Process the next item in the queue
/loop 1h30m Check the next repository and record the result
/loop 10 minutes Re-run the acceptance check

```

--------------------------------

### Install plugin by catalog ID in shell

Source: https://omp.sh/docs/marketplace

Shell equivalent for installing a plugin. The --scope flag sets the installation scope; the default is user.

```text
omp plugin install name@marketplace --scope project

```

--------------------------------

### Start auth broker

Source: https://omp.sh/docs/secrets

On the broker host, log in and start the loopback-only service. The default bind is 127.0.0.1:8765.

```bash
omp auth-broker login anthropic
omp auth-broker serve

```

--------------------------------

### Add a marketplace and install an extension from it

Source: https://omp.sh/docs/extension-authoring

After pushing the marketplace repository, users add it with omp plugin marketplace add and install the extension with omp plugin install. The extension is referenced as hello-extension@acme-extensions.

```bash
omp plugin marketplace add acme/omp-extensions
omp plugin install hello-extension@acme-extensions

```

--------------------------------

### Prompt to start omp with repository instructions

Source: https://omp.sh/docs/context-files

Use this prompt to start omp anywhere inside the repository and ask it to follow the repository instructions. The AGENTS.md file is loaded automatically, so you can reference it naturally in your request.

```text
Fix the failing invoice test and follow the repository instructions.

```

--------------------------------

### Install an extension from a Git repository

Source: https://omp.sh/docs/extension-authoring

A public repository can be installed without a marketplace using omp install with a github: prefix. Use an immutable tag or commit for reproducible installs.

```bash
omp install github:acme/hello-extension#v1.0.0

```

--------------------------------

### Add, browse, and install a plugin from a marketplace

Source: https://omp.sh/docs/marketplace

Adds the anthropics/claude-plugins-official marketplace, lists its entries, and installs a plugin at project scope. The explicit install command is needed for project scope; the interactive TUI defaults to user scope.

```shell
/marketplace add anthropics/claude-plugins-official
/marketplace
/marketplace install --scope project <plugin>@claude-plugins-official

```

--------------------------------

### Install plugin with feature selector

Source: https://omp.sh/docs/plugins

Installs a plugin with a feature selector. Quote the selector at install time. No brackets uses the plugin's defaults; [*] enables every declared feature and [] enables none of the optional features.

```bash
omp plugin install '@scope/plugin[search,web]'
omp plugin install '@scope/plugin[*]'
omp plugin install '@scope/plugin[]'

```

--------------------------------

### Install plugin by catalog ID in TUI

Source: https://omp.sh/docs/marketplace

Install a plugin using the catalog ID format name@marketplace. The --scope flag sets the installation scope; the default is user.

```text
/marketplace install --scope project name@marketplace
/marketplace install --scope user name@marketplace

```

--------------------------------

### Start a plan with /plan and a prompt

Source: https://omp.sh/docs/plan

Use this command to begin planning a change. The prompt should state the goal and any constraints that affect the design. The planning turn is read-only with respect to the working tree and system.

```text
/plan Replace the in-memory job queue with Postgres. Preserve the public API, include a rollback path, and call out every migration step.

```

--------------------------------

### Install the Node adapter for Streamable HTTP

Source: https://omp.sh/docs/mcp-authoring

Install the @modelcontextprotocol/node package to host an MCP server over Streamable HTTP from a Node.js endpoint.

```bash
npm install @modelcontextprotocol/node

```

--------------------------------

### /security cloud start --repo-id <id> --repo-url <url> --environment <id> [--lookback <days|all>] [--credential <id>]

Source: https://omp.sh/docs/slash

Starts a cloud scan and consumes cloud scan allowance.

```APIDOC
## /security cloud start --repo-id <id> --repo-url <url> --environment <id> [--lookback <days|all>] [--credential <id>]

### Description
Starts a cloud scan and consumes cloud scan allowance.

### Method
CLI Command

### Endpoint
/security cloud start

### Parameters
#### Options
- **--repo-id** (string) - Required - Repository ID.
- **--repo-url** (string) - Required - Repository URL.
- **--environment** (string) - Required - Environment ID.
- **--lookback** (string) - Optional - Lookback period in days or 'all'.
- **--credential** (string) - Optional - Credential ID.

### Response
Starts cloud scan and returns configuration ID.
```

--------------------------------

### Enable GitHub capability with gh auth and omp config

Source: https://omp.sh/docs/github

Install and authenticate the GitHub CLI, then enable the GitHub capability in omp. `github.enabled` is off by default; start a new session after enabling if the capability is unavailable in an already-running session.

```bash
gh auth login
gh auth status
omp config set github.enabled true

```

--------------------------------

### Magic keyword usage examples

Source: https://omp.sh/docs/magic-keywords

Shows three example prompts, each using a different magic keyword: ultrathink, orchestrate, and workflowz. The keyword is placed as a standalone word at the start of the prompt to steer the behavior for that turn.

```text
ultrathink about the failure modes before changing this public API

orchestrate the migration across the server, client, and tests

workflowz perform an adversarial review of authentication, authorization, and session handling
```

--------------------------------

### Minimal plan mode configuration in config.yml

Source: https://omp.sh/docs/plan

Persistent setup enabling plan mode and setting the plan role model. Plan mode is enabled by default but does not start automatically; the plan role model is used while planning.

```yaml
plan:
  enabled: true
  defaultOnStartup: false

modelRoles:
  plan: anthropic/claude-opus-4-5:high

```

--------------------------------

### Install MCP server SDK and Zod

Source: https://omp.sh/docs/mcp-authoring

Install the current TypeScript server SDK and Zod in your project.

```bash
npm install @modelcontextprotocol/server zod

```

--------------------------------

### Install omp on Windows (PowerShell)

Source: https://omp.sh/docs/quickstart

Downloads and runs the official omp installer in PowerShell on Windows.

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

```

--------------------------------

### Install a local plugin with omp plugin install and omp plugin link

Source: https://omp.sh/docs/plugins

Shows that omp plugin install and omp plugin link are equivalent for a local plugin under development. Source edits remain visible through the symlink, but a running session still needs a reload or restart before every changed capability is active.

```bash
omp plugin install ./my-plugin
omp plugin link ./my-plugin

```

--------------------------------

### Start goal mode with a guided objective

Source: https://omp.sh/docs/goal

Use /guided-goal with a rough objective to have omp ask clarifying questions, turn your answers into a concrete objective, and then start goal mode. With plain /goal, omit the objective to open a multiline editor.

```plaintext
/guided-goal I need to make authentication safer before launch

```

--------------------------------

### Generate and install shell completions for zsh, bash, and fish

Source: https://omp.sh/docs/cli

Add the appropriate line to your shell startup file or install the fish completion once. After adding, restart the shell or source its startup file, then type `omp ` and press Tab to verify.

```shell
# zsh: add to ~/.zshrc
eval "$(omp completions zsh)"

# bash: add to ~/.bashrc
eval "$(omp completions bash)"

# fish: install once
omp completions fish > ~/.config/fish/completions/omp.fish

```

--------------------------------

### Install the hook as a plugin with omp install

Source: https://omp.sh/docs/hooks

Installs the hook package as a plugin. The second command shows the `-l` flag for project scope instead of user scope.

```bash
omp install ./force-push-guard
# Project scope instead of user scope:
omp install -l ./force-push-guard

```

--------------------------------

### Install Browser Relay extension

Source: https://omp.sh/docs/web

Installs the OMP Browser Relay extension locally. Run once before enabling the relay in Chrome.

```bash
omp browser-relay install

```

--------------------------------

### Start Browser Relay with token

Source: https://omp.sh/docs/web

Starts the relay with a token for protection. The extension must be configured with the same token. Use a password manager or environment-safe launcher rather than committing the token to a repository.

```bash
omp browser-relay --token 'a-long-random-secret'

```

--------------------------------

### Start omp and work

Source: https://omp.sh/docs/sessions

Start omp normally in a working directory. Work is saved automatically; there is no Save command.

```bash
cd ~/work/api
omp

```

--------------------------------

### Run /login to start provider login

Source: https://omp.sh/docs/secrets

Starts the interactive login flow. Choose a provider and complete the browser or API-key prompt. After success, omp names the account and prints the credential path.

```text
/login

```

--------------------------------

### Run prewalk with slow planner and smol implementer

Source: https://omp.sh/docs/prewalk

Starts a session with the @slow model and arms prewalk to hand off to @smol after planning. The conversation, context, todos, and changes stay in the same session.

```bash
omp --model @slow --prewalk-into @smol
```

--------------------------------

### Good focus instructions for /handoff

Source: https://omp.sh/docs/handoff

These are examples of good focus instructions that name the work that must survive the reduction. They are shown as separate examples in the source.

```plaintext
/handoff Preserve the test failure, hypotheses ruled out, and the next two debugging steps.

```

```plaintext
/handoff Emphasize the approved API shape and unresolved compatibility risk.

```

--------------------------------

### Verify and select a model with omp models and --model

Source: https://omp.sh/docs/providers

Lists available models for a provider and launches omp with a specific model. Copy a selector from the models output if the example model has changed. In an existing session, use /model or /model provider/model-id instead.

```bash
omp models openai-codex
omp --model openai-codex/gpt-5.5

```

--------------------------------

### Link a local extension with omp plugin link

Source: https://omp.sh/docs/extension-authoring

Use this to link the package into your user plugin set. The equivalent for a local path is omp install ./hello-extension.

```bash
omp plugin link ./hello-extension
# Equivalent for a local path:
omp install ./hello-extension

```

--------------------------------

### Launch omp in a project

Source: https://omp.sh/docs/files

Start omp in the project directory you want to inspect.

```bash
cd my-project
omp

```

--------------------------------

### Start /collab with alternate relay: /collab relay.example.com

Source: https://omp.sh/docs/collab

Starts sharing with a one-time alternate relay. A hostname without a scheme uses secure WebSocket (wss://).

```text
/collab relay.example.com

```

--------------------------------

### Launch omp from the project root

Source: https://omp.sh/docs/custom-tools

Starts omp from the project root so tool discovery can find the custom tool. Tool discovery happens when a session starts, so exit any running session first.

```bash
omp

```

--------------------------------

### Example session tree output

Source: https://omp.sh/docs/session-tree

Example output of the /tree command showing the active path (token refresh) and an alternative branch (cache check). The bullets mark the active path.

```plaintext
• You: Investigate the failing build
  • Assistant: The failure starts in authentication
    ├─ • You: Patch the token refresh path
    │    • Assistant: Tests now pass
    └─ You: First check whether the cache is stale
         Assistant: The cache is healthy

```

--------------------------------

### Keybindings YAML example

Source: https://omp.sh/docs/keybindings

Example of the keybindings.yml file. Maps exact action IDs to a single chord, an array of chords, or an empty array. A remap replaces the action's complete default list; an empty array disables the action.

```yaml
# ~/.omp/agent/keybindings.yml
app.model.cycleForward: f6
app.plan.toggle: f7
tui.editor.undo: [ctrl+-, ctrl+_]
app.history.search: []

```

--------------------------------

### Install omp on macOS or Linux

Source: https://omp.sh/docs/quickstart

Downloads and runs the official omp installer script via curl. Run in a terminal on macOS or Linux.

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

```

--------------------------------

### omp MCP server config (.omp/mcp.json)

Source: https://omp.sh/docs/mcp-authoring

Add this project config to connect the hello server to omp. The server runs via node with the given args, and the child process starts in the project directory unless cwd is set.

```json
{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "hello": {
      "type": "stdio",
      "command": "node",
      "args": ["./mcp/hello-server.mjs"]
    }
  }
}

```

--------------------------------

### Enable Security Tool via CLI

Source: https://omp.sh/docs/security

Run this command to enable the security tool for the next launch or scripted setup.

```shell
omp config set security.enabled true
```

--------------------------------

### Enable or disable a plugin in project scope (TUI commands)

Source: https://omp.sh/docs/marketplace

Use these TUI commands to enable or disable a plugin in the project scope. The project installation shadows the user installation of the same name@marketplace. A disabled project installation does not shadow the user copy.

```plaintext
/plugins disable --scope project name@marketplace
/plugins enable --scope project name@marketplace

```

--------------------------------

### Project settings in .omp/config.yml

Source: https://omp.sh/docs/settings

Create .omp/config.yml in the exact directory where you launch omp. This example shows setting a default model role, disabling providers, and enabling compaction with a threshold.

```yaml
# <repo>/.omp/config.yml
modelRoles:
  default: anthropic/claude-sonnet-4-5

disabledProviders:
  - ollama

compaction:
  enabled: true
  thresholdPercent: 80

```

--------------------------------

### Verify goal configuration with omp config get

Source: https://omp.sh/docs/goal

Shell commands to check the effective values of goal.enabled, goal.statusInFooter, and goal.continuationModes.

```shell
omp config get goal.enabled
omp config get goal.statusInFooter
omp config get goal.continuationModes

```

--------------------------------

### Record value parsing example

Source: https://omp.sh/docs/settings

Record settings are parsed as JSON, for example `omp config set providers.maxInFlightRequests '{"anthropic":2}'`.

```shell
omp config set providers.maxInFlightRequests '{"anthropic":2}'
```

--------------------------------

### Array value parsing example

Source: https://omp.sh/docs/settings

Array settings are parsed as JSON, for example `omp config set disabledProviders '["ollama"]'`.

```shell
omp config set disabledProviders '["ollama"]'
```

--------------------------------

### Install a published extension by npm name

Source: https://omp.sh/docs/extension-authoring

Users install a published package by its npm name using omp install. The package manager installs dependencies and reads omp.extensions from the published package.json. Start a new omp session after installing or upgrading an extension module.

```bash
omp install @acme/hello-extension

```

--------------------------------

### Example MCP server definition in .omp/mcp.json

Source: https://omp.sh/docs/mcp

Shows the JSON structure for defining an MCP server in an omp-managed configuration file. The example uses the stdio transport with a command and optional arguments. Use this shape when adding a server to `.omp/mcp.json`, `~/.omp/agent/mcp.json`, or a named profile file.

```json
{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-example"],
      "env": { "EXAMPLE_VAR": "value" },
      "cwd": "/path/to/project"
    }
  }
}
```

--------------------------------

### Example description for Vitest tests

Source: https://omp.sh/docs/skills

A useful description names actions, objects, and boundaries. This example describes when to use the skill for Vitest tests in src/importer.

```markdown
description: Use when adding or reviewing Vitest tests in src/importer; covers fixtures, snapshots, and integration setup.

```

--------------------------------

### AGENTS.md example with project instructions

Source: https://omp.sh/docs/context-files

Place this AGENTS.md in your repository root to give omp durable project instructions. It includes build/test commands and conventions that omp loads automatically, so you don't need to repeat them in every prompt. Keep it short and concrete because every loaded instruction consumes context.

```markdown
# Project instructions

## Build and test
- Install dependencies with `bun install`.
- Run unit tests with `bun test`.
- Run the app with `bun run dev`.

## Conventions
- Keep public API changes backward compatible.
- Never edit generated files under `src/generated/`.
- Before finishing, run the narrowest test that covers the change.

```

--------------------------------

### /security scan [<plan-id>|options]

Source: https://omp.sh/docs/slash

Starts an existing security scan plan (secplan_...) or creates a new plan from the same options and starts it. Prints scan and operation IDs.

```APIDOC
## /security scan [<plan-id>|options]

### Description
Starts an existing security scan plan or creates a new plan from the same options and starts it.

### Method
CLI Command

### Endpoint
/security scan

### Parameters
#### Path Parameters
- **plan-id** (string) - Optional - ID of an existing plan (secplan_...).

#### Options
- **--path** (string) - Repeated - Path to include in the scan.
- **--exclude** (string) - Repeated - Path to exclude from the scan.
- **--knowledge-base** (string) - Repeated - Path to a knowledge base.
- **--working-tree** (flag) - Optional - Use the working tree.
- **--diff** (string) - Optional - Specify base and head for diff.
- **--output** (string) - Optional - Output directory.
- **--archive-existing** (flag) - Optional - Archive existing artifacts.
- **--credential** (string) - Optional - Credential ID.

### Response
Prints scan and operation IDs.
```

--------------------------------

### Deep-merge and replacement example

Source: https://omp.sh/docs/settings

Shows how mappings deep-merge and scalars/arrays replace. In the project, statusLine.preset remains default, transparent becomes true, and disabledProviders becomes exactly [groq].

```yaml
# global
statusLine:
  preset: default
  transparent: false
disabledProviders: [anthropic, openai]

# project
statusLine:
  transparent: true
disabledProviders: [groq]

```

--------------------------------

### Start omp with always-ask approval mode

Source: https://omp.sh/docs/files

Use this command to start omp in a session that pauses before workspace writes and commands. This mode permits read-only inspection automatically and requests confirmation for writes and command execution.

```bash
omp --approval-mode always-ask

```

--------------------------------

### WATCHDOG.md review priorities example

Source: https://omp.sh/docs/advisor

Example content for a WATCHDOG.md file that gives reviewer-only guidance. Lists specific concerns such as bypassing the durable queue, unescaped user-controlled text, schema changes without backwards compatibility, and unsupported success claims. Keep it specific enough to change a review decision.

```markdown
# Review priorities

Especially watch for:

- Writes that bypass the durable queue in `src/jobs/`.
- User-controlled text rendered without escaping.
- Schema changes without a backwards-compatible rollout.
- Claims of success that are not supported by a focused runtime check.

```

--------------------------------

### Test marketplace consumer workflow commands

Source: https://omp.sh/docs/marketplace

Commands to test the exact consumer workflow locally before publishing: add the marketplace, discover it, install a plugin, and reload plugins.

```bash
/marketplace add ./my-marketplace
/marketplace discover my-marketplace
/marketplace install --scope project my-plugin@my-marketplace
/reload-plugins

```

--------------------------------

### Create the .omp/tools/hello directory

Source: https://omp.sh/docs/custom-tools

Creates the directory for the custom tool source file. Run from the project root.

```bash
mkdir -p .omp/tools/hello

```

--------------------------------

### Add an extension path to user config

Source: https://omp.sh/docs/extension-authoring

For a package you do not want to install, add its absolute path to the user config. A relative configured path is resolved from the directory where omp starts, not from the config file.

```yaml
# ~/.omp/agent/config.yml
extensions:
  - /absolute/path/to/hello-extension

```

--------------------------------

### Check omp version

Source: https://omp.sh/docs/quickstart

Confirms the omp executable is available after installation.

```bash
omp --version

```

--------------------------------

### /force command examples

Source: https://omp.sh/docs/modes

Shows the /force command with both accepted spellings: /force read and /force:read. Both force the next model call to invoke the 'read' tool once. With no inline prompt, the force applies to the next prompt you submit.

```text
/force read Inspect package.json and summarize its scripts
/force:read Inspect package.json and summarize its scripts

```

```text
/force read

```

--------------------------------

### Inspect a named profile without entering a session

Source: https://omp.sh/docs/settings

Use the profile flag before the subcommand to inspect a named profile's settings without starting a session. The examples show checking the config path, listing settings, and setting a theme for the 'work' profile.

```bash
omp --profile work config path
omp --profile work config list
omp --profile work config set theme.dark titanium

```

--------------------------------

### Launch build/server with --config and break in parseConfig

Source: https://omp.sh/docs/debugging

Asks omp to launch a server binary with a configuration file, stop in the parseConfig function, and show arguments and the first caller that supplied an empty path.

```text
Launch build/server with --config test/fixtures/dev.toml. Stop in parseConfig,
then show me the arguments and the first caller that supplied an empty path.

```

--------------------------------

### Oversized logical stdout object as rpc_chunk frames

Source: https://omp.sh/docs/rpc

Example of an rpc_chunk frame used in v2 for oversized logical stdout objects. The sequence must be validated: chunkId unchanged, index starts at 0 and increments, count/byteLength/chunkId match, no ordinary frame interrupts, decoded bytes do not exceed maxReassembledFrameBytes, and concatenated bytes parse as one JSON object.

```json
{"type":"rpc_chunk","chunkId":"rpc-1","index":0,"count":2,"byteLength":1200000,"data":"BASE64_DATA"}
```

--------------------------------

### Execute with progress and cancellation

Source: https://omp.sh/docs/custom-tools

Example execute implementation that sends a progress update, runs a git status command via pi.exec with the session working directory and signal, and returns the output or throws an error on failure.

```javascript
async execute(_id, params, onUpdate, _ctx, signal) {
  onUpdate?.({
    content: [{ type: "text", text: `Checking ${params.path}…` }],
  });

  const result = await pi.exec("git", ["status", "--short", "--", params.path], {
    cwd: pi.cwd,
    signal,
  });

  if (result.code !== 0) {
    throw new Error(result.stderr || "git status failed");
  }

  return { content: [{ type: "text", text: result.stdout || "No changes" }] };
}
```

--------------------------------

### Create and invoke a prompt template with arguments

Source: https://omp.sh/docs/prompt-templates

Create a prompt template file and invoke it as a slash command. The filename creates the command name, and the frontmatter description appears in autocomplete. The template uses $1 and $@[2:] to capture arguments.

```markdown
---
description: Review one area of this project for correctness
---

Review the code related to $1.

Focus on: $@[2:].

Report concrete findings first, with file and line references. Then list any
remaining risks or missing tests. Do not change files.

```

```text
/review-change authentication "error handling and tests"

```

--------------------------------

### Launch ./build/repro with lldb-dap and break at decode_packet

Source: https://omp.sh/docs/debugging

Asks omp to launch a repro binary with lldb-dap, stop at main, continue to decode_packet, and inspect the packet header.

```text
Use lldb-dap to launch ./build/repro with arguments --seed 417. Stop at main,
then continue until decode_packet and inspect the packet header.

```

--------------------------------

### Enable Browser Relay with omp config set browser.relay true

Source: https://omp.sh/docs/web

Enables the relay in OMP settings. The local relay server starts automatically when first needed.

```bash
omp config set browser.relay true

```

--------------------------------

### Run commands with arguments and subcommands

Source: https://omp.sh/docs/slash

Arguments follow the command after a space, and command families take a subcommand first. Examples: /rename investigate checkout timeout, /usage reset active, /mcp test github.

```plaintext
/rename investigate checkout timeout
/usage reset active
/mcp test github
```

--------------------------------

### Verify effective compaction settings with omp config get

Source: https://omp.sh/docs/compaction

Shell commands to verify the effective values of compaction settings from the shell. Run these to confirm the current configuration.

```shell
omp config get compaction.enabled
omp config get compaction.methodOrder
omp config get compaction.thresholdPercent

```

--------------------------------

### List, uninstall, and upgrade plugins in shell

Source: https://omp.sh/docs/marketplace

Shell equivalents for listing, uninstalling, and upgrading plugins.

```text
omp plugin list
omp plugin uninstall name@marketplace --scope project
omp plugin upgrade name@marketplace --scope project

```

--------------------------------

### OAuth client registration settings

Source: https://omp.sh/docs/mcp

Add only the settings the provider requires when it needs a registered client. The example shows the `acme` server with `type: http` and a URL, with no token included so OAuth can run.

```json
{
  "mcpServers": {
    "acme": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

```

--------------------------------

### Skill directory structure with supporting files

Source: https://omp.sh/docs/skills

Shows the recommended layout for a skill directory, with SKILL.md, references, and scripts. Supporting files do not execute automatically; the playbook must explain when and how to use them.

```text
release-check/
├── SKILL.md
├── references/
│   └── registry-checks.md
└── scripts/
    └── verify-artifacts.sh

```

--------------------------------

### Security scan plan and scan commands

Source: https://omp.sh/docs/security

Run a narrow security scan: first freeze the scope with /security plan and then start the review with /security scan using the returned plan ID. Works best when you need deterministic plan and scan IDs.

```shell
/security plan --path src/auth --exclude src/auth/fixtures --knowledge-base SECURITY.md
/security scan secplan_…
```

--------------------------------

### Start view-only /collab with alternate relay

Source: https://omp.sh/docs/collab

Starts sharing with a view-only link through the specified alternate relay.

```text
/collab view relay.example.com

```

--------------------------------

### Pass arguments to a prompt template

Source: https://omp.sh/docs/prompt-templates

Shows how arguments are passed to a prompt template. Spaces and tabs separate arguments; matching quotes keep text together and are removed. This example demonstrates the argument syntax used with the template.

```text
/review-change payments "retry behavior" tests

```

--------------------------------

### Minimal stdio MCP server (mcp/hello-server.mjs)

Source: https://omp.sh/docs/mcp-authoring

Save this as mcp/hello-server.mjs. It creates an MCP server named 'hello' with a 'greet' tool that takes a name and returns a text message. Do not print logs to stdout; use stderr for diagnostics.

```javascript
import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
import * as z from "zod/v4";

const server = new McpServer({
  name: "hello",
  version: "1.0.0",
});

server.registerTool(
  "greet",
  {
    description: "Greet one person by name.",
    inputSchema: z.object({
      name: z.string().min(1).describe("The person's name"),
    }),
  },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
  }),
);

await server.connect(new StdioServerTransport());

```

--------------------------------

### Good focus text examples

Source: https://omp.sh/docs/review

Examples of focus text that name a failure boundary rather than asking for generic quality.

```text
/review focus on backward compatibility of the persisted session format
/review focus on authorization checks after redirects
/review focus on partial writes, retries, and idempotency

```

--------------------------------

### Equivalent wrapped and flat server configurations

Source: https://omp.sh/docs/code-intelligence

Shows two equivalent forms of LSP configuration: one with a top-level 'servers' wrapper and one with flat server entries. The 'servers' wrapper is optional, but mixing wrapped and flat entries is not allowed.

```json
{
  "servers": {
    "eslint": { "disabled": true }
  },
  "idleTimeoutMs": 300000
}
```

```yaml
eslint:
  disabled: true
idleTimeoutMs: 300000
```

--------------------------------

### Create and install custom theme 'ink'

Source: https://omp.sh/docs/themes

Creates the theme directory and saves the minimal 'ink' theme JSON file. The JSON defines color variables, semantic color mappings, and symbol presets. After saving, select 'ink' in /settings for Dark Theme; restart omp if the name does not appear.

```bash
mkdir -p ~/.omp/agent/themes

```

```json
{
  "name": "ink",
  "vars": {
    "fg": "#e6edf3",
    "muted": "#8b949e",
    "dim": "#6e7681",
    "accent": "#79c0ff",
    "green": "#56d364",
    "red": "#ff7b72",
    "yellow": "#e3b341",
    "purple": "#d2a8ff",
    "panel": "#161b22",
    "selected": "#26364a",
    "border": "#30363d"
  },
  "colors": {
    "accent": "accent",
    "border": "border",
    "borderAccent": "accent",
    "borderMuted": "border",
    "success": "green",
    "error": "red",
    "warning": "yellow",
    "muted": "muted",
    "dim": "dim",
    "text": "fg",
    "thinkingText": "muted",

    "selectedBg": "selected",
    "userMessageBg": "panel",
    "customMessageBg": "panel",
    "toolPendingBg": "panel",
    "toolSuccessBg": "#14251a",
    "toolErrorBg": "#2d1719",
    "statusLineBg": "panel",

    "userMessageText": "fg",
    "customMessageText": "fg",
    "customMessageLabel": "accent",
    "toolTitle": "fg",
    "toolOutput": "muted",

    "mdHeading": "accent",
    "mdLink": "accent",
    "mdLinkUrl": "muted",
    "mdCode": "yellow",
    "mdCodeBlock": "fg",
    "mdCodeBlockBorder": "border",
    "mdQuote": "muted",
    "mdQuoteBorder": "border",
    "mdHr": "border",
    "mdListBullet": "accent",

    "toolDiffAdded": "green",
    "toolDiffRemoved": "red",
    "toolDiffContext": "muted",

    "syntaxComment": "muted",
    "syntaxKeyword": "purple",
    "syntaxFunction": "accent",
    "syntaxVariable": "fg",
    "syntaxString": "green",
    "syntaxNumber": "yellow",
    "syntaxType": "accent",
    "syntaxOperator": "red",
    "syntaxPunctuation": "muted",

    "thinkingOff": "dim",
    "thinkingMinimal": "muted",
    "thinkingLow": "accent",
    "thinkingMedium": "green",
    "thinkingHigh": "yellow",
    "thinkingXhigh": "purple",
    "bashMode": "green",
    "pythonMode": "yellow",

    "statusLineSep": "dim",
    "statusLineModel": "purple",
    "statusLinePath": "accent",
    "statusLineGitClean": "green",
    "statusLineGitDirty": "yellow",
    "statusLineContext": "accent",
    "statusLineSpend": "muted",
    "statusLineStaged": "green",
    "statusLineDirty": "yellow",
    "statusLineUntracked": "red",
    "statusLineOutput": "fg",
    "statusLineCost": "yellow",
    "statusLineSubagents": "purple"
  },
  "symbols": {
    "preset": "unicode"
  }
}

```

--------------------------------

### Exercise the greet tool via normal request

Source: https://omp.sh/docs/mcp-authoring

Use this request to exercise the handler. You should see 'Hello, Ada!'.

```text
Use the hello server to greet Ada.

```

--------------------------------

### /fast command examples

Source: https://omp.sh/docs/modes

Shows the /fast command with on, off, status, and bare forms. Bare /fast toggles the setting. /fast on is idempotent and reports when the current model has no compatible service-tier control. /fast status is the direct check for the current model family's configured state.

```text
/fast on
/fast off
/fast status
/fast

```

--------------------------------

### Debug block example: stopped at breakpoint

Source: https://omp.sh/docs/debugging

Example of a Debug block shown in the transcript after a successful launch or attach, indicating the adapter, status, stop reason, frame, and source location.

```text
Adapter: debugpy
Status: stopped
Stop reason: breakpoint
Frame: transform_row
Location: /workspace/etl/transform.py:58:9

```

--------------------------------

### Agent definition example: release-auditor

Source: https://omp.sh/docs/agents-and-roles

Example of a custom agent definition with YAML frontmatter. The model field participates in precedence, while prewalk and advisor provide defaults that can be overridden via /agents.

```markdown
---
name: release-auditor
description: Check release readiness and report concrete blockers.
tools: read, grep, glob, bash
model: "@slow"
prewalk: false
advisor: "@advisor"
---

Inspect the assigned release scope. Report evidence and blockers; do not edit files.

```

--------------------------------

### Set remote auth broker URL and token

Source: https://omp.sh/docs/env

Selects broker mode by setting OMP_AUTH_BROKER_URL. Startup fails if no token can be resolved rather than falling back to local credentials.

```shell
export OMP_AUTH_BROKER_URL="https://broker.example.net:8765"
export OMP_AUTH_BROKER_TOKEN="..."
omp

```

--------------------------------

### Configure broker client

Source: https://omp.sh/docs/secrets

Configure each client, preferably through a secret injector. Environment variables take precedence over config keys. If a URL is configured without a token, startup fails.

```bash
export OMP_AUTH_BROKER_URL='https://auth.example.internal'
export OMP_AUTH_BROKER_TOKEN='…'
omp auth-broker status
omp

```

--------------------------------

### Print full-control and view-only collab links

Source: https://omp.sh/docs/collab

Shows that a hosting session has both a full-control link and a view-only link, and you can give different people different access without restarting it. The first command prints the full-control link, and the second prints the view-only link.

```bash
/collab       # print the full-control link
/collab view  # print the view-only link
```

--------------------------------

### List plugins with omp plugin list

Source: https://omp.sh/docs/plugins

Lists installed plugins before changing state. The human-readable output separates npm/link plugins from marketplace plugins, showing versions, enabled state, and optional features for npm/link plugins; marketplace rows include scope and whether a project copy shadows a user copy. Use --json for machine-readable output.

```bash
omp plugin list
omp plugin list --json

```

--------------------------------

### Subagent frontmatter example with model role alias

Source: https://omp.sh/docs/subagent-authoring

Example frontmatter for a subagent that uses the @review model role alias, restricts tools, and sets a high thinking level. The model alias is resolved in the user or project configuration.

```yaml
---
name: api-reviewer
description: Review API changes for compatibility, missing tests, and contract drift.
tools: [read, grep, glob]
model: "@review"
thinking-level: high
---

Review the assigned API change and report concrete findings with file and line references.

```

--------------------------------

### Sign in with OAuth or subscription using /login

Source: https://omp.sh/docs/providers

Starts an interactive login flow for a provider. Follow the browser, device-code, or paste-code instructions shown by omp. For remote terminals, you may need to paste the final redirect URL or code back as /login <value>.

```bash
/login openai-codex

```

--------------------------------

### Prompt example for renaming a symbol

Source: https://omp.sh/docs/acp

Example prompt to send to the ACP thread after authentication. The response streams into the editor, and omp uses the editor's filesystem bridge, writes through the editor, and runs shell commands in client-side terminals when available.

```text
Rename issueToken to mintToken across this project, update every caller, and run the focused tests.

```

--------------------------------

### new_session

Source: https://omp.sh/docs/rpc

Starts a new session, optionally as a child of a parent session.

```APIDOC
## new_session

### Description
Starts a new session, optionally as a child of a parent session.

### Method
stdin command

### Endpoint
stdin

### Parameters
#### Request Body
- **parentSession** (string) - Optional - Identifier of the parent session.

### Response
#### Success Response
- **cancelled** (boolean) - Indicates whether the session creation was cancelled.

#### Response Example
```json
{
  "cancelled": false
}
```
```

--------------------------------

### session.compact(instructions?)

Source: https://omp.sh/docs/sdk

Runs context compaction explicitly.

```APIDOC
## session.compact(instructions?)

### Description
Runs context compaction explicitly.

### Method
session.compact

### Parameters
#### Parameters
- **instructions?** (string) - Optional - Instructions for the compaction.
```

--------------------------------

### message_start

Source: https://omp.sh/docs/hooks

Emitted when a user, assistant, or tool-result message started. Provides the message.

```APIDOC
## Event: message_start

### Description
Emitted when a user, assistant, or tool-result message started.

### Payload
- `message` (object) - The message that started.

### Timing
When a user, assistant, or tool-result message started.
```

--------------------------------

### Install a standalone skill into native locations

Source: https://omp.sh/docs/skills

Copy a skill directory containing SKILL.md into one of omp's native locations. User-level skills apply to every project; project-level skills apply to the current repository tree. Discovery is one level deep, so skills/postgres/SKILL.md is found but skills/databases/postgres/SKILL.md is not.

```bash
~/.omp/agent/skills/<name>/SKILL.md   # user: every project
.omp/skills/<name>/SKILL.md           # project: this repository/tree

```

--------------------------------

### Open the session tree with /tree

Source: https://omp.sh/docs/session-tree

The smallest action to open the session tree. Use the navigator to choose where to continue.

```plaintext
/tree

```

--------------------------------

### turn_start

Source: https://omp.sh/docs/hooks

Emitted at the start of one model/tool turn. Provides turn index and timestamp.

```APIDOC
## Event: turn_start

### Description
Emitted at the start of one model/tool turn.

### Payload
- `turnIndex` (number) - Index of the turn.
- `timestamp` (string) - Timestamp of the turn start.

### Timing
Start of one model/tool turn.
```

--------------------------------

### Create a minimal skill with SKILL.md

Source: https://omp.sh/docs/skills

Place this file at .omp/skills/release-check/SKILL.md. The directory name becomes the invocation name, so the skill can be requested with /skill:release-check after /reload-plugins or in a new session.

```markdown
---
description: Use when preparing or reviewing a release; verify versioning, changelog, build artifacts, and publication status.
---

# Release check

1. Identify the version and release tag.
2. Verify the changelog describes the shipped behavior.
3. Check the build artifacts before publishing.
4. Report blockers before changing a tag or publishing.

```

--------------------------------

### Verify effective values: omp config get for collab settings

Source: https://omp.sh/docs/collab

Verifies the effective values for collab.relayUrl and collab.displayName.

```text
omp config get collab.relayUrl
omp config get collab.displayName

```

--------------------------------

### Run /context command

Source: https://omp.sh/docs/slash

The smallest useful check. Type /context in the main prompt editor and press Enter to run it.

```plaintext
/context
```
Tokens:
Raw