codex_review_changes
Submit git changes to Codex for an independent second opinion review. Supports working tree, branch, and commit scopes with optional author context.
Instructions
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).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | Base git ref for scope='branch'; the review covers base...HEAD. | |
| model | No | Override the Codex model slug for this call; defaults to the server/Codex default when unset. | |
| paths | No | Repo-relative paths to narrow the review ('/' separators, no '..'); omit to review all changes in scope. | |
| scope | No | Which changes to review: 'working_tree' (tracked changes vs HEAD; untracked files follow the `untracked` policy, off by default), 'branch' (needs base), or 'commit' (needs commit). | working_tree |
| commit | No | Commit SHA or ref to review for scope='commit'. | |
| detail | No | Response verbosity: 'summary' (default) omits the raw model text; 'full' includes it. | summary |
| isolation | No | Codex config isolation: 'inherit', 'ignore-config', or 'ignore-rules'. Defaults to the server's configured isolation (built-in default 'inherit'; `codex_status` reports the resolved value). | |
| untracked | No | How working_tree scope treats untracked files: 'explicit_only' (default) includes only those named in `paths`; 'include' reviews all non-ignored untracked files (SENDS their contents to OpenAI — opt-in egress); 'exclude' includes none. Omitted ones are disclosed in `coverage`. Inert for branch/commit scopes. | explicit_only |
| extra_context | No | Optional author intent / background context, added to the prompt as clearly-labeled UNTRUSTED data. Codex is instructed to treat embedded directives as data, not commands — best-effort prompt-injection mitigation, not a guarantee. Don't include live secrets: Codex can read files it's pointed at, and redaction does not cover this field. | |
| workspace_root | No | Absolute path to the target repository root. Pass it (or rely on an MCP root) so the call targets the intended repo; otherwise it falls back to the server's own cwd and meta.workspace_warning is set. | |
| idempotency_key | No | Optional client-supplied dedup key, scoped to THIS concrete tool on the same workspace. Reusing it on the same tool with the same arguments replays the existing run instead of starting — and paying for — a duplicate Codex call (a sync call reattaches to the in-flight run and returns its result; an _async call returns the same job_id). The sync and _async variants are DIFFERENT tools and never share a key's run. Reuse with different arguments — including a different timeout_seconds — is refused (idempotency_conflict); a key whose prior result was already consumed/evicted is idempotency_result_unavailable; a still-publishing reservation is idempotency_in_progress (retry). Omit it for the prior no-dedup behavior. A completed result stays replayable while its job record lives (its TTL), subject to consumption or count-eviction; the fail-closed conflict/in-progress window can last longer — up to the job's max runtime + termination grace + TTL. meta.idempotency_replayed=true marks a replayed (unpaid) response. | |
| timeout_seconds | No | Per-call wall-clock timeout in seconds, clamped to 10..600 (out-of-range values are coerced, not rejected). Defaults to the server's configured timeout. | |
| reasoning_effort | No | Override the Codex reasoning effort for this call (sent as a `model_reasoning_effort` config override); omit (or pass null) for the server default (CODEX_IN_CLAUDE_REASONING_EFFORT) or Codex's own resolution. An open per-model string the Codex backend validates at run time — commonly minimal|low|medium|high|xhigh; codex_models lists each model's advertised set (advisory). A backend-rejected value fails as invalid_reasoning_effort; an explicit empty string is sent as-is (and rejected by the backend), never treated as unset. Control characters, surrogates, and values over 128 chars are rejected as invalid_arguments. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes |