omp-worker-mcp

What it does

Most coding agents do everything in one place: read the code, plan, edit, run tests, fix — all inside one conversation and one model's budget. omp-worker-mcp splits that work into two roles:

omp-worker-mcp is the bridge between them. It gives the supervisor a small set of MCP tools, starts OMP in the background, keeps every job on disk, and returns a short structured report instead of a wall of logs.

Highlights

• One task or a whole plan — omp_run_compact delegates a single task; omp_run_batch_compact runs up to 50 tasks as a dependency graph (DAG), up to 10 at a time.
• Declared write-scope validation — parallel write tasks in a batch must declare the paths they own; overlapping declared scopes and dependency cycles are rejected before any worker starts (a scheduling check and prompt constraint, not an OS filesystem lock).
• Results you can review — every worker finishes with an OMP_WORKER_RESULT envelope: status, summary, changed files, verification evidence and remaining items.
• Correct instead of restart — omp_continue sends feedback to the same OMP session, so the worker keeps its context.
• Persistent jobs — job records, logs and results live on disk and can still be read after the MCP server restarts.
• Works from ChatGPT on the web — through OpenAI's Secure MCP Tunnel: no inbound port, plus an allowlist (OMP_WORKER_ALLOWED_ROOTS, available since 0.2.0; npm 0.1.1 lacks this feature) for the directories jobs may run in.

When to use it

A good fit when

• you want a strong model to make the decisions while a faster or cheaper model does the typing;
• the task is big enough to hand off: a feature, a bug fix with tests, a multi-module refactor, a long read-only investigation;
• you want several parts of a repo worked on in parallel without agents overwriting each other;
• you think with ChatGPT and want it to act on files on your own machine.

Probably not worth it when

• the change is one line or the question is quick — the supervisor's own tools are faster;
• you need a real OS-level sandbox. This project controls where jobs start and what they are told to touch, not what OMP is technically able to do (see Safety model).

Quick start

You need: Node.js ≥ 22 · Oh My Pi installed · an MCP client (Codex, Claude Code, Cursor, ChatGPT, …).

1. Install and set up OMP

Install OMP by following its official instructions, then:

omp --version   # confirm the CLI is on your PATHomp setup       # sign in and choose the default model

The default model you pick here is the model every worker will use. (Advanced: set modelRoles.default: <provider>/<model> in ~/.omp/agent/config.yml.)

If omp is not on your PATH, set OMP_WORKER_OMP_COMMAND to the full path of the executable in the MCP config below.

2. Register the MCP server in your client

There is nothing to install globally — the client runs the published package with npx -y omp-worker-mcp. Pick your client:

[mcp_servers.omp-worker]command = "npx"args = ["-y", "omp-worker-mcp"]
[mcp_servers.omp-worker.env]OMP_WORKER_OMP_COMMAND = "omp"
# Optional (Codex Code Mode only): let Codex call omp-worker tools directly# without code-mode wrapping. Per the current Codex config reference, merge into# your existing [features.code_mode] table (do not create a duplicate table header)# and append "mcp__omp_worker" while preserving any other list entries:[features.code_mode]direct_only_tool_namespaces = ["mcp__omp_worker"]

export OMP_WORKER_OMP_COMMAND=ompexport OMP_WORKER_ALLOWED_ROOTS='["/Users/you/Projects"]'   # strongly recommended for remote access (available since 0.2.0; 0.1.1 lacks this feature)export CONTROL_PLANE_API_KEY='<runtime-api-key>'
tunnel-client init \  --sample sample_mcp_stdio_local \  --profile omp-worker \  --tunnel-id <your-tunnel-id> \  --mcp-command "npx -y omp-worker-mcp"
tunnel-client doctor --profile omp-worker --explaintunnel-client run --profile omp-worker

claude mcp add omp-worker --scope user --env OMP_WORKER_OMP_COMMAND=omp -- npx -y omp-worker-mcp

{  "mcpServers": {    "omp-worker": {      "command": "npx",      "args": ["-y", "omp-worker-mcp"],      "env": {        "OMP_WORKER_OMP_COMMAND": "omp"      }    }  }}

Restart the client after changing its config.

3. Tell your agent when to delegate

Registering the server makes the tools available; it does not make the agent choose them. Add a short policy to your project's instruction file — AGENTS.md (Codex), CLAUDE.md (Claude Code), .cursorrules / .github/copilot-instructions.md (others) — or to ChatGPT's project instructions:

## Delegation policy (omp-worker-mcp)- Quick questions, single-file edits, design discussion: do it yourself.- Substantive single tasks (feature, bug fix, refactor, long investigation): inspect briefly,  then delegate with `omp_run_compact`, giving a clear `goal` and `acceptance` criteria.- Multi-part work: use `omp_run_batch_compact`. Parallel write tasks need disjoint `ownership`;  tasks touching the same files must be ordered with `depends_on`.- Review every result. If acceptance is not met, use `omp_continue` with specific feedback.- Never delegate `git push`, publishing, deployments or secret changes — confirm those with the user.

A fuller template: Author workflow → Policy template.

4. Run your first task

Start with something read-only:

Use omp-worker-mcp to do a read-only inspection of this workspace: summarize theproject structure and dependencies. Do not modify any files.

What you should see: the agent calls omp_run_compact, OMP works in the background, and a short summary comes back with no files changed. If the job runs longer than the wait window (60 s by default), the call returns a job_id with status running and the agent keeps going with omp_wait — that is normal.

Usage

Once the policy is in place you can just describe the outcome you want. The examples below show what the supervisor sends under the hood.

A single task

"Add exponential backoff to the HTTP client in src/net/, cover it with unit tests, and make sure npm test passes."

// omp_run_compact{  "cwd": "/path/to/repo",  "goal": "Add exponential backoff (max 5 retries) to src/net/client.ts for 5xx and network errors.",  "acceptance": [    "Unit tests cover the retry and give-up paths",    "npm test passes"  ],  "timeout_minutes": 30}

What comes back is compact (abridged example):

{  "job_id": "job-…",  "status": "completed",  "attempt": 1,  "max_attempts": 3,  "session_id": "sess-…",  "summary": "Added retry with exponential backoff to the HTTP client.",  "artifacts": [    { "path": "src/net/client.ts", "description": "retry loop + backoff helper" },    { "path": "test/net/client.test.ts", "description": "retry / give-up tests" }  ],  "verification": ["npm test: all tests passed"],  "remaining": [],  "details_path": "…/jobs/job-…/job.json"}

Several tasks as a DAG

"Add a /health endpoint to the API and a status badge to the UI in parallel, then add an integration test that covers both."

graph LR  api["api · write src/api/"] --> tests["tests · write tests/"]  ui["ui · write src/ui/"] --> tests

// omp_run_batch_compact{  "cwd": "/path/to/repo",  "max_parallel": 2,  "tasks": [    { "id": "api",   "goal": "Add GET /health returning build info.", "access": "write", "ownership": ["src/api/"] },    { "id": "ui",    "goal": "Show a status badge fed by /health.",   "access": "write", "ownership": ["src/ui/"] },    { "id": "tests", "goal": "Add an integration test for /health and the badge.",      "depends_on": ["api", "ui"], "access": "write", "ownership": ["tests/"],      "acceptance": ["npm test passes"] }  ]}

Rules worth knowing:

• write tasks must list the paths they own in ownership (relative to cwd); read_only tasks list none.
• Two tasks that may run at the same time cannot own overlapping paths — order them with depends_on instead.
• max_parallel is 1–10 (default 4); the whole group has a deadline (group_timeout_minutes, default 60).
• If the group is still running when the wait window ends, you get a group_id; continue with omp_wait_group.

Supervising a job

Tools

Full parameters and limits: Tool reference.

Configuration

Everything is configured through environment variables, set in the client's MCP config (env) or in the shell that launches the server.

All variables, the on-disk layout and restart behaviour: Operations · .env.example.

Safety model

What omp-worker-mcp enforces

• With OMP_WORKER_ALLOWED_ROOTS set (available since 0.2.0; npm 0.1.1 lacks this feature), a job's cwd must resolve (via realpath) inside an approved root. Sibling-prefix tricks and symlink/junction escapes are rejected before OMP starts; a present-but-invalid value fails closed.
• In a batch, parallel write tasks must have disjoint ownership, and the graph must be acyclic — checked before any worker is spawned.
• Ownership and read-only intent are passed to each worker as explicit constraints.

What it does not do

• It is not a sandbox. OMP and anything it runs have the same permissions as the user account that started the server. Ownership is a scheduling check plus an instruction to the worker, not a filesystem lock.
• It does not decide what is safe to run. Keep git push, publishing, deployments and secret changes with you and the supervisor.

For remote access (e.g. ChatGPT via Secure MCP Tunnel), always set OMP_WORKER_ALLOWED_ROOTS, and consider a dedicated low-privilege account, a container or a VM. To report a vulnerability, see SECURITY.md.

Platform support

Linux reports and client configs that you have verified are very welcome — see Contributing.

FAQ

Documentation

COMPATIBILITY.md defines the public contract and versioning policy; CHANGELOG.md lists releases.

Contributing

Issues and pull requests are welcome — especially Linux verification and tested client configs. Start with CONTRIBUTING.md. To build from source:

git clone https://github.com/divenire990/omp-worker-mcp.gitcd omp-worker-mcpnpm cinpm test        # builds, then runs the test suite against a fake OMP

Acknowledgements

Built on the Model Context Protocol TypeScript SDK and designed around Oh My Pi (MIT). OMP is not bundled and must be installed separately. This project is independent and not affiliated with OMP, OpenAI or Anthropic.

License

MIT