MCP Codex Worker

Stop spending premium context on bulk code work

Measured: 80% less premium context intake. ~$213-1068/mo saved.

Yeah# 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.

Related MCP server: Jules MCP Server

Efficiency First

Most AI coding tools optimize the model call. This project optimizes the route.

The fast path is deliberately split:

• search handles repo discovery with zero LLM calls.

• analyze and review use one cheap gateway call for read-only work.

• start moves implementation loops into an async worker so Codex is not blocked by every file read, failed attempt, or test log.

• get and wait return compact evidence instead of dumping the whole transcript back into the premium thread.

That routing discipline is the efficiency edge: Codex stays focused on planning and review while the worker absorbs the bulky middle.

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.

Efficiency Comparison

Highlights

• Async MCP tools: start, get, tail, wait, cancel.

• Read-only lite tools: read_pack, analyze, diff_digest, history, and draft keep bulky reading/review/drafting out of the premium thread.

• Code review lite tool: review checks diffs/files through the cheap gateway.

• Zero-LLM repo discovery and mechanical work: search uses bounded local search, and apply_edits handles deterministic replacements without a model call.

• Worker-side command digesting: shell can run tests/builds/lint and return a compact failure digest. Non-zero command exits return status:"failed" or status:"timeout" with failure_kind and required_action; they are command outcomes, not tool transport errors.

• Receipt abnormal-output assessment: every receipt carries a deterministic accept/repair verdict and bounded repair guidance without default multi-model voting.

• Runtime tool containment: the worker classifies tool errors, opens per-tool/per-error-class circuits, intercepts unhealthy routes, and uses deterministic fallbacks for review/analyze when the LLM route is unhealthy.

• Reliability tiers and episode summaries: start can record lite, standard, strict, or critical expectations without blocking old callers; hard rejection happens only with blocking_policy:"enforce".

• 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 and worker tool-call categories 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:

Tool Surface

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:

These controls reduce main-thread context, payload size, and accounting noise; they do not impose a spend ceiling on the worker LLM. Primary, fallback, and escalation models are chosen by capability and reliability configuration, not by price gates. WORKER_PRICE_* values are for reporting only and must not downgrade, block, or skip fallback/escalation usage.

• include_diff:false reduces high-cost Codex ingestion.

• DIFF_MAX_BYTES caps patch payloads.

• INCLUDE_DIFF_DEFAULT=0 makes omitted include_diff behave like false.

• CHECK_OUTPUT_RESPONSE_MAX keeps failed check output compact in get/wait responses while tail retains fuller logs.

• analyze skips Claude Code for read-only summaries.

• search handles symbol/file discovery without any LLM call.

• review and WORKER_FAILURE_DIGEST=1 move diff review and failure diagnosis to the cheaper gateway.

• read_pack, diff_digest, shell digest, apply_edits, history, and draft move the remaining high-token planning/review chores into worker lanes.

• WORKER_METRICS_FILE records real gateway token usage plus event=tool_call rows for zero-LLM worker calls.

• WORKER_ESCALATE_MODEL upgrades only failed, difficult revise passes.

• WORKER_RELIABILITY_TIER, WORKER_BLOCKING_POLICY, WORKER_SEMANTIC_GATE, and WORKER_TOOL_BUDGET record reliability expectations and blocking risk. Defaults are observe-only to avoid surprise stalls.

• 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 read_pack instead of full-file reads and diff_digest instead of full diff ingestion.

7. Use shell with digest:true for tests/builds/lint so command output is summarized before Codex sees it.

8. Keep start below 30% of worker calls; use finer tools for search, reading, diff digestion, history, drafts, and mechanical edits.

9. Treat receipt abnormal.verdict !== "accept" as a repair signal before considering multi-model parallel review. For shell, use failure_kind and required_action first; do not escalate to the main model just because the command exit code is non-zero.

10. Use a fit-for-task default model and reserve WORKER_ESCALATE_MODEL for difficult revise passes; do not downgrade primary, fallback, or escalation models because of cost.

Important Environment Variables

For less common stats, cache, reliability, and circuit-breaker settings, see Advanced Configuration.

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
npm run skills:validate
npm run codex:audit -- --since-minutes=60
npm run codex:guard

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

npm run codex:audit -- --since-minutes=60 checks recent worker metrics, receipt artifact coverage, the persisted AGENTS.md routing rules, fallback usage, and worker category evidence. It also prints the known blind spot: direct main-thread shell output, full-file reads, chat context, and pasted prompts are outside WORKER_METRICS_FILE.

npm run codex:guard runs the local Codex audit and then stats:gate.

npm run skills:validate checks the project-specific .claude/skills/ library used to preserve project doctrine for cheaper or lower-context worker sessions.

npm run stats reports gateway token usage, receipt byte/artifact usage, and a Worker Tool Audit. npm run stats:gate -- <metrics.jsonl> turns the same thresholds into hard gates with exit code 2 on failure. Category targets are: search 80%, context_pack 70%, command_digest 70%, diff_digest 60%, review 60%, mechanical_edit 50%, history 60%, draft 80%, analysis 60%, and start must stay at or below 30% of worker calls. Gate mode also fails if required categories have no audit evidence, overall tool error rate is 5% or higher, any single tool error rate is 3% or higher after the sample floor, fallback ratio exceeds 10%, large receipt payloads lack artifact refs, or diff_digest red-team coverage falls below 30%. Tool error rate is reserved for worker/tool execution failures; shell command failures are recorded as command_status with local repair guidance, and stale job ids or invalid caller inputs are recorded as rejected.

When the MCP server is running, it also reviews recent tool error rates every 3 hours by default. A threshold breach, or a review that runs later than WORKER_TOOL_REVIEW_GRACE_MS, enables escalation self-heal defaults for later start calls: reliability_tier=strict, blocking_policy=warn, semantic_gate=warn, auto_revise=true, and at least one revise pass. Explicit start arguments still win over these defaults.

Runtime containment is more aggressive than the 3-hour review. Every tool result updates an in-memory rolling window. Real tool execution errors are classified (upstream_404, upstream_error, shell_mismatch, search_timeout, timeout, missing_command, missing_path, permission_denied, dependency_missing, or unknown_failure). Repeated errors, or any immediate-class error, open a temporary circuit. While open, unhealthy routes are intercepted as rejected instead of producing more errors; review and analyze degrade to deterministic local evidence when possible. Open circuits and a bounded rolling-event snapshot are persisted to a state sidecar file and reloaded on MCP startup or the next tool-control decision, so restarts do not immediately forget an unhealthy route or a tool already close to its circuit threshold. To keep the hot path cheap, OK outcomes are snapshotted only after WORKER_TOOL_CIRCUIT_STATE_SAVE_MIN_MS; errors and circuit opens force a save. Shell command business failures still record command_status and do not count as tool errors. On Windows, PowerShell-shaped shell commands accidentally sent through cmd.exe are retried once through powershell -NoProfile -ExecutionPolicy Bypass -Command.

Additional redundancy that is already in place:

• Gate redundancy: codex:guard combines recent routing audit evidence with stats:gate.

• Route redundancy: review/analyze can fall back to local deterministic evidence while LLM review routes are unhealthy.

• Shell redundancy: shell mismatch is retried once through the matching Windows shell before surfacing failure.

• State redundancy: circuit state is atomically written with a temp file plus rename, protected by a best-effort lock, guarded by a checksum, and pruned on load. Corrupt, mismatched, or expired state is ignored and rewritten instead of crashing the MCP server.

• Restart redundancy: a small rolling-event snapshot is restored with open circuits so a restart does not erase tools that are already near a circuit threshold.

• Efficiency guardrail: state writes are bounded by event count and save interval; lock contention skips a snapshot instead of delaying the worker.

The routing contract tests lock the core money/safety invariants:

• I3: no predictive classifier call before routing.

• I5: identical read-only requests hit cache; primary failure plus fallback records one successful upstream.

• I6: read-only tools do not write to the workspace.

The smoke test also verifies the current tool surface: analyze, apply_edits, cancel, diff_digest, draft, get, get_artifact_slice, history, read_pack, review, search, shell, start, tail, and wait.

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.