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. 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. Pass include_schemas to also embed the full error-envelope / result-meta schemas (a tool-reachable fallback to the codex:// resources for resource-blind clients).

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.

Runs codex exec in a read-only sandbox — Codex never edits files. This is a STATIC review, not a verify mode: the read-only sandbox blocks the writes a test/build/lint run typically needs (a writable cache/temp), so Codex can't rely on executing your checks to confirm its claims. For a repo-grounded question, pass workspace_root (absolute) so Codex reasons about the right repo; it is optional for pure Q&A that needs no codebase. Returns a result envelope. Treat findings as unvalidated claims; verify them by running the checks yourself.

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 also auto-loads context from that workspace — the project's AGENTS.md and any skills under .agents/skills/ — so their content can be sent even if your prompt never mentions them; the plugin's isolation flags do not suppress this project-level context. 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 until Codex finishes (timeout clamped 10-600s via timeout_seconds), streaming coarse notifications/progress when your client requests it; the detached run (meta.job_id) is recoverable via codex_job_list→codex_job_result if the connection drops, and codex_consult_async runs the same work fire-and-forget (poll codex_job_status).

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

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.

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.

extra_context (optional) is author intent — why the change was made, what you already verified, constraints — added to the prompt as clearly-labeled UNTRUSTED data (Codex is instructed to treat embedded directives as data, not commands — a best-effort injection mitigation, not a guarantee) to cut false positives. It is bounded by the same input-byte limit as the diff.

STATIC review, not a verify mode: the read-only sandbox blocks the writes a test/build/lint run typically needs (a writable cache/temp), so Codex can't rely on running the project's checks to confirm its findings. Treat findings as unvalidated claims to verify by running those checks 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 — including the workspace's AGENTS.md and .agents/skills/ skills, which it auto-loads even if your prompt never mentions them (the plugin's isolation flags do not suppress this). 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 until Codex finishes (timeout clamped 10-600s via timeout_seconds), streaming coarse notifications/progress when your client requests it; the detached run (meta.job_id) is recoverable via codex_job_list→codex_job_result if the connection drops, and codex_review_changes_async runs the same work fire-and-forget (poll codex_job_status).

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.

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. The tracked AGENTS.md and .agents/skills/ skills seeded into the worktree auto-load there too — their content can be sent even if your task never mentions them (the plugin's isolation flags do not suppress this). Your task is sent raw — secret redaction is best-effort and does not cover it or files Codex reads itself.

Progress & recovery: blocks until Codex finishes (timeout clamped 10-600s via timeout_seconds), streaming coarse notifications/progress when your client requests it; the detached run (meta.job_id) is recoverable via codex_job_list→codex_job_result if the connection drops, and codex_delegate_async runs the same work fire-and-forget (poll codex_job_status).

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

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 it runs detached. Starting a job commits to spend (it runs to completion or its wall-clock deadline even if you never poll). Poll with codex_job_status, read with codex_job_result, delete after successful read with codex_job_consume_result, or 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 — including the tracked AGENTS.md and .agents/skills/ skills, which auto-load in the worktree. 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.

Same read-only behavior as codex_consult (Codex never edits files), but it runs detached — use it when the consult may run long. Starting a job commits to spend (it runs to completion or its wall-clock deadline even if you never poll). Poll with codex_job_status, read the consult envelope with codex_job_result, delete it after successful read with codex_job_consume_result, or stop it 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), including the auto-loaded AGENTS.md/.agents/skills/ workspace context.

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

Same read-only behavior as codex_review_changes (the diff is gathered, secret- redacted, and bounded, then reviewed read-only), but it runs detached — use it when the review may run long. 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 an out-of-enum value rejected by MCP input validation before the job starts). Starting a job commits to spend. Poll with codex_job_status, read the review envelope with codex_job_result, delete it after successful read with codex_job_consume_result, or stop it 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, including the auto-loaded AGENTS.md/.agents/skills/ workspace context. Redaction is best-effort, not a guarantee.

Preview what a codex_review_changes call would send — scope, diff size, redactions, truncation — with NO model call and 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).

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 — with NO model call, NO spend, and 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).

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

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

Use to recover job_ids lost across context compaction or interruption. Returns each job's id, kind, status, start time, result_available, and expiry. Free — no model call.

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 the list can transiently exceed the cap. Includes sync-originated records (any sync consult/review/delegate call); the cap/TTL eviction covers both.