MCP Codex Worker

Stop spending premium Codex context on bulk code reading, patch loops, and giant diffs.

mcp-codex-worker lets Codex delegate the expensive part of a coding task to an async worker running on a cheaper OpenAI-compatible model gateway. Codex stays in charge, but it only receives the compact evidence it needs: changed files, checks, logs, and an optional trimmed diff.

The Simple Picture

Without this worker, Codex often pays to ingest everything:

Codex main thread
  -> reads large files
  -> runs repair loops
  -> receives full diffs
  -> burns premium context

With this worker, Codex delegates the noisy middle:

flowchart LR
  A["Codex<br/>planner and reviewer"] -->|"small MCP start request"| B["MCP Codex Worker"]
  B -->|"launches"| C["Claude Code CLI<br/>background job"]
  C -->|"Anthropic messages"| D["Local adapter"]
  D -->|"OpenAI-compatible chat"| E["Cheap gateway model<br/>DeepSeek / OneAPI / New API"]
  C -->|"git diff + checks"| B
  B -->|"changed_files + checks<br/>optional diff"| A

Plain version:

Codex asks: "fix this, run tests"
Worker does: read files -> edit -> test -> summarize
Codex gets: files changed + checks passed + optional diff

Why It Exists

Codex is strongest when it coordinates, reviews, and decides. It is not always cost-effective to make the main Codex thread read huge files, run long repair loops, and ingest giant diffs.

This worker changes the shape of the bill:

• Codex sends a compact start request.
• Claude Code does the heavy local work in the background.
• The local adapter routes model traffic to your cheaper backend.
• Codex receives changed_files, checks, logs, and an optional trimmed diff.

For large code-reading and patching tasks, this can cut the expensive main-thread token intake dramatically because Codex no longer has to ingest every intermediate file read and full patch body.

What Makes It Better Than "Just Use A Cheaper Model"

Cheap models alone are not enough. You still need routing, safety, result shape, and verification.

This project gives you the missing plumbing:

• A Codex-native MCP interface, so delegation is one tool call.
• A Claude Code execution loop, so the worker can actually edit and test.
• A local Anthropic-to-OpenAI adapter, so Claude Code can use cheaper gateways.
• Scope enforcement and check commands, so work is auditable.
• Compact result payloads, so Codex does not swallow unnecessary tokens.
• Metrics, fallback, retries, and optional worktree isolation for real operations.

Highlights

• Async MCP tools: start, get, tail, wait, cancel.
• Read-only lite tool: analyze answers file-summary questions without launching Claude Code.
• Anthropic-to-OpenAI adapter: lets Claude Code talk to OpenAI-compatible gateways.
• 429 and 5xx retry handling with Retry-After support.
• Optional include_diff:false to return only changed_files and checks.
• Deterministic verification layer: scope checks, command checks, result signals, and bounded auto-revise.
• Cost telemetry: writes gateway token usage to JSONL when WORKER_METRICS_FILE is set.
• Optional fallback gateway when the primary provider fails.
• Optional worktree isolation for parallel jobs inside one repository.
• Secret redaction in logs and tool responses.

Use Cases

Use it when you want Codex to stay sharp instead of stuffed:

Task	Normal flow	Worker flow
Fix a bug in a large repo	Codex reads many files and test outputs	Worker reads/edits/tests, Codex reviews compact result
Summarize implementation details	Full agent loop may start	analyze calls cheap gateway directly
Run repeated repair passes	Main thread absorbs every attempt	Worker handles loop and returns final evidence
Parallel scoped edits	One dirty worktree gets tangled	Optional git worktree isolation keeps jobs apart
Cost accounting	Claude Code cost may be misleading	Gateway token usage is written to JSONL

Tool Surface

Tool	Purpose
start	Start an async Claude Code job in an allowed directory.
get	Read current job status and structured result.
tail	Read recent worker logs.
wait	Wait for completion without killing the job on timeout.
cancel	Kill a running job process tree.
analyze	Read-only cheap-model analysis for selected files.

Quick Start

npm install
npm run build
npm run test
npm run smoke

Create a local .env from .env.example or set environment variables in your shell. Never commit real keys.

setx ONEAPI_API_KEY "your-provider-key"
setx ONEAPI_BASE_URL "https://your-gateway.example.com/v1"
setx SANDBOX_ROOT "D:/workspaces"

Then run:

npm run doctor
npm run doctor:network

Codex Desktop Config

Copy and adapt codex-mcp.example.toml into your Codex config.

[mcp_servers.codex_async_worker]
command = "node"
args = ["D:/path/to/mcp-codex-worker/dist/index.js"]
cwd = "D:/path/to/mcp-codex-worker"
startup_timeout_sec = 10
tool_timeout_sec = 3600
env = { SANDBOX_ROOT = "D:/workspaces", ONEAPI_BASE_URL = "https://your-gateway.example.com/v1", CLAUDE_MODEL = "deepseek-v4-flash", CLAUDE_CODE_MODEL = "sonnet", CLAUDE_PERMISSION_MODE = "acceptEdits", USE_OPENAI_ADAPTER = "1", WAIT_DEFAULT_MS = "1800000" }
env_vars = ["ONEAPI_API_KEY"]

Example Job

{
  "prompt": "Fix the failing tests with the smallest safe code change.",
  "allowed_dirs": ["D:/workspaces/my-project"],
  "model": "deepseek-v4-flash",
  "permission_mode": "acceptEdits",
  "include_diff": false,
  "scoped_patch": {
    "paths": ["src", "tests"],
    "max_diff_bytes": 20000
  },
  "checks": [
    { "name": "unit tests", "command": "npm test", "timeout_ms": 600000 }
  ]
}

Typical result:

{
  "job_status": "completed",
  "changed_files": ["src/a.ts", "tests/a.test.ts"],
  "checks": ["scoped_patch: passed (src, tests)", "unit tests: passed"],
  "diff": ""
}

Use include_diff:false by default when Codex only needs to decide whether the job succeeded. Ask for the diff only when you actually need to review patch details.

Cost Controls

This project stacks several cost controls:

• include_diff:false reduces high-cost Codex ingestion.
• DIFF_MAX_BYTES caps patch payloads.
• analyze skips Claude Code for read-only summaries.
• WORKER_METRICS_FILE records real gateway token usage.
• WORKER_ESCALATE_MODEL upgrades only failed, difficult revise passes.
• WORKER_ISOLATION=worktree allows safe parallel work in one repo.
• Prompt-cache-friendly usage keeps stable instructions before dynamic task text.

Claude Code's own total_cost_usd may reflect Anthropic pricing, not your gateway pricing. Use WORKER_METRICS_FILE and provider prices for real accounting.

Cost-Saving Checklist

For best results:

1. Set include_diff:false for delegated implementation tasks.
2. Keep scoped_patch.paths narrow.
3. Add concrete checks so the worker proves completion.
4. Use analyze for read-only questions.
5. Enable WORKER_METRICS_FILE and compare token usage by route/model.
6. Use a cheap default model and reserve WORKER_ESCALATE_MODEL for difficult revise passes.

Important Environment Variables

Variable	Purpose
SANDBOX_ROOT	Root directory allowed for worker jobs and analyze file reads.
ONEAPI_BASE_URL / ANTHROPIC_BASE_URL	Primary gateway URL.
ONEAPI_API_KEY / ANTHROPIC_API_KEY	Primary gateway key. Keep it out of git.
CLAUDE_MODEL / ANTHROPIC_MODEL	Real backend model used by the gateway.
CLAUDE_CODE_MODEL	Model name passed to Claude Code for local validation, usually sonnet.
USE_OPENAI_ADAPTER	1 to use the local Anthropic-to-OpenAI adapter.
DIFF_MAX_BYTES	Maximum returned diff size.
WORKER_METRICS_FILE	Optional JSONL path for token usage metrics.
WORKER_ESCALATE_MODEL	Optional stronger model for hard revise passes.
WORKER_ISOLATION	Set to worktree for per-job git worktree isolation.
FALLBACK_BASE_URL / FALLBACK_API_KEY	Optional fallback gateway.

Security Model

• All job paths must resolve inside SANDBOX_ROOT.
• scoped_patch rejects changes outside declared paths.
• bypassPermissions is blocked unless explicitly enabled with ALLOW_BYPASS_PERMISSIONS=1.
• Secrets are redacted from logs and tool responses.
• .env, archives, logs, node_modules, and dist are gitignored.

See SECURITY.md for responsible disclosure and operational notes.

Validation

npm run build
npm run test
npm run smoke
npm run doctor:network

doctor:network depends on your real gateway credentials. Build, test, and smoke should pass offline.

When To Use It

Use this worker for:

• long codebase reading tasks,
• scoped code edits with tests,
• repeated repair loops,
• cheap model summaries,
• background implementation while Codex continues planning/reviewing.

Keep the main Codex thread for high-level decisions, code review, final integration, and tasks that require your most capable model directly.