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:
| File | What 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:
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
- The first
unzipplaces the three project files in.omp/. If a file there already exists, answer no and merge the Erebine entry into it. - The second places
models.yml;-nnever replaces a file. If~/.omp/agent/models.ymlalready exists, merge theproviders.erebineentry into it. - Start
ompin the project root.omp models erebinelists the fleet;/mcp test erebinechecks the server. - 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:
{
"$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
}
}
}
typeis not optional. omp treats an entry without it as a localstdioserver and asks for acommand.timeoutis in milliseconds and bounds every request, tool calls included. omp's default is 30000; the bundle sets 60000.0disables it.<api_key>, a key with theinferencescope. Mint one witherectl 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>, thews_xxxidentifier this connection pins to. List options witherectl 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:
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:
modelRoles:
default: "erebine/erebine/<model-slug>:medium"
api: openai-responsesis the Responses API transport: omp posts each turn to/v1/responseswith the system prompt asinstructions, the whole conversation ininput, andstore: false.baseUrlends in/v1, the root omp expects for it.- Each
idis the model id the router accepts. A role selector is<provider>/<id>, so the provider name leads the id:erebine/erebine/<model-slug>. reasoningandthinkingcome from the model's reasoning parser.effortslists the levels the model accepts, lowest first, from omp's vocabulary (minimal,low,medium,high,xhigh,max). omp has nononelevel, so a model whose only effort isnoneis registered without reasoning.inputis["text", "image"]for a vision model, else["text"]. omp has no audio input value.supportsToolsis true when the model takes tool calls.contextWindowis the advertised window andmaxTokensthe 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
maxTokensasmax_output_tokenson every request, so theX-Erebine-Augment-Max-Output-Tokens-Clamp: onheader 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
defaultLevelare the model's default effort. A model whose default isnonestarts at the lowest effort it offers instead, so omp's global thinking level never applies to it. apiKeyresolves as an environment-variable name first, soapiKey: "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:
/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:
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:
| Surface | Supported | Mechanism |
|---|---|---|
| Inference provider | yes | ~/.omp/agent/models.yml plus the .omp/config.yml model role |
| MCP tools | yes | Native MCP client, no bridge |
| Prompts | yes | /erebine:<prompt> key=value slash commands |
| Resources | yes | The read tool, by URI |
| Project rules | yes | .omp/RULES.md, sticky rules |
| Streaming transport | yes | Native streamable HTTP (type: http) |
| OAuth | no | Bearer header from .omp/mcp.json |
| Roots | yes | omp answers roots/list with the project directory |
| Sampling, elicitation | no | omp 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.