codex-offload-mcp: Instructions file for Claude Code

CLAUDE.md

What this is

An MCP server for running Claude Code and the Codex CLI as a pair: Claude drives and holds the conversation, Codex takes self-contained work as background jobs. Claude calls codex_start, gets a job id back immediately, keeps working, and collects the result later.

The point is two models working concurrently. Non-blocking delegation is the mechanism that makes that possible, not the goal in itself — which matters when weighing a change. If a tool here would block until Codex finishes, it does not belong in this server: a blocking call collapses the pair back into one model at a time, with the driving model parked, which is the one outcome this exists to avoid.

When to offload

Nothing here decides whether to delegate. There is no scheduler and no queue — the only thing steering that choice is the codex_start description in src/index.ts, which the calling model reads at call time and judges against. Everything below is that judgment written down, not behaviour the code enforces.

The one operator lever on that judgment is CODEX_MCP_OFFLOAD_LEVEL (src/offload.ts), set in the MCP server's env. Because the whether-decision lives only in the description prose, the knob works by appending a bias clause to that description — aggressive lowers the bar (offload more, to conserve the driving model's usage), conservative raises it, balanced (default) adds nothing. It steers the reading model; it enforces nothing, which is why it is a clause of prose and not a branch in route.ts. Read once at startup like the model index, so restart to change it, and surfaced in codex_models' offloadBias field so the active setting is visible. The hard exclusions (needs conversation context, exploratory, trivial triage) still bind at every level — a bias toward offloading must never override them.

Model and effort are chosen here, in src/route.ts, and that is the one exception to the above. Keep the distinction sharp when editing: routing decides how a job runs, never whether it runs. The facts it routes over — which models exist, which efforts each accepts — are read from Codex's own index (src/models.ts), so they do not go stale; only the tier judgment is invented, and it is a keyword heuristic by choice, since a classifier that called a model would add latency to a tool whose entire promise is returning immediately. It is reported in every job's routing field and overridden by any explicit model / reasoningEffort, or disabled with autoRoute: false. A hardcoded effort list was tried first and was wrong within the hour: it invented none and minimal, which no model advertises, and omitted ultra, which two models support. Do not reintroduce one.