### Install optional components

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

Use the 'setup' subcommand to install optional components like the Python kernel ('omp setup python') or speech-to-text ('omp setup stt'). Use --check to probe without installing.

```bash
setup
Install optional components. omp setup python provisions the Python kernel; omp setup stt provisions speech-to-text. Pass --check to probe without installing.
```

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

### APPEND_SYSTEM.md Example

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

Example of an APPEND_SYSTEM.md file to append custom instructions to the system prompt.

```markdown
# ~/.omp/agent/APPEND_SYSTEM.md

You are pairing with a security-focused engineer. When reviewing diffs,
call out: missing input validation, unsafe deserialization, secrets in
logs, and authn/authz changes that broaden access.


```

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

### Manage Marketplace Catalogs and Install Plugins

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

Commands to add a marketplace catalog, discover plugins within it, install a specific plugin by name and marketplace, and list all installed plugins.

```bash
omp marketplace add anthropics/claude-plugins-official
omp marketplace discover           # browse plugins in the catalog
omp install code-review@claude-plugins-official
omp list                           # everything installed, npm + marketplace
```

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

### Install Plugins from Marketplace

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

Install a plugin by its name and marketplace, optionally specifying a scope or forcing a reinstall. CLI equivalents are available under `omp plugin install`.

```bash
/marketplace install code-review@claude-plugins-official
/marketplace install --scope project my-plugin@my-marketplace
/marketplace install --force name@marketplace        # reinstall

```

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

### Complete SKILL.md Example

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

A full example of a SKILL.md file, including frontmatter with name, description, and condition, along with playbook content.

```markdown
---
name: postgres
description: Writing, reviewing, or optimizing Postgres queries, schemas, or configs.
condition: User mentions EXPLAIN, indexes, slow query, or migration.
---

# Postgres playbook

## When to use this skill
- Reviewing a migration before it lands
- Diagnosing slow queries with EXPLAIN
- Picking an index type

## Procedure
1. Capture the current plan: `EXPLAIN (ANALYZE, BUFFERS) <query>`.
2. Check stats freshness: `SELECT last_analyze FROM pg_stat_user_tables`.
3. Inspect indexes: `\d+ <table>` in psql, or `pg_indexes`.

## Reference
- `skill://postgres/references/indexes.md` — index decision matrix
- `skill://postgres/references/explain.md` — reading EXPLAIN output

```

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

### AGENTS.md Example

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

Example of an AGENTS.md file used for project notes, including conventions and file locations.

```markdown
# Project notes for the agent

## Conventions
- Bun, not Node. Use `bun test`, not `npm test`.
- React Router v6 with file-based routes under `src/routes/`.
- No utility classes inside <Prose>; use plain HTML tags.

## Where things live
- `src/components/docs/` &mdash; PageHeader, Prose, nav.ts
- `src/routes/docs/` &mdash; one file per page

## Don&rsquo;t touch
- `bun.lock` &mdash; regenerated by `bun install`.
- `public/clips/` &mdash; binary assets, do not rewrite.

```

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

### Install omp SDK

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

Install the omp SDK using Bun. This package is a TypeScript ES module.

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

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

### Verify omp Installation

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

Verify the installation of the omp binary and check its configuration path. Use the version command to confirm the installed version and the config path command to locate the active agent directory.

```bash
omp --version           # the binary version on PATH
omp config path         # the active agent dir (contains config.yml)
omp -p 'hello'          # round-trip a one-shot prompt
```

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

### Complete Extension Example: Manifest

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

A minimal `package.json` for an extension that includes a description and specifies the extension factory entry point.

```json
{
  "name": "@acme/notes",
  "version": "1.0.0",
  "description": "Notes search tool plus a writing-style skill",
  "omp": {
    "extensions": ["./src/main.ts"]
  }
}
```

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

### Starting a Goal

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

Enable Goal mode in your agent configuration and then use the `/goal` command with your objective. The objective should be written as a brief, including deliverables and success criteria.

```shell
/goal port the importer to streaming and update the call sites

```

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

### Example .env File Configuration

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

This snippet shows a typical configuration for a ~/.omp/.env file, including API keys and model settings. Ensure sensitive keys are protected.

```shell
# ~/.omp/.env — applies to every project
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
PI_SLOW_MODEL="openai/gpt-5.3-codex:high"
PI_NO_PTY=1

```

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

### Marketplace Catalog Schema

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

Example of a minimal `marketplace.json` file defining a marketplace name, owner, and a list of plugins with their names and relative sources.

```json
{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "acme-plugins",
  "owner": { "name": "Acme Corp", "email": "plugins@acme.example" },
  "description": "Official Acme plugins for omp",
  "plugins": [
    {
      "name": "acme-linter",
      "description": "Enforce Acme coding standards",
      "category": "development",
      "source": "./plugins/linter"
    }
  ]
}

```

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

### Manage configuration settings

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

Use the 'config' subcommand to read and write settings, including listing, getting, setting, resetting, and initializing configuration paths. The settings schema is the source of truth.

```bash
config
Read/write settings: list, get, set, reset, path, init-xdg. Source of truth is the settings schema.
```

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

### Example Session Structure

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

This snippet shows a trimmed session log, illustrating the header, user and assistant messages with tool usage, model changes, labels, and compaction.

```json
{"type":"session","version":3,"id":"1f9d29","timestamp":"2026-05-14T10:12:03Z","cwd":"/Users/me/src/api","title":"refactor importer"}
{"type":"message","id":"1f9d2a","parentId":null,"timestamp":"…","message":{"role":"user","content":[{"type":"text","text":"refactor the importer to stream"}]}}
{"type":"message","id":"1f9d2b","parentId":"1f9d2a","timestamp":"…","message":{"role":"assistant","content":[{"type":"text","text":"Reading the file first."},{"type":"tool_use","id":"toolu_01","name":"read","input":{"path":"src/importer.ts"}}]}}
{"type":"message","id":"1f9d2c","parentId":"1f9d2b","timestamp":"…","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01","content":[{"type":"text","text":"…file contents…"}]}]}}
{"type":"model_change","id":"1f9d2d","parentId":"1f9d2c","timestamp":"…","model":"anthropic/claude-opus","role":"default"}
{"type":"label","id":"1f9d2e","parentId":"1f9d2c","timestamp":"…","targetId":"1f9d2a","label":"pre-refactor"}
{"type":"compaction","id":"1f9d2f","parentId":"1f9d2e","timestamp":"…","summary":"…","firstKeptEntryId":"1f9d2c","tokensBefore":48211}
```

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

### Plugin Structure Example

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

Illustrates the typical directory structure and files within a custom Omp plugin, including configuration, skills, commands, hooks, tools, MCP servers, and themes.

```bash
my-plugin/
  plugin.json              # name, version, description, entry points
  skills/<name>/SKILL.md   # → /docs/skills
  commands/<name>.md       # → /docs/prompt-templates
  hooks/pre/*.ts           # → /docs/hooks
  hooks/post/*.ts
  tools/<name>/index.ts    # → /docs/custom-tools
  mcp.json                 # → /docs/mcp
  themes/<name>.json       # → /docs/themes
  README.md
```

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

### Start omp in RPC UI Mode

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

Launches omp with an integrated UI, suitable for interactive elements alongside programmatic control.

```bash
omp --mode rpc-ui --no-session    # adds tool-card / selector UI frames

```

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

### Manage plugins and marketplace

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

Control the plugin and marketplace lifecycle with the 'plugin' subcommand, including install, uninstall, list, link, doctor, features, config, enable, disable, discover, and upgrade.

```bash
plugin
Plugin and marketplace lifecycle: install, uninstall, list, link, doctor, features, config, enable, disable, marketplace, discover, upgrade.
```

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

### Implement Custom Provider with Discovery

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

Declare a custom provider using a supported transport and enable live model discovery. This example uses `llama.cpp` discovery for a local server.

```yaml
providers:
  llama.cpp:
    baseUrl: http://127.0.0.1:8080
    api: openai-responses
    auth: none
    discovery:
      type: llama.cpp

```

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

### Markdown Prompt Template Example

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

A Markdown file defining a prompt template with YAML frontmatter for metadata and a prompt body that includes positional arguments.

```markdown
---
description: Review a PR with a structured checklist
---

Review pull request #$1.

Focus areas (from `$@`):

1. Correctness — logic errors, off-by-ones, wrong return paths.
2. Security — injection, authn/authz, secret handling.
3. Performance — N+1, allocations on hot paths, blocking I/O.
4. Tests — new code paths covered, no flakiness or hidden mocks.

Use `gh pr view $1 --json title,body,files` to start, then
`gh pr diff $1` for the patch. Surface findings inline with file:line.

```

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

### Minimal Stdio Server Implementation

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

This TypeScript code sets up a basic MCP server using the `@modelcontextprotocol/sdk`. It handles tool listing and calling via stdio transport. Ensure the `@modelcontextprotocol/sdk` is installed.

```typescript
// server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const server = new Server({ name: "hello", version: "0.1.0" }, { capabilities: { tools: {} } });

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "greet",
    description: "Say hello to someone.",
    inputSchema: { type: "object", properties: { who: { type: "string" } }, required: ["who"] },
  }],
}));

server.setRequestHandler(CallToolRequestSchema, async (req) => ({
  content: [{ type: "text", text: `Hello, ${req.params.arguments?.who}!` }],
}));

await server.connect(new StdioServerTransport());

```

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

### Define and Use a Custom Tool

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

Define a custom tool with parameters and an execute function, then pass it to `createAgentSession`. This example shows an 'echo_host' tool that echoes a message back.

```typescript
import { Type } from "@sinclair/typebox";
import { createAgentSession, type CustomTool } from "@oh-my-pi/pi-coding-agent";

const echoHost: CustomTool = {
  name: "echo_host",
  label: "Echo Host",
  description: "Echo a value back through the embedding host.",
  parameters: Type.Object({ message: Type.String() }),
  async execute(_id, { message }) {
    return { content: [{ type: "text", text: `host: ${message}` }] };
  },
};

const { session } = await createAgentSession({
  customTools: [echoHost],
});

```

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

### Session Tree Structure Example

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

Illustrates the hierarchical structure of a session tree, showing parent-child relationships between messages and identifying the current 'leaf' pointer.

```text
root
├─ user: "Start task"
│  └─ assistant: "Plan"
│     ├─ • user: "Try approach A"   ← leaf
│     │  └─ • assistant: "A result"
│     └─ user: "Try approach B"
│        └─ assistant: "B result"


```

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

### Example: Catching a Value After Three Iterations in Python

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

This example demonstrates how to set a conditional breakpoint in a Python script, inspect variables when the breakpoint is hit, and continue execution. It covers launching the script, setting the breakpoint, continuing, inspecting the stack and locals, evaluating an expression, and terminating the session.

```shell
# 1. Launch the script under debugpy.
debug action=launch adapter=debugpy program=etl/transform.py

# 2. Break inside the loop the third time through.
debug action=set_breakpoint file=etl/transform.py line=58 condition="i == 3"
debug action=continue

# 3. When it stops, read the frame.
debug action=stack_trace levels=5
debug action=scopes frame_id=0
debug action=variables scope_id=<locals_ref_from_scopes>

# 4. Ask the running interpreter a question.
debug action=evaluate frame_id=0 expression="sum(running_totals)" context=repl

# 5. Done.
debug action=continue
debug action=terminate

```

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

### Reload LSP Servers

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

After installing a missing toolchain or to clear stale state, use `lsp action=reload` to restart the language servers. Use `file="*"` to reload all servers.

```bash
lsp action=reload file="*"
```

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

### Start ACP Mode

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

Initiates the omp agent in ACP mode. This is the equivalent of running omp with the --mode acp flag.

```bash
omp acp           # equivalent to: omp --mode acp

```

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

### Session Header Example

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

The first line of every session file is a 'session' header. It includes schema version, working directory, and an optional title or parent session lineage.

```json
{"type":"session","version":3,"id":"1f9d29","timestamp":"2026-05-14T10:12:03Z","cwd":"/Users/me/src/api","title":"refactor importer"}

```

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

### Resume session and fork

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

Resume a specific session by its ID prefix and fork from a particular message, providing a new message to start from.

```bash
omp -r 1f9d2a --fork msg_8c1e "Try a different approach"
```

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

### Resume Session Commands

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

These flags are used to resume or start sessions. Use `-c` to continue the most recent session in the current working directory, `-r` to open a picker scoped to the project or resume by ID prefix, or `--resume` with a file path for explicit resumption. `--no-session` runs ephemerally without disk persistence.

```bash
omp -c                       # continue most recent in this cwd
omp -r                       # open a picker scoped to this project
omp -r 1f9d2a                # resume by id prefix
omp --resume ./session.jsonl # resume an explicit file
omp --no-session             # ephemeral; nothing written to disk
```

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

### Force Mode Examples

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

Use /force to pin the next turn to a specific tool. This is useful when the model repeatedly selects the incorrect tool. You can specify the tool and an optional prompt, or just the tool to pin the next message you send.

```bash
/force write src/server/auth.ts: stub a JWT verifier
/force task                       # pins next message you send

```

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

### TypeScript Prompt Template Example

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

A TypeScript module for a prompt template that registers a command to summarize git commits. It includes argument parsing, shell command execution, and user notifications.

```typescript
// ~/.omp/agent/commands/changelog/index.ts
import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("changelog", {
    description: "Summarise recent commits into CHANGELOG bullets",
    argumentHint: "<rev-range>",
    handler: async (args, ctx) => {
      const range = args.trim() || "HEAD~10..HEAD";
      const log = await pi.exec("git", ["log", "--oneline", range], {
        cwd: pi.cwd,
      });
      if (log.code !== 0) {
        ctx.ui.notify("git log failed: " + log.stderr, "error");
        return;
      }
      await pi.sendUserMessage(
        `Summarise these commits as CHANGELOG bullets, grouped by Added / Changed / Fixed:\n\n${log.stdout}`, { deliverAs: "nextTurn" },
      );
      ctx.ui.notify(`Queued changelog for ${range}`, "info");
    },
  });
}


```

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

### Fast Mode Examples

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

Use /fast to toggle OpenAI's 'service_tier: "priority"' for outgoing requests. This routes requests ahead of default-tier traffic at a higher cost. Options include toggling, explicitly turning on/off, or checking the status.

```bash
/fast          # toggle
/fast on
/fast off
/fast status

```

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

### Check LSP Server Status

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

If diagnostics are empty but the build fails, run `lsp action=status` to check if the language server for that language is running. If missing, install the required toolchain and reload servers.

```bash
lsp action=status
```

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

### Start omp in RPC Mode

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

Launches omp as a subprocess for programmatic interaction. Use `--mode rpc` for headless operation or `--mode rpc-ui` to include interactive UI elements.

```bash
#!/usr/bin/env bash
set -euo pipefail
prompt='Say "ok" and nothing else.'
jq -nc --arg m "$prompt" '{id:"s1",type:"prompt",message:$m}' \
  | omp --mode rpc --no-session \
  | while IFS= read -r line; do
      t=$(jq -r '.type' <<<"$line")
      [[ "$t" == "message_update" ]] && \
        jq -r '.assistantMessageEvent.delta // empty' <<<"$line"
      [[ "$t" == "agent_end" ]] && exit 0
    done

```

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

### Custom Theme JSON Structure

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

Define a custom theme by creating a JSON file in `~/.omp/agent/themes/`. This example shows the basic structure including name, variables, and color definitions for UI elements.

```json
{
  "name": "ink",
  "vars": {
    "fg": "#e6e6e6",
    "bg": "#0b0d12",
    "accent": "#7aa2f7"
  },
  "colors": {
    "text": "fg",
    "background": "bg",
    "accent": "accent",
    "error": "#f7768e",
    "success": "#9ece6a",
    "warning": "#e0af68",
    "info": "#7dcfff",
    "border": "#3a3f4b",
    "muted": "#565f89"
    /* ...remaining required tokens... */
  },
  "symbols": "unicode"
}

```

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

### Loop Mode Examples

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

Use /loop to repeatedly submit a prompt until a condition is met. You can specify an unlimited number of iterations, a fixed count, or a time duration. Units for duration include seconds (s), minutes (m/min), and hours (h/hr).

```bash
/loop          # unlimited; runs until you cancel
/loop 10       # cap at 10 iterations
/loop 30m      # wall-clock cap
/loop 2h

```

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

### Manage OMP Agent Configuration

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

Use the `omp config` command to list, get, set, reset, or find the path to the configuration file. These commands allow for scripted edits and inspection of settings.

```bash
omp config list                            # the full tree
omp config get modelRoles.default          # one key
omp config set theme.dark catppuccin-macchiato
omp config reset theme.dark                # back to schema default
omp config path                            # print the active config.yml path


```

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

### Serve Authentication Broker

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

Start an authentication broker on a host to serve credentials over HTTP. This is useful for sharing a single credential store across multiple machines. Ensure you secure the transport layer (TLS or VPN) as the broker enforces bearer token authentication.

```bash
# on the broker host
omp auth-broker serve --bind=0.0.0.0:8765

```

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

### Configure Self-Hosted Hindsight Backend

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

Configure the 'hindsight' memory backend for a self-hosted instance. This involves setting the API URL, API token, and choosing a scoping method. The bank ID is typically null for self-hosted setups, being allocated on first use.

```yaml
memory:
  backend: hindsight
hindsight:
  apiUrl: http://hindsight.internal:8888
  apiToken: REPLACE_ME
  bankId: null                  # per-project bucket allocated on first use
  scoping: per-project
```

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

### Enter Plan Mode

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

Initiate plan mode by typing '/plan' followed by the goal, or use the keyboard shortcut Alt+Shift+P.

```bash
/plan refactor src/importer.ts to stream rows instead of buffering

```

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

### Print help and reference

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

Display help information, including the environment variable and tool reference, using the --help or -h flag.

```bash
--help, -h
Print help and the env var / tool reference.
```

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

### Goal Tool - Get Operation

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

The model uses the `goal` tool with `op: "get"` to read its own budget information.

```json
goal({"op": "get"})

```

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

### Example Custom Share Handler: Upload to S3

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

An example of a custom share handler that uploads an HTML file to an S3 bucket and returns a public URL. It uses Node.js's child_process to execute AWS CLI commands.

```typescript
// ~/.omp/agent/share.ts
import { execFileSync } from "node:child_process";
import { basename } from "node:path";

const BUCKET = "s3://my-team-omp-shares";
const PUBLIC_BASE = "https://shares.my-team.dev";

export default async function share(htmlPath: string) {
  const key = `${Date.now()}-${basename(htmlPath)}`;
  execFileSync("aws", ["s3", "cp", htmlPath, `${BUCKET}/${key}`, "--acl", "public-read"], {
    stdio: "inherit",
  });
  const url = `${PUBLIC_BASE}/${key}`;
  return { url, message: `Uploaded ${key} (${BUCKET})` };
}

```

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

### Open a PR with Details

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

Demonstrates how to open a new PR with a title, body, base branch, reviewers, and labels.

```shell
github op=pr_create \
  title="Fix login redirect after SSO" \
  body="Resolves #1198. Adds a regression test." \
  base=main \
  reviewer=["octocat","myorg/team-auth"] \
  label=["bug"]
```

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

### Open a Draft PR with Autofill

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

Shows how to create a draft PR that automatically fills details from the commit log.

```shell
github op=pr_create fill=true draft=true
```

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

### New Session Confirmation

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

This message confirms that a new session has been started with the handoff context.

```bash
New session started with handoff context
```

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

### Basic Handoff Command

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

Use this command to end the current session and start a new one with a generated wrap-up document.

```bash
/handoff
```

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

### Send a Prompt to omp

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

Send a prompt to the omp agent to start interacting. The agent will detect terminal settings and project context to provide responses.

```bash
summarise src/main.ts
```

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

### Allow Home Directory Launch

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

Use the `--allow-home` flag to permit launching omp from the $HOME directory without automatically changing into a project directory.

```bash
--allow-home| Permit launching from $HOME without auto-chdir into a project.
```

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

### Authenticate with Anthropic API Key

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

Set the ANTHROPIC_API_KEY environment variable to authenticate with the Anthropic provider. This is the fastest way to start using omp with Anthropic.

```bash
export ANTHROPIC_API_KEY=sk-ant-...
omp
```

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

### Complete Extension Example: Factory Module

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

The TypeScript factory module for an extension. It registers a slash command and a custom tool with OMP using the provided `ExtensionAPI`.

```typescript
// src/main.ts
import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";

export default function notes(pi: ExtensionAPI) {
  const { z } = pi.zod;

  pi.registerCommand("notes", {
    description: "Open today's note",
    handler: async (_args, ctx) => ctx.ui.notify("Opened notes", "info"),
  });

  pi.registerTool({
    name: "search_notes",
    label: "Search Notes",
    description: "Full-text search through project notes",
    parameters: z.object({ query: z.string() }),
    async execute(_id, params) {
      return {
        content: [{ type: "text", text: `Searched: ${params.query}` }],
        details: { query: params.query },
      };
    },
  });
}
```

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

### Omp CLI Flags for Context Files

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

Demonstrates CLI flags to control the discovery and injection of context files.

```text
--no-context-files
--no-rules
--system-prompt <text|@file>

```

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

### Serve Remote Credential Vault

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

Set up a remote credential vault to share credentials across multiple machines. This command starts the authentication broker server.

```bash
omp auth-broker serve --bind 127.0.0.1:7700
```

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

### Skill Configuration Options

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

Lists flags and configuration settings for managing skill discovery and execution.

```text
Flag / setting| Effect  
---|---  
`--skills <p1,p2,…>`| Comma-separated glob patterns; only matching skills are kept.  
`--no-skills`| Disable skill discovery entirely for this run.  
`skills.enabled: false`| Same, persisted in `~/.omp/agent/config.yml`.  
`ignoredSkills: [name, …]`| Block individual skills by name.  
`includeSkills: [name, …]`| Allowlist — only these load.  
`skills.enableSkillCommands: false`| Disable `/skill:<name>` invocations while leaving discovery on.  

```

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

### Attach to a running browser instance

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

Connect to an existing Chromium instance using CDP or by spawning an Electron binary with the 'browser open' command.

```tool_code
browser open name=cursor app={path: "/Applications/Cursor.app/Contents/MacOS/Cursor"}
```

```tool_code
browser open name=devtools app={cdp_url: "http://127.0.0.1:9222"}
```

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

### Omp Context File Locations

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

Illustrates the directory structure for project-specific and global context files that Omp discovers.

```text
<repo>/AGENTS.md            # project notes (also walked from subdirs)
<repo>/.omp/SYSTEM.md       # project: replace the system prompt
<repo>/.omp/APPEND_SYSTEM.md
<repo>/.omp/RULES.md

~/.omp/agent/AGENTS.md      # global notes
~/.omp/agent/SYSTEM.md      # global: replace the system prompt
~/.omp/agent/APPEND_SYSTEM.md
~/.omp/agent/RULES.md

```

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

### Basic CLI Usage

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

Shows the general syntax for using the omp CLI. It can be used for general commands or specific subcommands.

```bash
omp [options] [@files...] [messages...]

```

```bash
omp <command> [args] [flags]

```

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

### Allow launching from home directory

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

Permit launching omp from the user's home directory without automatically changing the current directory to a project using the --allow-home flag.

```bash
--allow-home
Permits launching from $HOME without auto-chdir into a project.
```

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

### Hook File Locations

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

Global and project-specific directories for pre-hooks and post-hooks.

```bash
~/.omp/agent/hooks/pre/*.ts      # global pre-hooks
~/.omp/agent/hooks/post/*.ts     # global post-hooks
.omp/hooks/pre/*.ts              # project pre-hooks
.omp/hooks/post/*.ts             # project post-hooks

```

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

### Message Entry Examples

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

Message entries wrap model messages with role and content. Tool calls and results are embedded within the content array. A single turn constitutes one entry.

```json
{"type":"message","id":"1f9d2a","parentId":null,"timestamp":"…","message":{"role":"user","content":[{"type":"text","text":"refactor the importer to stream"}]}}

```

```json
{"type":"message","id":"1f9d2b","parentId":"1f9d2a","timestamp":"…","message":{"role":"assistant","content":[{"type":"text","text":"Reading the file first."},{"type":"tool_use","id":"toolu_01","name":"read","input":{"path":"src/importer.ts"}}]}}

```

```json
{"type":"message","id":"1f9d2c","parentId":"1f9d2b","timestamp":"…","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_01","content":[{"type":"text","text":"…file contents…"}]}]}}

```

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

### Open Model Picker UI

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

Open the model picker interface to select from providers you are currently signed into.

```bash
> /model
```

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

### Provider Hint Flag

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

Use the `--provider` flag to hint at the provider, though `--model` is generally sufficient.

```bash
--provider <name>| Provider hint. Mostly legacy; --model is enough.| —
```

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

### Branch Session Command

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

The `/branch` command allows you to start a new thread from a previous message within the same session file. This is useful for exploring alternative paths without creating a new file.

```bash
/branch                       # message selector opens; pick where to branch
```

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

### Setting Token Budget

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

Cap the goal's token usage with `/goal budget <N>`, where N is a positive integer. Use `off` to clear the cap.

```shell
/goal budget 200000

```

```shell
/goal budget off

```

```shell
/goal budget <N|off>

```

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

### Launch omp and Login via TUI

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

Launch the omp agent and use the /login command within the TUI to authenticate with OAuth providers. This method is suitable for subscription-based services.

```bash
omp
/login
```

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

### Session Tree Navigation Example

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

This visual representation shows the structure of a session tree, illustrating parent-child relationships between messages and indicating the current leaf. It helps in understanding how to navigate and visualize session history.

```text
● 1f9d2a  user      "rewrite the importer to stream"
└─● 1f9d2b  assistant tool: read src/importer.ts
  ├─● 1f9d2c  assistant edit src/importer.ts          ← current leaf
  │ └─● 1f9d2d  user      "add a test for the stream path"
  └─● 1f9d2e  assistant edit src/importer.ts (alt)    ← branch B
    └─◆ 1f9d2f  [labeled: pre-refactor checkpoint]
```

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

### Checkout and Push PRs

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

Illustrates the workflow for checking out a PR into a worktree and pushing changes back.

```shell
github op=pr_checkout pr=1234
# cd into the worktree, run tests, edit, then:
github op=pr_push
```

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

### Interactive Login with OAuth

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

Use the /login command for interactive authentication. It initiates an OAuth flow if supported by the provider, otherwise it prompts for an API key. Credentials are stored in ~/.omp/agent/agent.db.

```bash
/login anthropic
```

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

### Configure Hindsight Cloud Backend

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

Set up the 'hindsight' memory backend using the public Hindsight Cloud API. This requires specifying the API URL, token, and optionally a bank ID and scoping strategy.

```yaml
memory:
  backend: hindsight
hindsight:
  apiUrl: https://api.hindsight.vectorize.io
  apiToken: hs_live_REPLACE_ME
  bankId: my-team-bank          # optional; auto-allocated when omitted
  scoping: per-project-tagged   # global | per-project | per-project-tagged
```

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

### Example TTSR Rule for Rust Project

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

This rule prevents the model from using `Box::leak` in Rust code edits or writes, steering it towards safer alternatives like `Arc<str>`. It targets specific file operations and includes a detailed explanation for the model.

```markdown
---
description: Refuse Box::leak in production code paths
condition: "Box::leak\("
scope: "tool:edit(*.rs), tool:write(*.rs)"
---

You were about to write `Box::leak` to obtain a `&'static` reference. Stop.

`Box::leak` permanently allocates for the lifetime of the process &mdash; harmless
in a one-shot binary, a real leak inside a server that runs for days. In this
codebase use one of:

- `Arc<str>` for cheaply-cloneable owned strings
- `Cow<'static, str>` when the value is sometimes a literal, sometimes owned
- `OnceLock<String>` for actual program-lifetime singletons

Re-plan the edit with one of those, then proceed.

```

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

### Read using internal URL schemes

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

Demonstrates reading content using various internal omp URL schemes.

```shell
read pr://1234/diff/2
```

```shell
read agent://AuthLoader/findings
```

```shell
read conflict://*
```

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

### Attaching Files and Images

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

Attach multiple files, including documents and images, in a single command. This allows for comprehensive context to be provided to the agent.

```bash
omp @prompt.md @screenshot.png "Implement what's drawn"
```

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

### Minimal Marketplace Structure

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

A basic directory structure for a local marketplace, including the `.claude-plugin/marketplace.json` catalog file and a directory for plugins.

```bash
my-marketplace/
  .claude-plugin/
    marketplace.json
  plugins/
    my-plugin/        ← a plugin tree, see /docs/plugins

```

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

### Resume Session by ID or Path

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

Resume a session using its ID prefix or JSONL path with the `--resume` or `-r` flag. Without a value, it opens an interactive picker.

```bash
--resume, -r [id|path]| Resume by session id prefix or jsonl path. With no value, opens an interactive picker.
```

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

### Open an Agent Session

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

Create an agent session using `createAgentSession`. This function discovers credentials, loads extensions, and sets up the model. It subscribes to session events and sends an initial prompt.

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

const authStorage = await discoverAuthStorage();
const modelRegistry = new ModelRegistry(authStorage);
await modelRegistry.refresh();

const { session, modelFallbackMessage } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
  model: modelRegistry.getAvailable()[0],
  thinkingLevel: "medium",
});

if (modelFallbackMessage) {
  process.stderr.write(modelFallbackMessage + "\n");
}

const unsubscribe = session.subscribe((event) => {
  if (
    event.type === "message_update" &&
    event.assistantMessageEvent.type === "text_delta"
  ) {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await session.prompt("Summarize this repository in three bullets.");
unsubscribe();
await session.dispose();

```

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

### Read PRs and Diffs

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

Demonstrates how to read PR metadata, diffs, and individual file diffs using the `pr://` URL scheme.

```shell
read pr://1234
read pr://1234/diff
read pr://1234/diff/2
```

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

### Navigate to Symbol Definition

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

Use `lsp action=definition` to find the location where a symbol is defined. Specify the file, line, and symbol name. Use `symbol="name#N"` to disambiguate multiple occurrences on the same line.

```bash
lsp action=definition  file=src/parse.ts      line=88 symbol="parse#2"
```

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

### Read Local Memory Documents

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

Use the 'read' tool with 'memory://' URLs to access local memory content for the current project. This includes the static guidance block, the full long-term memory document, or generated skill playbooks.

```bash
omp -p 'read memory://root'

# Show the full long-term memory document for this project
omp -p 'read memory://root/MEMORY.md'

# Show a generated skill playbook
omp -p 'read memory://root/skills/<name>/SKILL.md'
```