omp-worker-mcp

omp-worker-mcp

Let your main AI agent plan and review — and hand the hands-on coding to local [Oh My Pi](https://github.com/can1357/oh-my-pi) workers.

An MCP server that turns ChatGPT, Codex, Claude Code, Cursor and other MCP clients into a *supervisor*,

and Oh My Pi (OMP) on your own machine into its background *workforce*.

English · 简体中文 · Documentation

Quick start · Usage · Tools · Configuration · Safety model · FAQ

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 PATH

omp 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: / 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:

Codex — the author's daily setup

Edit ~/.codex/config.toml (Windows: C:\Users\ \.codex\config.toml):

[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"]

*(If [features.code_mode] already exists in your config.toml, merge into that table and append "mcp__omp_worker" to direct_only_tool_namespaces rather than duplicating the table or overwriting existing entries. Legacy Codex builds used a top-level direct_only_tool_namespaces = ["mcp__omp_worker"] key before any [table] header. Neither setting is required to register the MCP server; see Codex direct namespace setup and the official Codex Config Reference.)*

ChatGPT (web) — via Secure MCP Tunnel

Version requirement (`>= 0.2.0`): OMP_WORKER_ALLOWED_ROOTS is available since omp-worker-mcp 0.2.0 (historical npm 0.1.1 lacks this feature and does not enforce OMP_WORKER_ALLOWED_ROOTS). Confirm npx -y omp-worker-mcp@latest --version reports 0.2.0 or newer before exposing local execution remotely.

Run the server locally behind OpenAI's tunnel-client; your machine only makes outbound connections.

export OMP_WORKER_OMP_COMMAND=omp

export 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=' '

tunnel-client init \ --sample sample_mcp_stdio_local \ --profile omp-worker \ --tunnel-id \ --mcp-command "npx -y omp-worker-mcp"

tunnel-client doctor --profile omp-worker --explain tunnel-client run --profile omp-worker

Windows PowerShell commands, 0.1.1 upgrade / local-build notes, managed runtime alternatives (tunnel-client runtimes connect), permission requirements and the full trust boundary: ChatGPT Secure MCP Tunnel guide.

Claude Code

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

Use --scope project to register it for the current project only. On Windows cmd.exe, if npx fails to resolve, use cmd /c npx.

Cursor · VS Code / Copilot · Windsurf · Continue · any JSON-config client

{

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

File locations and client-specific notes: Client configurations.

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 the

project 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