OMP (Oh My Pi)

OMP (Oh My Pi) is a Pi-compatible harness that stores its agent state under ~/.omp/agent/ (overridable with the PI_CODING_AGENT_DIR environment variable). context-mode ships as an OMP plugin — omp plugin install context-mode — and the dedicated adapter does three things:

• Wires real in-process hooks via OMP's plugin api, so routing is enforced programmatically — not left to the model's goodwill.
• Self-registers the MCP server, so the ctx_* tools become reachable without a manual mcp.json edit.
• Isolates ~/.omp/context-mode/ storage, so an OMP install is detected as OMP rather than treated as plain Pi and never roots its session data under another harness's directory.

Install

The plugin path is recommended — it gives you the full hook set and self-registers MCP. An MCP-only path is available if you only want the ctx_* tools.

omp plugin install context-mode

omp plugin list
omp plugin doctor

cd ~/.omp/plugins
npm install context-mode

MCP-only path (no plugin)

If you only want the ctx_* tools without in-process hooks, install context-mode globally and register it by hand. Routing then depends on the model following SYSTEM.md voluntarily (~60% adherence).

npm install -g context-mode

Add context-mode to ~/.omp/agent/mcp.json (user scope) or <project>/.omp/mcp.json (project scope). The bare context-mode binary starts the MCP server by default — there is no mcp subcommand.

{
  "mcpServers": {
    "context-mode": {
      "command": "context-mode"
    }
  }
}

Then copy the routing instructions and restart OMP:

cp node_modules/context-mode/configs/omp/SYSTEM.md ~/.omp/agent/SYSTEM.md

This SYSTEM.md is written for the MCP-only path: it states that hooks are "not yet wired" and that "these rules are the only enforcement path," which is accurate here. On the plugin path you do not need this file — the in-process hooks enforce routing — so skip this copy step if the plugin is installed.

Routing

Routing instructions live in SYSTEM.md — OMP's native system-prompt file (project .omp/SYSTEM.md takes precedence over the global ~/.omp/agent/SYSTEM.md). OMP also auto-discovers AGENTS.md. There is no PI.md loader upstream.

On the plugin path, five in-process hooks enforce routing programmatically:

Detection

context-mode detects OMP ahead of plain Pi, so an OMP install is never treated as Pi. It identifies OMP through any of these signals:

Session data is rooted at ~/.omp/context-mode/sessions/, kept separate from the agent directory. This isolation means:

• OMP and Pi installs never share session DBs, content indices, or stats files.
• Multiple OMP instances on one host share an index without colliding.

Verify your savings

Confirm context-mode is actually saving you tokens, not just installed.

In an OMP session, type ctx stats in chat. After some work it shows the tokens-saved and savings ratio for the session. On the plugin path OMP records real per-turn tokens and provider cost via the turn_end hook, so the ~98% figure is user-verifiable.

For a structural check, run the doctor. It verifies the context-mode entry in ~/.omp/agent/mcp.json alongside language runtimes and the FTS5 knowledge base:

context-mode doctor

If that entry is absent, the ctx_* tools won't appear until OMP is restarted (the plugin self-registers on load). The doctor needs the global binary (npm install -g context-mode); on the plugin path omp plugin doctor is the primary check.

Related