Check that the codex CLI is installed, authenticated, and a supported version, and report the resolved defaults. Free — no model call. Run it before your first paid call in a session to confirm setup, and again whenever a run fails with a setup error. Also reports a rate_limit block — how much of the Codex quota windows remains, fetched LIVE from codex app-server (a read-only call with no model spend). primary is the shorter/rolling window, secondary the longer one; the account reports only the windows that currently bind it, so either may be null. Use it to decide whether to spend: available is deliberately conservative (only when every reported window is healthy); when limited/exhausted, prefer to defer non-urgent Codex calls (urgent ones may still proceed); unknown means the live read couldn't complete just now (retry) or only a stale cache was available; unavailable means this codex/account exposes no quota data — none of these means anything is wrong. blocked is different: the backend reports a SPEND control (spend_control_reached: true), so paid calls will fail and waiting for a quota reset will NOT clear it — don't defer, and surface it to the user. spend_control_reached is null when this codex/backend didn't report that state (then available covers the quota windows only, and note says so). is_stale/as_of show freshness; home_unverified flags a snapshot from a different CODEX_HOME.

Hand off the current Claude Code session to a resumable Codex thread.

Imports a Claude session transcript (.jsonl) into a persistent Codex thread via codex app-server and returns resume_command (codex resume <thread_id>) to continue that exact conversation in Codex (TUI or App). Free — no model call and no token spend; it is a local file conversion, typically seconds. It does create a thread in $CODEX_HOME (so it is not read-only) but never edits your working tree.

Pass transcript_path: the current session's transcript is the newest *.jsonl under ~/.claude/projects//. If that is ambiguous — for example, more than one recent transcript could be the current session — ask the user which one to transfer. Transferring a still-live session creates a NEW thread each call — Codex dedups only a byte-identical transcript — so this is not idempotent for an active session.

Identifiers the app-server reports (the imported thread id and $CODEX_HOME) are validated: a drifted, oversized, or malformed value fails as cli_contract_changed rather than producing a corrupt resume_command or importing into the wrong home. resume_command is POSIX shell syntax.

codex_status (free) can confirm Codex is installed and authenticated beforehand.

List this server's tools, tiers, and the result fingerprint. Free — no model call. Clients can cache by the fingerprint.

detail="summary" (default) returns each tool's name, cost, stability, and error_codes — the facts tools/list does not already carry — plus async_lifecycle, but only for the *_async tools. detail="full" adds use_when/returns/required_params/key_optional_params, restating what you already hold. detail="contracts" omits tool_details.

Pass include_schemas to also embed the full 'error-envelope', 'result-meta', 'capabilities-result', and/or 'status-result' schema, and/or the 'parameter-contracts' document (a contract doc, not a JSON Schema) — a tool-reachable fallback to the codex:// resources for resource-blind clients. It works in any detail mode.

List Codex model slugs you can pass as model, with each model's advertised reasoning-effort set for reasoning_effort. Free — no model call.

Advisory discovery only: read from Codex's on-disk cache when present, else a bundled fallback (source says which; the fallback carries no effort data). codex exec validates the real slug and the backend validates the real effort, so an unlisted value may still work and a listed one may be unavailable to your account. Same payload as the codex://models resource. Not fingerprint-stable — do not cache it by the capabilities fingerprint.

Ask Codex (a different model) for a read-only second opinion or answer.

PAID — this spends Codex quota on every new call; there is no dry-run preview for a consult, so run codex_status (free) first to confirm the CLI is installed and authenticated.

Runs codex exec in a read-only sandbox — Codex never edits files. A STATIC review, not a verify mode: the read-only sandbox blocks the writes a test/build/lint run needs, so Codex can't run your checks to confirm its claims — treat findings as unvalidated claims you verify yourself. Pass workspace_root (absolute) for a repo-grounded question; omit it for pure Q&A. Returns a result envelope.

Data egress: this sends your question and extra_context to OpenAI via the codex CLI. Codex always runs with a resolved working directory (workspace_root, your MCP roots, or the server's cwd as a fallback), so it may read files there and send their content too. Codex auto-loads the resolved workspace's AGENTS.md and discovers skills in its .agents/skills/ and user-global $CODEX_HOME/skills/ (default ~/.codex/skills/), reachable from outside the workspace. The plugin's isolation flags don't suppress any of it. Skill names and descriptions are exposed up front and a selected skill's body can reach the model, so that content can be sent even if your prompt never mentions it. Your inputs are sent raw — secret redaction is best-effort and does not cover them (it covers gathered diffs and Codex's returned output, not what you type or what Codex reads from files).

Progress & recovery: blocks up to the resolved deadline (timeout_seconds, clamped 10-600s; when omitted, the server-configured value, built-in default 300s). If that deadline expires the run is terminated and its partial output is not recoverable or resumable, so for a high-reasoning_effort or broad repo-grounded consult that may exceed it, prefer codex_consult_async (a background job, built-in default 1800s deadline; poll codex_job_status). Coarse notifications/progress streams while it blocks when your client requests it; some MCP clients background a long call before the deadline, so timeout_seconds bounds the run, not necessarily the inline wait — either way the detached run (meta.job_id) is recoverable via codex_job_list→codex_job_status→codex_job_result.

Ask Codex (a different model) to review your git changes for an independent second opinion.

PAID — this spends Codex quota on every new call; use codex_dry_run or codex_status (both free) first if you only need to check scope or readiness.

scope: working_tree (tracked changes vs HEAD — untracked files follow the untracked policy and are NOT reviewed by default), branch (needs base, reviews base...HEAD), or commit (needs a commit SHA). The diff is gathered, secret- redacted, and bounded by this server; Codex reviews it read-only and returns structured findings. Pass workspace_root (absolute) for the right repo. Optional extra_context (author intent, bounded like the diff) cuts false positives.

The result's top-level review_status and coverage disclose whether the model actually ran and what it was shown: a pass over partial coverage is surfaced as unknown, and a tree with nothing reviewable returns not_run, never a pass.

STATIC review, not a verify mode: the read-only sandbox blocks the writes a test/build/lint run needs, so Codex can't run the project's checks to confirm its findings — treat them as unvalidated claims you verify yourself before acting.

Data egress: this sends the gathered diff to OpenAI via the codex CLI. The diff is secret-redacted (best-effort), but your extra_context is sent raw (unredacted), and Codex may read and send other repo files. Codex auto-loads the resolved workspace's AGENTS.md and discovers skills in its .agents/skills/ and user-global $CODEX_HOME/skills/ (default ~/.codex/skills/), reachable from outside the workspace. The plugin's isolation flags don't suppress any of it. A selected skill's body can reach the model even if your prompt never mentions it. Redaction is not a guarantee. Do not rely on it to protect live credentials; keep them out of the reviewed tree and your supplied inputs, or do not request a review of that tree.

Progress & recovery: blocks up to the resolved deadline (timeout_seconds, clamped 10-600s; when omitted, the server-configured value, built-in default 300s). If that deadline expires the run is terminated and its partial output is not recoverable or resumable, so for a multi-file or whole-branch review that may exceed it, prefer codex_review_changes_async (a background job, built-in default 1800s deadline; poll codex_job_status). Coarse notifications/progress streams while it blocks when your client requests it; some MCP clients background a long call before the deadline, so timeout_seconds bounds the run, not necessarily the inline wait — either way the detached run (meta.job_id) is recoverable via codex_job_list→codex_job_status→codex_job_result.

Delegate a coding task to Codex (a different model) in an isolated git worktree, and get back a reviewable diff that is NOT applied to your tree.

PAID — this spends Codex quota on every new call; use codex_delegate_dry_run or codex_status (both free) first if you only need to check scope or readiness.

Codex edits files with workspace-write, but only inside a throwaway worktree seeded from your current tracked state. The returned diff is Codex's changes; review it, then apply it yourself if you want it. Requires a git repo with at least one commit. Pass workspace_root (absolute).

NO NETWORK: workspace-write blocks network egress for commands Codex RUNS in the sandbox, so the task must be self-contained — it cannot git push/fetch, gh anything, curl, publish, or install dependencies (those fail inside the sandbox with a DNS/host-resolution error). Ask only for local code changes; do any network step yourself afterward. This does NOT mean nothing leaves the machine: the Codex model call still sends your task to OpenAI and lets Codex read tracked files in the worktree and send their content. Codex auto-loads the resolved workspace's AGENTS.md and discovers skills in its .agents/skills/ and user-global $CODEX_HOME/skills/ (default ~/.codex/skills/), reachable from outside the workspace. The plugin's isolation flags don't suppress any of it. For delegate, that workspace is the worktree; scrubbing it doesn't exclude $CODEX_HOME/skills/. A selected skill's body can reach the model even if your task never mentions it. Your task is sent raw — secret redaction is best-effort and does not cover it or files Codex reads itself.

Progress & recovery: blocks up to the resolved deadline (timeout_seconds, clamped 10-600s; when omitted, the server-configured value, built-in default 300s). If that deadline expires the run is terminated and its partial output is not recoverable or resumable, so for a substantial or multi-file task that may exceed it, prefer codex_delegate_async (a background job, built-in default 1800s deadline; poll codex_job_status). Coarse notifications/progress streams while it blocks when your client requests it; some MCP clients background a long call before the deadline, so timeout_seconds bounds the run, not necessarily the inline wait — either way the detached run (meta.job_id) is recoverable via codex_job_list→codex_job_status→codex_job_result.

Delegate a coding task to Codex in the background and get a job_id back immediately (does not block on the run).

PAID — this spends Codex quota on every new call; use codex_delegate_dry_run or codex_status (both free) first if you only need to check scope or readiness.

Same propose-tier behavior as codex_delegate — Codex works in a throwaway git worktree and the result carries a reviewable diff that is NOT applied — but detached; prefer it for a substantial or multi-file implementation task that can exceed the synchronous deadline (built-in default 300s), since a sync run whose deadline expires loses its partial work (this job's own deadline is separately configured, built-in default 1800s). Starting a job commits to spend (it runs to completion or its wall-clock deadline even if you never poll). Poll codex_job_status; read/consume with codex_job_result/codex_job_consume_result; stop with codex_job_cancel. Requires a git repo with at least one commit; pass workspace_root (absolute).

NO NETWORK: like codex_delegate, this runs under workspace-write, which blocks network egress for commands Codex RUNS in the sandbox — the task must be self-contained (no push/fetch/gh/curl/publish/dependency install; those fail with a DNS/host-resolution error in the sandbox). This does NOT mean nothing leaves the machine: the Codex model call still sends your task (raw) to OpenAI and lets Codex read tracked files in the worktree and send their content. Codex auto-loads the resolved workspace's AGENTS.md and discovers skills in its .agents/skills/ and user-global $CODEX_HOME/skills/ (default ~/.codex/skills/), reachable from outside the workspace. For delegate, that workspace is the worktree; scrubbing it doesn't exclude $CODEX_HOME/skills/, so a selected skill's body can reach the model even if your task never mentions it. Secret redaction is best-effort and does not cover your task or files Codex reads itself.

Ask Codex for a read-only second opinion in the background; get a job_id back immediately instead of blocking.

PAID — this spends Codex quota on every new call; there is no dry-run preview for a consult, so run codex_status (free) first to confirm the CLI is installed and authenticated.

Same read-only behavior as codex_consult (Codex never edits files), but detached — prefer it for a high-reasoning_effort or broad repo-grounded consult that can exceed the synchronous deadline (built-in default 300s), since a sync run whose deadline expires loses its partial work; this job's own deadline is separately configured (built-in default 1800s). Starting a job commits to spend (it runs to completion or its wall-clock deadline even if you never poll). Poll codex_job_status; read/consume the consult envelope with codex_job_result/codex_job_consume_result; stop with codex_job_cancel.

Data egress: same as codex_consult — sends your question and extra_context (raw, unredacted) to OpenAI via the codex CLI, plus files Codex reads from its resolved working directory (workspace_root, your MCP roots, or the server cwd). Codex auto-loads the resolved workspace's AGENTS.md and discovers skills in its .agents/skills/ and user-global $CODEX_HOME/skills/ (default ~/.codex/skills/), reachable from outside the workspace.

Review your git changes in the background; get a job_id back immediately.

PAID — this spends Codex quota on every new call; use codex_dry_run or codex_status (both free) first if you only need to check scope or readiness.

Same read-only behavior as codex_review_changes (the diff is gathered, secret- redacted, and bounded, then reviewed read-only), but detached — prefer it for a multi-file or whole-branch review that can exceed the synchronous deadline (built-in default 300s), since a sync run whose deadline expires loses its partial work; this job's own deadline is separately configured (built-in default 1800s). The diff is gathered inside the job, so a bad base/commit comes back as the same structured error with zero spend (a bad scope is rejected by MCP input validation before the job starts). Starting a job commits to spend. Poll codex_job_status; read/consume the review envelope with codex_job_result/codex_job_consume_result; stop with codex_job_cancel. Pass workspace_root (absolute).

Data egress: same as codex_review_changes — sends the secret-redacted diff plus your raw (unredacted) extra_context to OpenAI via the codex CLI; Codex may also read other repo files. Codex auto-loads the resolved workspace's AGENTS.md and discovers skills in its .agents/skills/ and user-global $CODEX_HOME/skills/ (default ~/.codex/skills/), reachable from outside the workspace. Redaction is best-effort, not a guarantee.

Preview what a codex_review_changes call would send — scope, diff size, redactions, truncation. Free — no model call, no spend. Use it before a review to inspect the scope and the reported redactions; redaction is best-effort, so treat the preview as a check on scope, not as confirmation that no secret remains. Pass the same extra_context and untracked policy you would give the review so the preview matches it. would_call_model reports whether the paid call would actually run the model (False on an empty diff, where prompt_bytes is 0), and coverage discloses omitted untracked files just as the review would. The result echoes the effective model/reasoning_effort overrides the paid call would send (unvalidated). deadline_advisory is non-null when size or effort risks the synchronous deadline (null whenever would_call_model is False) and names codex_review_changes_async verbatim — the async counterpart of the previewed call, not of this dry-run tool. A hint, not a refusal.

Preview what a codex_delegate/codex_delegate_async call would do — the baseline it seeds from (HEAD commit, tracked file count/size, uncommitted and untracked counts), the prompt size that would be sent, and the resolved workspace/isolation. Free — no model call, no spend, no worktree created.

Use it before delegating to confirm scope and repo before committing to cost, exactly as codex_dry_run previews codex_review_changes. Mirrors the real delegate's zero-spend validation (workspace, isolation, task size, git repo), so a failure here is a failure the paid call would also hit. The returned tier/sandbox describe the previewed propose run, not this read-only preview; the result echoes the effective model/reasoning_effort overrides the paid call would send (unvalidated). deadline_advisory is non-null when size or reasoning effort risks the synchronous deadline and names codex_delegate_async verbatim — the async counterpart of the previewed call, not of this dry-run tool. A hint, not a refusal.

Check a background job's lifecycle state without fetching the full result.

Use after any *_async call (codex_delegate_async, codex_consult_async, codex_review_changes_async) or any sync consult/review/delegate (whose meta.job_id names its record). Returns status, elapsed time, expiry, and result_available; when it is true, call codex_job_result. result_ok reports a done job's producer-declared outcome — true (success), false (a stored error envelope), or null (running, no stored envelope, an unclassifiable payload, or a record finalized before this field) — so you can spot a stored FAILURE without fetching it. It does not guarantee the payload is still fetchable; a cross-release record may report an outcome yet fail codex_job_result with job_result_incompatible. Free — no model call.

Honor poll_after_ms between polls — for a running job it GROWS with elapsed runtime (bounded), so following it backs you off instead of tight-looping (a delegate often runs ~20s). expires_at is null while running and is set once the job finishes; results are then retained ttl_seconds past that completion.

Fetch a finished background Codex job's result WITHOUT deleting the record.

Works for any async job or sync consult/review/delegate (whose meta.job_id names its record) — codex_delegate_async (a diff), codex_consult_async (a consult answer), or codex_review_changes_async (a review with verdict). Use when codex_job_status reports result_available=true; the envelope matches the job's kind, so branch on tool. meta.job_id is set. A still-running/cancelled/timed- out/failed job returns an error envelope — as does a done job whose stored result this release cannot read (job_result_incompatible). To fetch and delete, use codex_job_consume_result. Free — no model call.

detail="summary" (default) omits the raw model text; pass detail="full" for the complete raw output and metadata (#56).

Fetch a finished background Codex job's result and delete the stored record.

Same envelope as codex_job_result (matching the job's kind — branch on tool), then removes completed job state — but only once the stored result has been read intact and validated (a success or the job's own error envelope): a stored result this release cannot read (job_result_incompatible or a corruption internal_error) is NOT deleted, so it stays inspectable via codex_job_result. Deletion precedes the response, so a response lost in transit does not restore the record; a failed removal retains the record until its TTL (codex_job_status still shows it). Use only when you no longer need to poll or re-read the job. Non-done jobs are not deleted. Free — no model call.

detail works as in codex_job_result (#56).

Cancel a running background Codex job.

Asks the worker to shut down gracefully so it tears down its throwaway worktree, then force-kills it if it overstays, and marks the job cancelled (cancelled jobs cannot be resumed). If the worktree could not be removed, cleanup_warnings names the leftover path. Already-terminal jobs are returned unchanged, so cancel is idempotent — a retry after a lost response is safe. Free — no model call.

List the background jobs known for this workspace, newest first.

Free — no model call. Use to recover job_ids lost across context compaction or interruption. Returns each job's id, kind, status, start time, result_available, result_ok (a done job's outcome — true/false/null; see codex_job_status), and expiry, so a stored failure is triageable without fetching each result.

Returns every retained job by default; pass limit (1-1000) or status to narrow. They narrow independently — omitting limit returns every job matching status, not every job. Only an explicit limit truncates: when more jobs match, the response sets truncated: true with a truncation_hint — the extra rows are dropped, not paged, so omit limit to get them all rather than looking for a cursor.

Read a job's result promptly — a finished record can silently drop off. This list is not permanent storage: terminal records expire after the TTL (default 24h), and a per-workspace soft cap (default 50, clamped 1-1000) evicts the oldest terminal records as new jobs start, so a finished job can disappear even before its expires_at. Running jobs are never evicted, so a busy workspace can hold more than the cap — and more than limit's 1000 ceiling. Includes sync-originated records (any sync consult/review/delegate call); the cap/TTL eviction covers both.