docs
// Guides

omp Coding Agent

One project folder, one user-level merge. omp reads MCP servers, sticky rules and project settings from .omp/, and custom model providers from ~/.omp/agent/models.yml. The Erebine bundle fills both.

omp is a terminal coding agent with a native MCP client, native custom OpenAI-compatible providers and native sticky rules. The Erebine bundle installs no extension and no adapter: three project files and one provider snippet.

The Client-tab download carries four files, plus a README.txt:

FileWhat it does
mcp.json The mcpServers.erebine entry: streamable-HTTP URL, Authorization and workspace headers, timeout. Save as .omp/mcp.json at your project root.
RULES.md The Erebine tool-use rules. Save as .omp/RULES.md.
config.yml Makes this workspace's default omp's default model role. Save as .omp/config.yml. Present only when this workspace advertises models.
models.yml Registers every advertised model under a custom erebine provider. Merge into ~/.omp/agent/models.yml. Present only when this workspace advertises models.

~/.omp/agent/ is the default profile's directory. A named profile reads ~/.omp/profiles/<name>/agent/ instead, and PI_CODING_AGENT_DIR moves the default one.

See the general MCP integration documentation for the full tool catalog, the governed-execution model, and the security gates that apply to every MCP request.

Quick Start

Download the omp bundle from the Chat page's Client tab (visible once a specific workspace is selected), then install it from your project root:

Shell
mkdir -p .omp ~/.omp/agent unzip erebine-<workspace>-omp-config.zip mcp.json RULES.md config.yml -d .omp unzip -n erebine-<workspace>-omp-config.zip models.yml -d ~/.omp/agent
  1. The first unzip places the three project files in .omp/. If a file there already exists, answer no and merge the Erebine entry into it.
  2. The second places models.yml; -n never replaces a file. If ~/.omp/agent/models.yml already exists, merge the providers.erebine entry into it.
  3. Start omp in the project root. omp models erebine lists the fleet; /mcp test erebine checks the server.
  4. Prompt: Call the Erebine intelligence brief tool (erebine.intelligence.brief) and summarize this workspace. The answer proves both halves of the bundle.

.omp/mcp.json and models.yml carry your workspace API key. Add .omp/mcp.json to your project's .gitignore. models.yml lives outside the repository; delete any extracted copy left in the project tree. RULES.md and config.yml carry no secrets and are safe to commit. Re-downloading rotates the key and revokes the one in your previous bundle.

MCP Server

omp reads project MCP servers from .omp/mcp.json and personal ones from ~/.omp/agent/mcp.json. The bundle uses the project file: a workspace serves one repository. This is the whole entry:

JSON
{ "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json", "mcpServers": { "erebine": { "type": "http", "url": "https://api.erebine.ai/proj_ABC123/v1/mcp", "headers": { "Authorization": "Bearer <api_key>", "X-Erebine-Workspace": "<workspace_id>" }, "timeout": 60000 } } }
  • type is not optional. omp treats an entry without it as a local stdio server and asks for a command.
  • timeout is in milliseconds and bounds every request, tool calls included. omp's default is 30000; the bundle sets 60000. 0 disables it.
  • <api_key>, a key with the inference scope. Mint one with erectl keys --create --name "omp" --scopes inference. omp expands ${VAR} in this file, so "Bearer ${EREBINE_API_KEY}" keeps the key in your environment.
  • <workspace_id>, the ws_xxx identifier this connection pins to. List options with erectl workspaces list.

omp appends the server's own instructions to its system prompt; set "instructions": false on the entry to leave them out. /mcp reload applies an edit without restarting.

Inference Provider

omp reads custom providers from the user-level ~/.omp/agent/models.yml only; there is no project model file. The bundle's snippet registers the whole fleet this workspace advertises:

YAML
providers: erebine: baseUrl: "https://api.erebine.ai/proj_ABC123/<workspace_id>/_direct/v1" apiKey: "<api_key>" api: "openai-responses" headers: X-Erebine-Augment-Corrective-Retries: "on" X-Erebine-Augment-Max-Output-Tokens-Clamp: "on" models: - id: "erebine/<model-slug>" name: "<model-name>" reasoning: true thinking: mode: "effort" efforts: ["low", "medium", "high"] defaultLevel: "medium" input: ["text", "image"] supportsTools: true contextWindow: 131072 maxTokens: 32000

.omp/config.yml starts omp on this workspace's default model:

YAML
modelRoles: default: "erebine/erebine/<model-slug>:medium"
  • api: openai-responses is the Responses API transport: omp posts each turn to /v1/responses with the system prompt as instructions, the whole conversation in input, and store: false. baseUrl ends in /v1, the root omp expects for it.
  • Each id is the model id the router accepts. A role selector is <provider>/<id>, so the provider name leads the id: erebine/erebine/<model-slug>.
  • reasoning and thinking come from the model's reasoning parser. efforts lists the levels the model accepts, lowest first, from omp's vocabulary (minimal, low, medium, high, xhigh, max). omp has no none level, so a model whose only effort is none is registered without reasoning.
  • input is ["text", "image"] for a vision model, else ["text"]. omp has no audio input value.
  • supportsTools is true when the model takes tool calls. contextWindow is the advertised window and maxTokens the output cap, at most half the window; each is emitted only when the model publishes a positive value, and a value of zero or less is dropped so omp's default applies.
  • omp sends maxTokens as max_output_tokens on every request, so the X-Erebine-Augment-Max-Output-Tokens-Clamp: on header asks Erebine to shorten an output cap that does not fit the remaining window instead of refusing the request.
  • The role's thinking suffix and defaultLevel are the model's default effort. A model whose default is none starts at the lowest effort it offers instead, so omp's global thinking level never applies to it.
  • apiKey resolves as an environment-variable name first, so apiKey: "EREBINE_API_KEY" reads the key from your environment.

Switch models with /model, or pass --model erebine/<id> for one launch. The model travels in the request payload, so one base URL covers every id in models.yml. omp reads .omp/config.yml only from the directory it is launched in; to use the model from elsewhere, assign the role once in /model > Roles.

The routing mode chosen at download time decides how much of the fleet lands in models.yml:

  • Direct (default): every generative model in the project, all in the picker.
  • Semantic router: one entry pointing at the semantic router, which scores the fleet per request.
  • Pinned: the resolved endpoint, pinned. One model.

A workspace with no advertised models yields an MCP-only bundle: mcp.json and the rules file, no model files, and omp keeps whatever provider you already use.

Project Rules

.omp/RULES.md carries the shared Erebine tool-use rules every other client receives through its own rules surface, plus an omp addendum that spells out the tool, prompt and resource names. omp applies RULES.md as sticky rules to every session in the project, alongside your personal ~/.omp/agent/RULES.md.

Without them the agent will sometimes ask you about workspace state instead of calling the Erebine tools to retrieve it.

The rules also ask the agent to sign each commit an Erebine endpoint generates with a Co-Authored-By: Erebine trailer. See Commit Attribution.

RULES.md, not .omp/AGENTS.md. omp loads a .omp/AGENTS.md in place of the repository's AGENTS.md at the same level; the two are not concatenated. RULES.md stacks with both, so the bundle never shadows a project's existing instructions and never replaces the system prompt.

Tools, Prompts, Resources

omp names each MCP tool mcp__<server>_<tool>: lower-cased, every character outside [a-z0-9_] replaced by an underscore, and a tool name that repeats the server prefix stripped of it once. erebine.intelligence.brief becomes mcp__erebine_intelligence_brief.

Every Erebine prompt is a slash command named /erebine:<prompt>. Arguments are key=value pairs after the name; quote a value with spaces:

omp
/erebine:brief /erebine:onboard topic=billing /erebine:save-this note="use the v2 schema for exports"

/mcp prompts lists them. Resources are read through omp's read tool by URI, for example erebine://workspace/current/brief; /mcp resources lists what the server exposes. Both are documented on the general MCP integration page.

CLI Setup

erectl prints the MCP server entry. When the project has no .omp/mcp.json yet, write it straight out:

Shell
mkdir -p .omp erectl mcp setup --client omp --workspace <uuid> > .omp/mcp.json

If the file already exists, merge the mcpServers.erebine key into it instead of overwriting.

By default the key is written as "Bearer ${EREBINE_API_KEY}", which omp expands from the environment when it loads the file. Export EREBINE_API_KEY before starting omp, or pass --inline-api-key <key>.

Pass --out-dir <dir> to also write models.yml, config.yml and the rules file, built from the workspace's _direct models over the management API, exactly as the dashboard's Direct bundle carries them; --mcp-only keeps the model provider you already use.

Capability Matrix

What the bundle wires into omp, and how:

SurfaceSupportedMechanism
Inference provideryes~/.omp/agent/models.yml plus the .omp/config.yml model role
MCP toolsyesNative MCP client, no bridge
Promptsyes/erebine:<prompt> key=value slash commands
ResourcesyesThe read tool, by URI
Project rulesyes.omp/RULES.md, sticky rules
Streaming transportyesNative streamable HTTP (type: http)
OAuthnoBearer header from .omp/mcp.json
Rootsyesomp answers roots/list with the project directory
Sampling, elicitationnoomp does not advertise either

See the full per-client comparison in docs/mcp, Security.

Troubleshooting

The server reports stdio server requires "command"

The mcpServers.erebine entry has no type. omp assumes a local stdio server without one. Set "type": "http", then run /mcp reload.

"Request timeout after 30000ms"

The entry has no timeout, so omp's 30 second default applies to every tool call. Set "timeout": 60000 or more; the value is in milliseconds. OMP_MCP_TIMEOUT_MS overrides every server's timeout for one process.

The provider is missing from omp models

Run omp models erebine. "models.yml validation failed" names the field that broke; one invalid custom entry disables every custom provider in the file for that run. Check that the root key is providers and that the file sits in the active profile's agent directory (omp config path prints it).

omp starts on another model

.omp/config.yml is read only from the directory omp is launched in. Start omp from the project root, or assign the role in /model > Roles. A --model flag or a later --config overlay also wins over the project file.

401 Unauthorized on every tool call

The key in .omp/mcp.json is missing, malformed, or revoked. Each omp download from the Client tab rotates your omp key and revokes the previous one; other clients' keys are untouched. Re-download the bundle, or replace the Authorization header value with a key carrying the inference scope. With ${EREBINE_API_KEY} in the file, check that the variable is exported in the shell that starts omp.

403 Forbidden with code scope_insufficient

The key authenticated but does not carry the inference scope the MCP surface requires. Mint a replacement with erectl keys --create --name "omp" --scopes inference.