This server bridges Claude Code and OpenAI Codex CLI to implement a plan → execute → review workflow, enabling Claude to delegate coding tasks to Codex while retaining control over planning and review.
codex_execute: Start a new Codex session to implement a task or plan in a specified workspace, returning a session ID, agent messages, file changes, commands run, token usage, and a git diff of changes made.
codex_continue: Resume an existing Codex session with follow-up instructions (e.g., review feedback), preserving conversation context.
codex_review: Perform a read-only review of uncommitted workspace changes, returning findings ordered by severity. Never modifies files.
codex_health: Check the installed Codex CLI version and authentication/login status.
Live progress streaming: Optionally open a terminal window (Terminal.app on macOS, PowerShell on Windows, various emulators on Linux) to stream live Codex progress, plus real-time MCP notifications/progress updates for events like session start, file changes, and command runs.
Sandbox policy control: Choose between read-only, workspace-write (default), or danger-full-access modes to control what Codex is permitted to do.
Concurrency protection: Serializes runs per workspace to prevent race conditions, while allowing parallel runs across different workspaces.
Graceful cancellation: Forwards MCP cancellation signals (SIGTERM, then SIGKILL) to Codex and its subprocesses when a run is aborted.
Integrates with OpenAI Codex CLI to execute code tasks, review changes, and continue sessions, enabling a plan->execute->review workflow for AI agents.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codex-mcp execute the plan in .codex-flow/PLAN.md"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Plan with Claude · Execute with OpenAI Codex · Review with Claude
A Claude Code plugin and MCP server that runs a disciplined plan → execute → review loop:
Claude interviews you and designs the plan, Codex writes the code, then Claude reviews each task
and the final pass alongside a required Codex codex_review; findings are compared, fixes go back,
and non-blocking improvements wait for your decision — all from a single command.
· macOS · Windows · Linux · Node ≥ 20 · MIT
1. Prerequisites — Node ≥ 20 and the Codex CLI, authenticated:
npm i -g @openai/codex
codex login # ChatGPT Plus/Pro/Team — or set OPENAI_API_KEY2. Install the plugin (bundles the /codex-flow command, ~60 skills, and the codex MCP server):
/plugin marketplace add anhnguyen0905/codex-mcp
/plugin install codex-flow@codex-mcpOnce listed in the Claude community directory, this also works:
claude plugin marketplace add anthropics/claude-plugins-community then
claude plugin install codex-flow@claude-community.
3. Run it in any project:
/codex-flow implement a dark-mode toggle on the settings page# from npm (recommended — ships a prebuilt dist, nothing to compile)
claude mcp add --scope user codex -- npx -y @anhnguyen0905/codex-mcp
# or straight from this repo, which builds from source on first run
claude mcp add --scope user codex -- npx -y github:anhnguyen0905/codex-mcpclaude mcp list should then show codex … ✔ Connected. Copy
commands/codex-flow.md to ~/.claude/commands/ for the workflow
command, or just use the plugin install above which bundles both.
codex-flow routes chart and graph tasks to flint-chart (Microsoft Research) via the
codex-flow:exec-visualization skill, rendering polished PNG/SVG charts instead of using ad-hoc
Python plotting.
Register the server with the Codex CLI in ~/.codex/config.toml:
[mcp_servers.flint-chart]
command = "npx"
args = ["-y", "flint-chart-mcp"]Register it with Claude:
claude mcp add flint-chart -- npx -y flint-chart-mcpThis setup is optional; when the server is not present, the exec-visualization skill degrades to
a fallback.
The plugin is distributed as a git clone and dist/ is gitignored, so up to v0.14.0 a freshly
installed plugin had no build and its node dist/index.js launcher exited immediately.
Since v0.15.1 the bundled .mcp.json runs the published npm tarball
(npx -y @anhnguyen0905/codex-mcp@<version>), which ships a prebuilt dist/ — nothing is compiled
at install time. Updating the plugin is the fix:
/plugin update codex-flow@codex-mcpIf you are pinned to an older version, patch that install once instead:
cd ~/.claude/plugins/cache/codex-mcp/codex-flow/<version>
npm install --no-audit --no-fund && npm run buildThen restart Claude Code and confirm with claude mcp list (or call codex_health).
Related MCP server: MCP-Claude Code Bridge
Claude Code ──(MCP stdio)──▶ codex-mcp ──spawns──▶ codex exec --json/codex-flow runs six phases, keeping Claude as the planner/reviewer and Codex as the implementer:
Phase | Owner | What happens |
0 · Preflight | Claude | Verify Codex login; baseline git + tests; resume an interrupted run. |
1 · Interview | Claude | Clarify requirements until every acceptance criterion is verifiable. |
2 · Plan | Claude | Explore the codebase, select relevant skills, write |
3 · Backlog | Claude | Decompose into dependency-ordered tasks in |
4 · Execute | Codex | Implement one task at a time — or several in parallel (see below). |
5 · Review | Claude + Codex | Dual-review each task and the final pass via Claude + required |
The bundled session-report skill writes a per-session bundle to .codex-flow/reports/<YYYYMMDD-HHMMSS>/ with planning, allocation, task, cost, and summary reports plus explicit claude / codex / both PIC attribution.
The server spawns codex exec non-interactively, parses its JSONL event stream, and returns a
structured result (sessionId, agentMessage, fileChanges, commands, token usage, diff).
Instead of blind-loading whole skill collections, /codex-flow selects only the skills a task
needs from a local index: it classifies the request's role facets (engineering, data,
marketing, growth, research, design…) and loads every relevant skill that fits a context budget
(~3% of the window), embedding distilled rule blocks into the Codex prompts. Skills on disk cost
zero context until selected; third-party skills are vetted once before first use.
The index covers ~/.claude/skills, ~/claude-skill-library, and the skills/ dir of every
installed plugin (newest version per plugin) — so selection knows about skills the machine
already has instead of reporting a gap. And a domain facet never ends with zero skills: when
nothing indexed fits, Step 7 re-indexes, vets, searches (gh/catalog/web), and — failing all of
that — authors the missing SKILL.md before execution, so the library grows toward the work.
node scripts/sync-awesome-skills.mjs --clone # build a local library from awesome-claude-skills
node scripts/build-skills-index.mjs # → ~/.claude/skill-library/INDEX.mdBesides the phase skills, the plugin ships 17 domain skills authored through Step 7 — paid media, unit economics, media planning, warehouse modeling, event taxonomy, attribution, causal inference, survey design, ASO, localisation, OKRs, creative briefs, influencer strategy, SOPs and data-quality checks, and agent context persistence — so they are indexed and selectable out of the box. Their numeric thresholds are labelled derived, unverified: replace them with your own account history before treating any of them as a target.
Verified by a 32-scenario scope eval (npm run skills:eval) — latest 32/32 — plus a
100-request non-engineering scope run (data analysis, marketing planning, performance marketing,
market research, content, product): 99/100 covered by an existing skill, at precision@1 84/99,
with the remaining case queued for Step 7 acquisition/authoring. Full procedure:
skills/skill-selection/SKILL.md.
scripts/context-slice.mjs generates budgeted derived slices from .codex-flow/PLAN.md and
.codex-flow/TASKS.md: per-task .codex-flow/CONTEXT-T<n>.md files (≤ 4000 estimated tokens
using the chars/4 heuristic) and .codex-flow/RESUME.md on resume (≤ 8000 estimated tokens
using the chars/4 heuristic). Decision-log blocks carry a git-SHA Anchor:, and slices stamp each
block [fresh] or [verify]; anything unverifiable — including a missing or invalid anchor or a
git failure — degrades to [verify].
scripts/project-context.mjs writes .codex-flow/PROJECT.md, the durable project brief Codex
reads on every task: --generate derives it from the repo (what it is, users, layout, constraints,
quality mechanisms, known limitations, direction) and --refresh regenerates the generated parts
while preserving any <!-- owner-notes --> blocks the team added. /codex-flow Phase 0 generates it
on a fresh run when it is absent and has the user confirm or edit it in the interview; Phase 2 reads
it before exploring; Phase 5 proposes a --refresh (with the diff shown for confirmation) when a
Decision-log block records a contract deviation or an architecture change. It is a tracked project
file, not run state — committed with the run, never archived with it — and slices carry it as a
## Project context item capped at 600 tokens.
Mandatory task text and task statuses are never dropped. Lower-priority content is dropped whole
when necessary, with a restorable
(+N lower-priority items omitted — read .codex-flow/PLAN.md …) pointer. Full
.codex-flow/PLAN.md remains the on-disk source of truth. The slice helper is required: when it is
missing or exits non-zero the flow stops and asks for a plugin reinstall instead of degrading.
.codex-flow/REQUIREMENTS.md records confirmed acceptance criteria verbatim with atomic
R<n>.<m> IDs. Mid-run changes append confirmed ADDED/MODIFIED/REMOVED Deltas instead of
rewriting history, and reset affected downstream approvals.
.codex-flow/STATE.md is the resume authority instead of file existence. Its 10-key run state
tracks the phase, three approvals, immutable runBaselineRef / known-red / dirty-baseline values,
checkpoint choice, execution mode, and a separate resumeHead.
scripts/requirements-coverage.mjs rejects uncited or unknown criterion IDs at the Phase 3 gate;
final review then walks every ID and records met/not-met with evidence.
TASKS.md records session lineage and an append-only status-transition log. Resume reconciles orphaned in-progress work, while wave scheduling seeds dependencies from done tasks, waits on in-progress tasks, and blocks dependents of failed or unknown states.
In parallel mode, one coordinator writes .codex-flow/*; workers return structured handoffs with
touched files, checks, findings, decision-log proposals, and session IDs.
Context slices always carry a stamped contracts index, compact known-red failures, and rank
decision blocks by explicit Applies to: scope before recency; the execution prompt carries the
run-position recitation header.
codex-mcp serializes runs per workspace but parallelizes across workspaces, so independent tasks can run concurrently — each in its own git worktree driven by a Claude subagent, then merged and integration-reviewed per wave.
npm run waves # compute execution waves from .codex-flow/TASKS.mdWaves batch tasks whose dependencies are met and whose files are disjoint, capped at 10
concurrent subagents (--max <n> to lower). Parallel is the default when task-waves reports
width > 1: waves of ≤3 run automatically, while wider waves ask first; parallel execution costs
N× simultaneous quota. Playbook:
skills/parallel-execution/SKILL.md.
Tool | Purpose |
| Start a new Codex session executing a task/plan |
| Resume a session with follow-up (e.g. review feedback) |
| Read-only review of uncommitted workspace changes |
| Run up to 50 tasks in parallel across distinct workspaces (worktrees) |
| List prior Codex sessions (from |
| Aggregate token/duration/failure metrics from the local run log |
| Check Codex CLI version and login status |
codex_execute / codex_continue / codex_review accept writeNotes: true to persist a markdown
summary of the run to <cwd>/.codex-flow/notes/<sessionId>.md.
When Codex is not logged in or unreachable, /codex-flow no longer stops dead: it offers an
explicit Executor fallback (fix Codex and re-check, or let Claude execute the backlog under the
same plan/review contract, with an independent subagent review replacing codex_review). The choice
is recorded in .codex-flow/STATE.md as executor: and is never made silently or mid-task.
Every codex_execute / codex_continue / codex_review payload carries accepted: boolean, a
fail-closed delivery verdict: status === "success" AND the acceptance evidence holds — the
verifyCommand passed (when given), or for codex_review the findings block parsed. It never
changes status/isError; read it before trusting agentMessage. codex_review is never
auto-resumed: a timed-out or partial review is reported after one attempt.
codex_review asks Codex to end its message with one fenced json block and returns it parsed
fail-closed as reviewFindings: { parsed, findings[], improvements[], dropped, droppedReasons, parseError? } (severity is one of CRITICAL/HIGH/MEDIUM/LOW; malformed entries are counted in
dropped, never coerced). droppedReasons: string[] carries one entry per dropped item, naming the
field that failed validation (for example findings[0].line, or the bare locator findings[0] when
the whole entry is invalid), so dropped is always droppedReasons.length. Any dropped > 0 makes
accepted false for codex_review — a review that lost an entry is never treated as delivered. The
prose agentMessage is still returned for the parsed: false case.
codex_execute / codex_continue accept verifyCommand (plus optional verifyTimeoutMs, default
10 min, cap 30): after the Codex run settles, the server runs that acceptance command in cwd
(still inside the workspace lock) and returns verification: { command, exitCode, timedOut, durationMs, outputTail, passed, skipped? }. This is deterministic evidence that the acceptance
check ran — independent of Codex's own claim. It is skipped (skipped: "run-failed") when the run
itself failed or aborted, and it never changes the run's status/isError. Termination is bounded
(SIGTERM → tree SIGKILL → forced settle) so a hung check can never hold the workspace lock. The
command runs with the server's environment, and its output tail passes through the same redaction
pass as every other returned text — treat it with the same trust as Codex's own output.
codex_execute / codex_continue / codex_review and each codex_batch task accept
reasoningEffort: minimal | low | medium | high | xhigh, passed to Codex as
-c model_reasoning_effort="<value>".
Secret redaction. Every returned or persisted text — agentMessage, stderr, errors,
verification.outputTail, live-progress notifications, the raw JSONL live log, and writeNotes
run notes — is redacted before it leaves the server: each known secret shape (OpenAI/GitHub/AWS/
Slack/Google keys, bearer tokens, JWTs, PEM private keys, SECRET/TOKEN/KEY-style env
assignments) is replaced by [REDACTED:<kind>]. codex_execute / codex_continue / codex_review
report redactions: <n> (and each codex_batch task result its own redactions, with
redactionsTotal on the batch payload) whenever the count is above zero; the fields are omitted at
zero. Redaction is idempotent and never changes status, isError, accepted, or a
verification.passed verdict.
Auth mode & the model guard. codex_health always returns
authMode: "chatgpt" | "apikey" | "unknown", derived from the Codex CLI login output. Under
ChatGPT auth a model override is refused before anything is spawned — codex_execute /
codex_continue / codex_review return an error and a codex_batch task fails with
model override is not allowed under ChatGPT auth; steer with reasoningEffort — because the
ChatGPT-auth backend rejects arbitrary model ids. So pass model only when authMode is
apikey; otherwise omit it and steer with reasoningEffort. /codex-flow Phase 4 follows the same
rule, and a flowDocs guard checks that wording.
Review scope. codex_review accepts scope: { files: string[]; contract?: string } (files
non-empty, up to 200 entries; contract up to 4000 chars). The server appends the contract and the
file list to the reviewer prompt and stamps every parsed finding with inScope: boolean, plus
reviewFindings.outOfScopeCount for the findings outside the declared files. Out-of-scope findings
are non-blocking by default — /codex-flow routes them to the improvements ledger and blocks only
when the reviewer verifies they affect the task's acceptance.
Metrics history & completeness. codex_metrics accepts includeHistory: true to aggregate the
archived history/*.jsonl back-files alongside the live and rotated log (default false, with
historyFiles / historyExcluded reported when archives exist). Every aggregate carries
completeness: { complete, unpricedRuns, missingUsage, readErrors, historyExcluded } so an
incomplete roll-up is visible instead of silent. Note that the shipped COST_TABLE is empty and
CODEX_MCP_PRICING does not fill it, so any run that reported usage counts as unpriced:
completeness.complete is never true for usage-bearing entries in this release.
Sandbox modes: read-only, workspace-write (default), danger-full-access. Default execution
timeout is 60 min (timeoutMs caps at 2 h). Runs into the same cwd are serialized; different
workspaces run in parallel.
By default, the server automatically resumes the same session after a transient turn failure
(at most 2 resumes), timeout (at most 1), or partial result caused by a missing completion marker
or parse errors (at most 1, reported as no-completion-marker), with 2 s then 8 s backoff (8 s
for any later resume). Set CODEX_MCP_AUTO_RESUME=0 to opt out.
Every run tool returns sessionId, agentMessage, fileChanges, commands, token usage,
errors, plus:
diff — git status --porcelain + git diff HEAD after the run (64 KB cap, truncated
flag; null outside a git repo) so the caller can review without re-reading files.
aborted — true when cancelled from the client (Esc in Claude Code); the server forwards
cancellation to Codex (SIGTERM → SIGKILL after 5 s).
attempts / resumeReasons — total attempts and the ordered reasons for automatic resumes;
each codex_batch task result carries the same fields.
liveLog — path to the raw JSONL event log when the live terminal view is enabled.
Clients that send an MCP progressToken (Claude Code does) get notifications/progress for every
meaningful Codex event. Set terminal: true (or CODEX_MCP_TERMINAL=1) to also open a live-tailing
window — Terminal.app on macOS, PowerShell on Windows, the first available emulator on Linux. On
macOS, the window closes itself about 4 seconds after a successful run; it stays open after a failed
or interrupted run. The delay defaults to 4000 ms; 0 closes immediately, and values above 60000
are clamped. Windows and Linux windows already close with their process. If no window can open, the
run still succeeds; follow the liveLog or the in-session progress instead.
Variable | Effect |
| Auth for Codex CLI (alternative to |
| Override the Codex binary path/name (e.g. |
| Open the live-progress window by default. |
| Never auto-close the live-progress window (the value must be exactly |
| Set the close delay in ms; negative, non-integer, or unparseable input uses |
| Disable bounded server-side session auto-resume. |
| Override the skill index path. |
| Raise Claude Code's MCP tool timeout (ms) for long runs. |
No credentials handled. The server never reads, stores, or transmits your credentials — auth
is handled entirely by the Codex CLI (~/.codex/). Run npm run doctor to verify your setup.
No network calls of its own. The MCP server only spawns the local codex CLI (and git for
diffs). All model traffic is Codex's, under your OpenAI account and its data policies.
Local-only telemetry. Run metrics (tokens, durations, exit codes, a 200-char error head) are
appended to ~/.codex-mcp/metrics.jsonl on your machine and never uploaded. Live-progress logs
and run notes stay under the project's gitignored .codex-flow/.
Sandboxed writes. Codex runs in workspace-write by default; codex_review is always
read-only; danger-full-access is never used unless a task explicitly needs it and the user is
told first. Per-cwd locks serialize runs into the same workspace.
Caller-defined commands. verifyCommand runs the acceptance command you pass, in your
workspace, with the server's environment; its output tail is redacted like every other returned
text, but treat it with the same trust as any other shell output. Third-party skills are loaded only after a content-pinned vet
(skill-selection).
Report vulnerabilities per SECURITY.md.
npm test # unit tests (vitest)
npm run coverage # enforces 80% thresholds
npm run build # tsc → dist/
npm run test:e2e # real end-to-end smoke test (spawns Codex, uses quota)Server (src/): index.ts (stdio entry) · server.ts (MCP tools, cwd lock, cancellation) ·
argsBuilder.ts (argv) · codexRunner.ts (spawn + timeout/kill) · eventParser.ts (JSONL →
result) · workspaceDiff.ts (git diff) · terminal.ts / liveView.ts / progressFormatter.ts /
progressNotifier.ts (live progress).
Skill & workflow scripts (scripts/): sync-awesome-skills.mjs · build-skills-index.mjs ·
skill-match.mjs · skill-eval.mjs · task-waves.mjs · session-cost.mjs · tail-progress.mjs.
Fan out N tasks across N cwds (typically git worktrees) with a bounded concurrency limit. Each task uses its own per-cwd lock, so callers must supply distinct cwds. Returns one result entry per input task in input order.
| Name | Required | Description | Default |
|---|---|---|---|
| tasks | Yes | Tasks to run in parallel, one per workspace. Each task uses its own cwd (must be unique in the batch). | |
| failFast | No | If true, cancel remaining tasks on the first failure. Default false (continue-on-error). | |
| maxConcurrency | No | Cap on parallel tasks (default 10, hard cap 32). |
| Name | Required | Description |
|---|---|---|
| tasks | Yes | |
| total | Yes | |
| failed | Yes | |
| summary | Yes | |
| redactionsTotal | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses per-cwd locking, the need for distinct cwds, bounded parallelism, and ordered result entries. It does not detail failure behavior or auth requirements, but the core behavioral traits are well covered beyond what the schema shows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler. The opening sentence states the core operation and scope, the second adds the critical locking constraint, and the third clarifies the return shape. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex batched tool, the description is complete: it explains parallelism, the workspace requirement, the uniqueness constraint, and the result ordering. The parameter schema covers the remaining details like defaults, limits, and timeouts, and an output schema exists, so return structure does not need to be restated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents tasks, failFast, and maxConcurrency. The description adds meaningful semantic context beyond the schema: distinct cwds are required because each task holds its own per-cwd lock, results are returned in input order, and parallelism is bounded. This helps an agent choose and fill parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fans out N tasks across N cwds in parallel, which is specific and distinct from the sibling tools that focus on single sessions or execution. It also names the resource (Codex tasks across workspaces) and includes the unique per-cwd lock requirement, so an agent can distinguish it from codex_execute or codex_sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: multiple tasks, multiple cwds, typically git worktrees, with a bounded concurrency limit. It also states a hard prerequisite (distinct cwds). However, it does not explicitly name alternatives or state when not to use the batch tool, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume an existing Codex session by sessionId with a follow-up prompt — typically review feedback that Codex should address. Preserves Codex context.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Absolute path of the workspace Codex should work in | |
| model | No | Codex model override | |
| prompt | Yes | Follow-up instruction, e.g. review findings to fix | |
| sandbox | No | Codex sandbox policy (default: workspace-write) | workspace-write |
| terminal | No | Open a Terminal window streaming live progress (default: env CODEX_MCP_TERMINAL=1) | |
| sessionId | Yes | Session/thread id returned by a previous codex_execute call | |
| timeoutMs | No | Max execution time per attempt in ms; auto-resume may add attempts (default: 60 minutes) | |
| writeNotes | No | Persist a markdown summary of this run to <cwd>/.codex-flow/notes/<sessionId>.md (default false). | |
| verifyCommand | No | Acceptance command the server runs in cwd AFTER the Codex run settles (e.g. the test suite). Its exit code and output tail are returned in `verification` — deterministic evidence, not Codex's claim. | |
| reasoningEffort | No | Reasoning effort override for the selected model | |
| verifyTimeoutMs | No | Max time for verifyCommand in ms (default 10 minutes, cap 30). |
| Name | Required | Description |
|---|---|---|
| diff | Yes | |
| runId | Yes | |
| usage | Yes | |
| errors | Yes | |
| status | Yes | |
| stderr | Yes | |
| aborted | Yes | |
| liveLog | Yes | |
| accepted | Yes | |
| attempts | No | |
| commands | Yes | |
| exitCode | Yes | |
| timedOut | Yes | |
| warnings | Yes | |
| notesPath | Yes | |
| sessionId | Yes | |
| turnCount | Yes | |
| redactions | No | |
| attribution | Yes | |
| fileChanges | Yes | |
| parseErrors | Yes | |
| agentMessage | Yes | |
| verification | No | |
| resumeReasons | No | |
| sawCompletion | Yes | |
| schemaVersion | Yes | |
| unknownEvents | Yes | |
| reviewFindings | No | |
| outputTruncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden of behavioral disclosure. It only states that the session is resumed and context preserved; it does not mention that Codex may execute in a mutable workspace, run verification commands, open a terminal, or persist notes. These are significant side effects for a code-execution tool and are not surfaced in the prose description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler: the action, target, and context-preserving benefit are all front-loaded. The description earns each word and is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (11 parameters, code execution), but the schema describes every parameter and an output schema exists, so the description is not required to restate details. It supplies the missing high-level purpose and typical usage. It stops short of full completeness because it omits safety/behavioral context that an annotation-lacking execution tool would benefit from, though the schema partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with meaningful descriptions for all 11 parameters, so the baseline is 3. The description adds only that the prompt is typically review feedback, which largely restates the schema's example for prompt. No additional parameter-level meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Resume an existing Codex session by sessionId with a follow-up prompt'. It also adds the key differentiator 'Preserves Codex context', which separates it from starting a new session. It does not explicitly name sibling tools, but the purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete use case: 'typically review feedback that Codex should address', so an agent knows when continuing is appropriate. It does not explicitly contrast with codex_execute or codex_review, nor state when not to use this tool, so it falls short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new Codex session that executes a plan/task in the given workspace. Returns sessionId (keep it to send review feedback later), agent message, file changes and commands run.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Absolute path of the workspace Codex should work in | |
| model | No | Codex model override, e.g. gpt-5.1-codex | |
| prompt | Yes | Task or plan for Codex to execute (can embed full plan text) | |
| sandbox | No | Codex sandbox policy (default: workspace-write) | workspace-write |
| terminal | No | Open a Terminal window streaming live progress (default: env CODEX_MCP_TERMINAL=1) | |
| timeoutMs | No | Max execution time per attempt in ms; auto-resume may add attempts (default: 60 minutes) | |
| writeNotes | No | Persist a markdown summary of this run to <cwd>/.codex-flow/notes/<sessionId>.md (default false). | |
| verifyCommand | No | Acceptance command the server runs in cwd AFTER the Codex run settles (e.g. the test suite). Its exit code and output tail are returned in `verification` — deterministic evidence, not Codex's claim. | |
| reasoningEffort | No | Reasoning effort override for the selected model | |
| verifyTimeoutMs | No | Max time for verifyCommand in ms (default 10 minutes, cap 30). |
| Name | Required | Description |
|---|---|---|
| diff | Yes | |
| runId | Yes | |
| usage | Yes | |
| errors | Yes | |
| status | Yes | |
| stderr | Yes | |
| aborted | Yes | |
| liveLog | Yes | |
| accepted | Yes | |
| attempts | No | |
| commands | Yes | |
| exitCode | Yes | |
| timedOut | Yes | |
| warnings | Yes | |
| notesPath | Yes | |
| sessionId | Yes | |
| turnCount | Yes | |
| redactions | No | |
| attribution | Yes | |
| fileChanges | Yes | |
| parseErrors | Yes | |
| agentMessage | Yes | |
| verification | No | |
| resumeReasons | No | |
| sawCompletion | Yes | |
| schemaVersion | Yes | |
| unknownEvents | Yes | |
| reviewFindings | No | |
| outputTruncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It mentions that the tool runs a task and returns file changes and commands run, which implies workspace mutation, but it does not state the default sandbox policy, potential side effects, or that this is an execution tool capable of modifying files. This is a significant gap for a code-execution tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence that front-loads the primary action, states the workspace scope, and lists meaningful return artifacts. There is no redundant wording or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 10-parameter execution tool with no annotations, the description is somewhat thin. It explains the core function and key return values, and the output schema covers return structure, but it omits safety-critical context such as the default sandbox being workspace-write and the existence of verification behavior. The description is adequate for basic selection but not fully complete for safe invocation without reading every schema field.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all ten parameters. The description does not add deeper parameter semantics, though mentioning sessionId as something to keep for later review provides mild context about the session lifecycle. This matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Start a new Codex session that executes a plan/task in the given workspace.' It clearly identifies the tool as a session-starter and executor, and the mention of 'new' helps distinguish it from sibling tools like codex_continue. The return values are also summarized, so an agent can tell what to expect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for starting a fresh execution rather than continuing or reviewing an existing session, but it does not explicitly name alternatives or state when not to use it. Sibling tools like codex_continue and codex_review are not referenced, leaving the agent to infer routing from the word 'new.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report installed Codex CLI version and login status. With deep=true, also run one bounded read-only Codex exec probe to detect quota/model outages that login status cannot see.
| Name | Required | Description | Default |
|---|---|---|---|
| deep | No | Also run one bounded read-only `codex exec` probe and report execProbe/execProbeMessage (default: false) |
| Name | Required | Description |
|---|---|---|
| version | Yes | |
| authMode | Yes | |
| loggedIn | Yes | |
| execProbe | No | |
| loginProbe | Yes | |
| redactions | No | |
| loginStatus | Yes | |
| execProbeMessage | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It usefully discloses that deep mode runs one bounded, read-only Codex exec probe, which communicates safety and limits. It also explains why deep mode matters by mentioning quota/model outage detection, though it does not detail potential latency, failure semantics, or network dependencies beyond the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences with no filler. The main output is stated first, and the optional deep behavior is clearly introduced second. Every phrase earns its place, including 'bounded' and 'read-only,' which carry important safety information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one optional boolean parameter, an output schema, and no nested structures. The description fully covers its purpose, the deep-mode extension, and the rationale for using it. Nothing needed for selecting or invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining why deep=true is useful—detecting quota/model outages that login status cannot see—rather than just restating the parameter's mechanics. This helps an agent decide whether to set deep=true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool reports installed Codex CLI version and login status, and optionally runs a health probe. This is a specific verb-resource pairing that makes the core purpose obvious, though it does not explicitly differentiate itself from sibling tools like codex_metrics or codex_sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The main purpose is clear: use this when you need CLI version, login status, or health-related outage detection. The deep=true behavior is explicitly tied to detecting quota/model outages that login status cannot see, providing a clear reason to enable it, but no direct comparisons or exclusions against sibling tools are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Roll up token/duration/failure counts from the local metrics log (~/.codex-mcp/metrics.jsonl). Set CODEX_MCP_PRICING (JSON: {inputPer1M, cachedInputPer1M, outputPer1M, reasoningOutputPer1M}) to include estCostUsd.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Filter by exact cwd. | |
| tool | No | Filter by which tool produced the run. | |
| since | No | ISO 8601 lower bound — only entries at or after this timestamp are aggregated. | |
| until | No | ISO 8601 upper bound. | |
| sessionId | No | Filter by session id. | |
| includeHistory | No | Also aggregate the archived history/*.jsonl files, not just the live + rotated log (default false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the full behavioral burden and does disclose the data source and the conditional CODEX_MCP_PRICING env var behavior. The read-only nature is reasonably implied by 'roll up ... from the local metrics log.' It could explicitly state side-effect-free behavior or missing-file handling, but the disclosure is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences: the first front-loads the action, resource, and source path; the second specifies the exact env var JSON shape. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose, data source, and optional cost-estimation setup, and the schema already documents all filters. Since there is no output schema, slightly more return-shape detail would improve completeness, but the mentioned 'token/duration/failure counts' and 'estCostUsd' provide a reasonable picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all six parameters and their filter meanings. The description adds no per-parameter detail beyond the schema, though it does provide useful context about the pricing environment variable affecting output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'Roll up token/duration/failure counts' from the local metrics log, with an exact file path. This clearly differentiates codex_metrics from the execution/session sibling tools by framing it as an aggregation/reporting tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says what the tool does but gives no guidance on when to use it instead of siblings like codex_sessions or codex_health. No exclusions, alternative conditions, or use-case context is provided, so the agent must infer when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ask Codex to review the uncommitted changes in a workspace (read-only sandbox, no files modified). Returns findings ordered by severity plus a sessionId usable with codex_continue.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Absolute path of the workspace to review | |
| focus | No | Optional focus for the review, e.g. "security of the auth module" | |
| model | No | Codex model override | |
| scope | No | Declared task scope. Findings gain `inScope` and reviewFindings gains `outOfScopeCount`; nothing is dropped, so an out-of-scope defect is still reported. | |
| terminal | No | Open a Terminal window streaming live progress (default: env CODEX_MCP_TERMINAL=1) | |
| timeoutMs | No | Max execution time per attempt in ms; auto-resume may add attempts (default: 60 minutes) | |
| writeNotes | No | Persist a markdown summary of this run to <cwd>/.codex-flow/notes/<sessionId>.md (default false). | |
| baselineRef | No | Optional git ref to review from: Codex reviews `git diff <baselineRef>..HEAD` plus current uncommitted changes, so checkpoint/merge commits made since the baseline are covered. | |
| reasoningEffort | No | Reasoning effort override for the selected model |
| Name | Required | Description |
|---|---|---|
| diff | Yes | |
| runId | Yes | |
| usage | Yes | |
| errors | Yes | |
| status | Yes | |
| stderr | Yes | |
| aborted | Yes | |
| liveLog | Yes | |
| accepted | Yes | |
| attempts | No | |
| commands | Yes | |
| exitCode | Yes | |
| timedOut | Yes | |
| warnings | Yes | |
| notesPath | Yes | |
| sessionId | Yes | |
| turnCount | Yes | |
| redactions | No | |
| attribution | Yes | |
| fileChanges | Yes | |
| parseErrors | Yes | |
| agentMessage | Yes | |
| verification | No | |
| resumeReasons | No | |
| sawCompletion | Yes | |
| schemaVersion | Yes | |
| unknownEvents | Yes | |
| reviewFindings | No | |
| outputTruncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the transparency burden and does add meaningful context: the review runs in a read-only sandbox, modifies no files, and produces severity-ordered findings. It does not disclose execution duration, auto-resume behavior, or the writeNotes side effect; the 'no files modified' claim is also slightly broad given that writeNotes can persist a file.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences carry the full message efficiently, with the purpose front-loaded, the safety property in a parenthetical, and the output format plus follow-up hook stated at the end. There is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The rich input schema and presence of an output schema mean the description does not need to restate parameter details or return structure. It provides the essential selection context and follow-up path, though explicitly naming execution-style alternatives such as codex_execute would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 9 parameters are already described in the input schema, including nested fields, defaults, and constraints, so the schema coverage is 100%. The description adds no additional input-parameter meaning beyond referring to the returned sessionId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair: 'review the uncommitted changes in a workspace.' It further distinguishes the tool from execution-style siblings by noting the read-only sandbox and that no files are modified, and it connects to codex_continue via the returned sessionId.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear trigger for when to use the tool: when uncommitted workspace changes should be reviewed by Codex. It also implies a follow-up workflow through codex_continue, but it does not explicitly mention alternatives or when-not conditions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover Codex sessions stored locally under ~/.codex/sessions/. Returns sessionId, cwd, and last activity for each, newest first. sessionId can be passed to codex_continue to resume. Filter by cwd to find sessions from a specific workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Filter to sessions whose recorded cwd matches this path exactly. | |
| limit | No | Cap on returned sessions (default 50, hard cap 500). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does well to clarify the tool's behavior: it is a read-only operation that returns session metadata. It specifies the return structure and sorting. It does not mention side effects or permissions, but for a list tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no redundancy. It front-loads the key information ('Discover Codex sessions') and provides essential details efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers all essential aspects: what the tool does, its parameters, return values, and relation to sibling tools (codex_continue). For a simple list tool with two parameters, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the cwd filter's purpose ('to find sessions from a specific workspace') and implicitly references the limit parameter via the schema. This additional context raises the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose: listing prior Codex sessions. It specifies the storage location, return fields (sessionId, cwd, last activity), and ordering (newest first). It also distinguishes itself by mentioning the connection to codex_continue for resuming sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to discover sessions) and provides a contextual use case: filtering by cwd to find sessions from a specific workspace. It also hints at the alternative of using codex_continue with the sessionId. However, it does not explicitly contrast with other siblings like codex_health or codex_review, so it loses a point for completeness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.25.0codex_batch12 fields changedOutput schema / properties / redactionsTotalAdded value: +{
+ "type": "number"
+}Output schema / properties / tasks / items / properties / exitCode / anyOfRemoved value: -[
- {
- "type": "number"
- },
- {
- "type": "null"
- }
-]Output schema / properties / tasks / items / properties / exitCode / typeAdded value: +[
+ "number",
+ "null"
+]Output schema / properties / tasks / items / properties / liveLog / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / tasks / items / properties / liveLog / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / tasks / items / properties / parsed / properties / agentMessage / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / tasks / items / properties / parsed / properties / agentMessage / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / tasks / items / properties / parsed / properties / commands / items / properties / exitCode / anyOfRemoved value: -[
- {
- "type": "number"
- },
- {
- "type": "null"
- }
-]Output schema / properties / tasks / items / properties / parsed / properties / commands / items / properties / exitCode / typeAdded value: +[
+ "number",
+ "null"
+]Output schema / properties / tasks / items / properties / parsed / properties / sessionId / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / tasks / items / properties / parsed / properties / sessionId / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / tasks / items / properties / redactionsAdded value: +{
+ "type": "number"
+}codex_continue19 fields changedInput schema / properties / verifyCommandAdded value: +{
+ "description": "Acceptance command the server runs in cwd AFTER the Codex run settles (e.g. the test suite). Its exit code and output tail are returned in `verification` — deterministic evidence, not Codex's claim.",
+ "type": "string"
+}Input schema / properties / verifyTimeoutMsAdded value: +{
+ "description": "Max time for verifyCommand in ms (default 10 minutes, cap 30).",
+ "exclusiveMinimum": 0,
+ "maximum": 1800000,
+ "type": "integer"
+}Output schema / properties / acceptedAdded value: +{
+ "type": "boolean"
+}Output schema / properties / agentMessage / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / agentMessage / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / commands / items / properties / exitCode / anyOfRemoved value: -[
- {
- "type": "number"
- },
- {
- "type": "null"
- }
-]Output schema / properties / commands / items / properties / exitCode / typeAdded value: +[
+ "number",
+ "null"
+]Output schema / properties / exitCode / anyOfRemoved value: -[
- {
- "type": "number"
- },
- {
- "type": "null"
- }
-]Output schema / properties / exitCode / typeAdded value: +[
+ "number",
+ "null"
+]Output schema / properties / liveLog / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / liveLog / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / notesPath / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / notesPath / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / redactionsAdded value: +{
+ "type": "number"
+}Output schema / properties / reviewFindingsAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "dropped": {
+ "type": "number"
+ },
+ "droppedReasons": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "findings": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "expected": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "file": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "inScope": {
+ "type": "boolean"
+ },
+ "line": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "observed": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "severity": {
+ "enum": [
+ "CRITICAL",
+ "HIGH",
+ "MEDIUM",
+ "LOW"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "severity",
+ "file",
+ "line",
+ "summary",
+ "expected",
+ "observed"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "improvements": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "file": {
+ "type": "string"
+ },
+ "id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "summary": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "summary"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "outOfScopeCount": {
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+ },
+ "parseError": {
+ "type": "string"
+ },
+ "parsed": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "parsed",
+ "findings",
+ "improvements",
+ "dropped",
+ "droppedReasons"
+ ],
+ "type": "object"
+}Output schema / properties / sessionId / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / sessionId / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / verificationAdded value: +{
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "command": {
+ "type": "string"
+ },
+ "durationMs": {
+ "type": "number"
+ },
+ "exitCode": {
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "outputTail": {
+ "type": "string"
+ },
+ "passed": {
+ "type": "boolean"
+ },
+ "redactions": {
+ "type": "number"
+ },
+ "skipped": {
+ "enum": [
+ "aborted",
+ "run-failed"
+ ],
+ "type": "string"
+ },
+ "timedOut": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "command",
+ "exitCode",
+ "timedOut",
+ "durationMs",
+ "outputTail",
+ "passed"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+}Output schema / requiredPrevious value: -[
- "sessionId",
- "agentMessage",
- "fileChanges",
- "commands",
- "usage",
- "errors",
- "parseErrors",
- "unknownEvents",
- "sawCompletion",
- "warnings",
- "turnCount",
- "schemaVersion",
- "status",
- "runId",
- "diff",
- "attribution",
- "exitCode",
- "timedOut",
- "aborted",
- "outputTruncated",
- "stderr",
- "liveLog",
- "notesPath"
-]New value: +[
+ "sessionId",
+ "agentMessage",
+ "fileChanges",
+ "commands",
+ "usage",
+ "errors",
+ "parseErrors",
+ "unknownEvents",
+ "sawCompletion",
+ "warnings",
+ "turnCount",
+ "schemaVersion",
+ "status",
+ "accepted",
+ "runId",
+ "diff",
+ "attribution",
+ "exitCode",
+ "timedOut",
+ "aborted",
+ "outputTruncated",
+ "stderr",
+ "liveLog",
+ "notesPath"
+]codex_execute19 fields changedInput schema / properties / verifyCommandAdded value: +{
+ "description": "Acceptance command the server runs in cwd AFTER the Codex run settles (e.g. the test suite). Its exit code and output tail are returned in `verification` — deterministic evidence, not Codex's claim.",
+ "type": "string"
+}Input schema / properties / verifyTimeoutMsAdded value: +{
+ "description": "Max time for verifyCommand in ms (default 10 minutes, cap 30).",
+ "exclusiveMinimum": 0,
+ "maximum": 1800000,
+ "type": "integer"
+}Output schema / properties / acceptedAdded value: +{
+ "type": "boolean"
+}Output schema / properties / agentMessage / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / agentMessage / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / commands / items / properties / exitCode / anyOfRemoved value: -[
- {
- "type": "number"
- },
- {
- "type": "null"
- }
-]Output schema / properties / commands / items / properties / exitCode / typeAdded value: +[
+ "number",
+ "null"
+]Output schema / properties / exitCode / anyOfRemoved value: -[
- {
- "type": "number"
- },
- {
- "type": "null"
- }
-]Output schema / properties / exitCode / typeAdded value: +[
+ "number",
+ "null"
+]Output schema / properties / liveLog / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / liveLog / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / notesPath / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / notesPath / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / redactionsAdded value: +{
+ "type": "number"
+}Output schema / properties / reviewFindingsAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "dropped": {
+ "type": "number"
+ },
+ "droppedReasons": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "findings": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "expected": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "file": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "inScope": {
+ "type": "boolean"
+ },
+ "line": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "observed": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "severity": {
+ "enum": [
+ "CRITICAL",
+ "HIGH",
+ "MEDIUM",
+ "LOW"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "severity",
+ "file",
+ "line",
+ "summary",
+ "expected",
+ "observed"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "improvements": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "file": {
+ "type": "string"
+ },
+ "id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "summary": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "summary"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "outOfScopeCount": {
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+ },
+ "parseError": {
+ "type": "string"
+ },
+ "parsed": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "parsed",
+ "findings",
+ "improvements",
+ "dropped",
+ "droppedReasons"
+ ],
+ "type": "object"
+}Output schema / properties / sessionId / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / sessionId / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / verificationAdded value: +{
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "command": {
+ "type": "string"
+ },
+ "durationMs": {
+ "type": "number"
+ },
+ "exitCode": {
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "outputTail": {
+ "type": "string"
+ },
+ "passed": {
+ "type": "boolean"
+ },
+ "redactions": {
+ "type": "number"
+ },
+ "skipped": {
+ "enum": [
+ "aborted",
+ "run-failed"
+ ],
+ "type": "string"
+ },
+ "timedOut": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "command",
+ "exitCode",
+ "timedOut",
+ "durationMs",
+ "outputTail",
+ "passed"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+}Output schema / requiredPrevious value: -[
- "sessionId",
- "agentMessage",
- "fileChanges",
- "commands",
- "usage",
- "errors",
- "parseErrors",
- "unknownEvents",
- "sawCompletion",
- "warnings",
- "turnCount",
- "schemaVersion",
- "status",
- "runId",
- "diff",
- "attribution",
- "exitCode",
- "timedOut",
- "aborted",
- "outputTruncated",
- "stderr",
- "liveLog",
- "notesPath"
-]New value: +[
+ "sessionId",
+ "agentMessage",
+ "fileChanges",
+ "commands",
+ "usage",
+ "errors",
+ "parseErrors",
+ "unknownEvents",
+ "sawCompletion",
+ "warnings",
+ "turnCount",
+ "schemaVersion",
+ "status",
+ "accepted",
+ "runId",
+ "diff",
+ "attribution",
+ "exitCode",
+ "timedOut",
+ "aborted",
+ "outputTruncated",
+ "stderr",
+ "liveLog",
+ "notesPath"
+]codex_health6 fields changedInput schema / properties / deepAdded value: +{
+ "description": "Also run one bounded read-only `codex exec` probe and report execProbe/execProbeMessage (default: false)",
+ "type": "boolean"
+}Output schema / properties / authModeAdded value: +{
+ "enum": [
+ "chatgpt",
+ "apikey",
+ "unknown"
+ ],
+ "type": "string"
+}Output schema / properties / execProbeAdded value: +{
+ "enum": [
+ "ok",
+ "quota",
+ "model",
+ "error",
+ "skipped"
+ ],
+ "type": "string"
+}Output schema / properties / execProbeMessageAdded value: +{
+ "type": "string"
+}Output schema / properties / redactionsAdded value: +{
+ "type": "number"
+}Output schema / requiredPrevious value: -[
- "version",
- "loggedIn",
- "loginProbe",
- "loginStatus"
-]New value: +[
+ "version",
+ "loggedIn",
+ "loginProbe",
+ "loginStatus",
+ "authMode"
+]codex_metrics1 field changedInput schema / properties / includeHistoryAdded value: +{
+ "description": "Also aggregate the archived history/*.jsonl files, not just the live + rotated log (default false).",
+ "type": "boolean"
+}codex_review18 fields changedInput schema / properties / scopeAdded value: +{
+ "description": "Declared task scope. Findings gain `inScope` and reviewFindings gains `outOfScopeCount`; nothing is dropped, so an out-of-scope defect is still reported.",
+ "properties": {
+ "contract": {
+ "description": "The task contract the reviewer should check conformance against (max 4000 chars).",
+ "maxLength": 4000,
+ "type": "string"
+ },
+ "files": {
+ "description": "Paths the task is allowed to touch, relative to cwd (1-200 entries).",
+ "items": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "maxItems": 200,
+ "minItems": 1,
+ "type": "array"
+ }
+ },
+ "required": [
+ "files"
+ ],
+ "type": "object"
+}Output schema / properties / acceptedAdded value: +{
+ "type": "boolean"
+}Output schema / properties / agentMessage / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / agentMessage / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / commands / items / properties / exitCode / anyOfRemoved value: -[
- {
- "type": "number"
- },
- {
- "type": "null"
- }
-]Output schema / properties / commands / items / properties / exitCode / typeAdded value: +[
+ "number",
+ "null"
+]Output schema / properties / exitCode / anyOfRemoved value: -[
- {
- "type": "number"
- },
- {
- "type": "null"
- }
-]Output schema / properties / exitCode / typeAdded value: +[
+ "number",
+ "null"
+]Output schema / properties / liveLog / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / liveLog / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / notesPath / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / notesPath / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / redactionsAdded value: +{
+ "type": "number"
+}Output schema / properties / reviewFindingsAdded value: +{
+ "additionalProperties": false,
+ "properties": {
+ "dropped": {
+ "type": "number"
+ },
+ "droppedReasons": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "findings": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "expected": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "file": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "inScope": {
+ "type": "boolean"
+ },
+ "line": {
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "observed": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "severity": {
+ "enum": [
+ "CRITICAL",
+ "HIGH",
+ "MEDIUM",
+ "LOW"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "severity",
+ "file",
+ "line",
+ "summary",
+ "expected",
+ "observed"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "improvements": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "file": {
+ "type": "string"
+ },
+ "id": {
+ "minLength": 1,
+ "type": "string"
+ },
+ "summary": {
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "summary"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "outOfScopeCount": {
+ "maximum": 9007199254740991,
+ "minimum": 0,
+ "type": "integer"
+ },
+ "parseError": {
+ "type": "string"
+ },
+ "parsed": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "parsed",
+ "findings",
+ "improvements",
+ "dropped",
+ "droppedReasons"
+ ],
+ "type": "object"
+}Output schema / properties / sessionId / anyOfRemoved value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]Output schema / properties / sessionId / typeAdded value: +[
+ "string",
+ "null"
+]Output schema / properties / verificationAdded value: +{
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "command": {
+ "type": "string"
+ },
+ "durationMs": {
+ "type": "number"
+ },
+ "exitCode": {
+ "type": [
+ "number",
+ "null"
+ ]
+ },
+ "outputTail": {
+ "type": "string"
+ },
+ "passed": {
+ "type": "boolean"
+ },
+ "redactions": {
+ "type": "number"
+ },
+ "skipped": {
+ "enum": [
+ "aborted",
+ "run-failed"
+ ],
+ "type": "string"
+ },
+ "timedOut": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "command",
+ "exitCode",
+ "timedOut",
+ "durationMs",
+ "outputTail",
+ "passed"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+}Output schema / requiredPrevious value: -[
- "sessionId",
- "agentMessage",
- "fileChanges",
- "commands",
- "usage",
- "errors",
- "parseErrors",
- "unknownEvents",
- "sawCompletion",
- "warnings",
- "turnCount",
- "schemaVersion",
- "status",
- "runId",
- "diff",
- "attribution",
- "exitCode",
- "timedOut",
- "aborted",
- "outputTruncated",
- "stderr",
- "liveLog",
- "notesPath"
-]New value: +[
+ "sessionId",
+ "agentMessage",
+ "fileChanges",
+ "commands",
+ "usage",
+ "errors",
+ "parseErrors",
+ "unknownEvents",
+ "sawCompletion",
+ "warnings",
+ "turnCount",
+ "schemaVersion",
+ "status",
+ "accepted",
+ "runId",
+ "diff",
+ "attribution",
+ "exitCode",
+ "timedOut",
+ "aborted",
+ "outputTruncated",
+ "stderr",
+ "liveLog",
+ "notesPath"
+]v0.16.0codex_batchcodex_healthcodex_metricsv0.15.1codex_batchcodex_healthcodex_metricsv0.13.0codex_batch3 fields changedInput schema / properties / tasks / items / properties / reasoningEffortAdded value: +{
+ "description": "Reasoning effort override for the selected model",
+ "enum": [
+ "minimal",
+ "low",
+ "medium",
+ "high",
+ "xhigh"
+ ],
+ "type": "string"
+}Input schema / properties / tasks / items / properties / timeoutMs / descriptionAdded value: +"Max execution time per attempt in ms; auto-resume may add attempts (default: 60 minutes)"Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "failed": {
+ "type": "number"
+ },
+ "summary": {
+ "additionalProperties": false,
+ "properties": {
+ "aborted": {
+ "type": "number"
+ },
+ "failed": {
+ "type": "number"
+ },
+ "partial": {
+ "type": "number"
+ },
+ "succeeded": {
+ "type": "number"
+ },
+ "total": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "total",
+ "succeeded",
+ "failed",
+ "aborted",
+ "partial"
+ ],
+ "type": "object"
+ },
+ "tasks": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "aborted": {
+ "type": "boolean"
+ },
+ "attempts": {
+ "type": "number"
+ },
+ "attribution": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "files": {
+ "items": {
+ "additionalProperties": {},
+ "properties": {},
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "untracked": {
+ "items": {
+ "additionalProperties": {},
+ "properties": {},
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "files",
+ "untracked"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "cwd": {
+ "type": "string"
+ },
+ "diff": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "patch": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string"
+ },
+ "statusTruncated": {
+ "type": "boolean"
+ },
+ "truncated": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "status",
+ "statusTruncated",
+ "patch",
+ "truncated"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "error": {
+ "type": "string"
+ },
+ "exitCode": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "isError": {
+ "type": "boolean"
+ },
+ "liveLog": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "outputTruncated": {
+ "type": "boolean"
+ },
+ "parsed": {
+ "additionalProperties": false,
+ "properties": {
+ "agentMessage": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "commands": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "command": {
+ "type": "string"
+ },
+ "exitCode": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "required": [
+ "command",
+ "exitCode"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "errors": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "fileChanges": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "kind": {
+ "type": "string"
+ },
+ "path": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "path",
+ "kind"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "parseErrors": {
+ "type": "number"
+ },
+ "sawCompletion": {
+ "type": "boolean"
+ },
+ "sessionId": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "turnCount": {
+ "type": "number"
+ },
+ "unknownEvents": {
+ "type": "number"
+ },
+ "usage": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "cachedInputTokens": {
+ "type": "number"
+ },
+ "inputTokens": {
+ "type": "number"
+ },
+ "outputTokens": {
+ "type": "number"
+ },
+ "reasoningOutputTokens": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "inputTokens",
+ "cachedInputTokens",
+ "outputTokens",
+ "reasoningOutputTokens"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "warnings": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "sessionId",
+ "agentMessage",
+ "fileChanges",
+ "commands",
+ "usage",
+ "errors"
+ ],
+ "type": "object"
+ },
+ "resumeReasons": {
+ "items": {
+ "enum": [
+ "timeout",
+ "transient-turn-failure",
+ "no-completion-marker"
+ ],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "runId": {
+ "type": "string"
+ },
+ "schemaVersion": {
+ "type": "number"
+ },
+ "status": {
+ "enum": [
+ "success",
+ "partial",
+ "failed",
+ "aborted"
+ ],
+ "type": "string"
+ },
+ "stderr": {
+ "type": "string"
+ },
+ "taskIndex": {
+ "type": "number"
+ },
+ "timedOut": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "taskIndex",
+ "cwd",
+ "schemaVersion",
+ "status",
+ "parsed",
+ "diff",
+ "exitCode",
+ "timedOut",
+ "aborted",
+ "stderr",
+ "liveLog",
+ "isError"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "total": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "tasks",
+ "total",
+ "failed",
+ "summary"
+ ],
+ "type": "object"
+}codex_continue3 fields changedInput schema / properties / reasoningEffortAdded value: +{
+ "description": "Reasoning effort override for the selected model",
+ "enum": [
+ "minimal",
+ "low",
+ "medium",
+ "high",
+ "xhigh"
+ ],
+ "type": "string"
+}Input schema / properties / timeoutMs / descriptionPrevious value: -"Max execution time in ms (default: 30 minutes)"New value: +"Max execution time per attempt in ms; auto-resume may add attempts (default: 60 minutes)"Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "aborted": {
+ "type": "boolean"
+ },
+ "agentMessage": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "attempts": {
+ "type": "number"
+ },
+ "attribution": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "files": {
+ "items": {
+ "additionalProperties": {},
+ "properties": {},
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "untracked": {
+ "items": {
+ "additionalProperties": {},
+ "properties": {},
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "files",
+ "untracked"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "commands": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "command": {
+ "type": "string"
+ },
+ "exitCode": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "required": [
+ "command",
+ "exitCode"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "diff": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "patch": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string"
+ },
+ "statusTruncated": {
+ "type": "boolean"
+ },
+ "truncated": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "status",
+ "statusTruncated",
+ "patch",
+ "truncated"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "errors": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "exitCode": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "fileChanges": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "kind": {
+ "type": "string"
+ },
+ "path": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "path",
+ "kind"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "liveLog": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "notesPath": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "outputTruncated": {
+ "type": "boolean"
+ },
+ "parseErrors": {
+ "type": "number"
+ },
+ "resumeReasons": {
+ "items": {
+ "enum": [
+ "timeout",
+ "transient-turn-failure",
+ "no-completion-marker"
+ ],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "runId": {
+ "type": "string"
+ },
+ "sawCompletion": {
+ "type": "boolean"
+ },
+ "schemaVersion": {
+ "type": "number"
+ },
+ "sessionId": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "status": {
+ "enum": [
+ "success",
+ "partial",
+ "failed",
+ "aborted"
+ ],
+ "type": "string"
+ },
+ "stderr": {
+ "type": "string"
+ },
+ "timedOut": {
+ "type": "boolean"
+ },
+ "turnCount": {
+ "type": "number"
+ },
+ "unknownEvents": {
+ "type": "number"
+ },
+ "usage": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "cachedInputTokens": {
+ "type": "number"
+ },
+ "inputTokens": {
+ "type": "number"
+ },
+ "outputTokens": {
+ "type": "number"
+ },
+ "reasoningOutputTokens": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "inputTokens",
+ "cachedInputTokens",
+ "outputTokens",
+ "reasoningOutputTokens"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "warnings": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "sessionId",
+ "agentMessage",
+ "fileChanges",
+ "commands",
+ "usage",
+ "errors",
+ "parseErrors",
+ "unknownEvents",
+ "sawCompletion",
+ "warnings",
+ "turnCount",
+ "schemaVersion",
+ "status",
+ "runId",
+ "diff",
+ "attribution",
+ "exitCode",
+ "timedOut",
+ "aborted",
+ "outputTruncated",
+ "stderr",
+ "liveLog",
+ "notesPath"
+ ],
+ "type": "object"
+}codex_execute3 fields changedInput schema / properties / reasoningEffortAdded value: +{
+ "description": "Reasoning effort override for the selected model",
+ "enum": [
+ "minimal",
+ "low",
+ "medium",
+ "high",
+ "xhigh"
+ ],
+ "type": "string"
+}Input schema / properties / timeoutMs / descriptionPrevious value: -"Max execution time in ms (default: 30 minutes)"New value: +"Max execution time per attempt in ms; auto-resume may add attempts (default: 60 minutes)"Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "aborted": {
+ "type": "boolean"
+ },
+ "agentMessage": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "attempts": {
+ "type": "number"
+ },
+ "attribution": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "files": {
+ "items": {
+ "additionalProperties": {},
+ "properties": {},
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "untracked": {
+ "items": {
+ "additionalProperties": {},
+ "properties": {},
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "files",
+ "untracked"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "commands": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "command": {
+ "type": "string"
+ },
+ "exitCode": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "required": [
+ "command",
+ "exitCode"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "diff": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "patch": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string"
+ },
+ "statusTruncated": {
+ "type": "boolean"
+ },
+ "truncated": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "status",
+ "statusTruncated",
+ "patch",
+ "truncated"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "errors": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "exitCode": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "fileChanges": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "kind": {
+ "type": "string"
+ },
+ "path": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "path",
+ "kind"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "liveLog": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "notesPath": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "outputTruncated": {
+ "type": "boolean"
+ },
+ "parseErrors": {
+ "type": "number"
+ },
+ "resumeReasons": {
+ "items": {
+ "enum": [
+ "timeout",
+ "transient-turn-failure",
+ "no-completion-marker"
+ ],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "runId": {
+ "type": "string"
+ },
+ "sawCompletion": {
+ "type": "boolean"
+ },
+ "schemaVersion": {
+ "type": "number"
+ },
+ "sessionId": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "status": {
+ "enum": [
+ "success",
+ "partial",
+ "failed",
+ "aborted"
+ ],
+ "type": "string"
+ },
+ "stderr": {
+ "type": "string"
+ },
+ "timedOut": {
+ "type": "boolean"
+ },
+ "turnCount": {
+ "type": "number"
+ },
+ "unknownEvents": {
+ "type": "number"
+ },
+ "usage": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "cachedInputTokens": {
+ "type": "number"
+ },
+ "inputTokens": {
+ "type": "number"
+ },
+ "outputTokens": {
+ "type": "number"
+ },
+ "reasoningOutputTokens": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "inputTokens",
+ "cachedInputTokens",
+ "outputTokens",
+ "reasoningOutputTokens"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "warnings": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "sessionId",
+ "agentMessage",
+ "fileChanges",
+ "commands",
+ "usage",
+ "errors",
+ "parseErrors",
+ "unknownEvents",
+ "sawCompletion",
+ "warnings",
+ "turnCount",
+ "schemaVersion",
+ "status",
+ "runId",
+ "diff",
+ "attribution",
+ "exitCode",
+ "timedOut",
+ "aborted",
+ "outputTruncated",
+ "stderr",
+ "liveLog",
+ "notesPath"
+ ],
+ "type": "object"
+}codex_health1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "loggedIn": {
+ "type": "boolean"
+ },
+ "loginProbe": {
+ "enum": [
+ "ok",
+ "failed",
+ "timeout"
+ ],
+ "type": "string"
+ },
+ "loginStatus": {
+ "type": "string"
+ },
+ "version": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "version",
+ "loggedIn",
+ "loginProbe",
+ "loginStatus"
+ ],
+ "type": "object"
+}codex_review4 fields changedInput schema / properties / baselineRefAdded value: +{
+ "description": "Optional git ref to review from: Codex reviews `git diff <baselineRef>..HEAD` plus current uncommitted changes, so checkpoint/merge commits made since the baseline are covered.",
+ "maxLength": 256,
+ "minLength": 1,
+ "pattern": "^[A-Za-z0-9_][A-Za-z0-9_./@{}^~-]*$",
+ "type": "string"
+}Input schema / properties / reasoningEffortAdded value: +{
+ "description": "Reasoning effort override for the selected model",
+ "enum": [
+ "minimal",
+ "low",
+ "medium",
+ "high",
+ "xhigh"
+ ],
+ "type": "string"
+}Input schema / properties / timeoutMs / descriptionPrevious value: -"Max execution time in ms (default: 30 minutes)"New value: +"Max execution time per attempt in ms; auto-resume may add attempts (default: 60 minutes)"Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "aborted": {
+ "type": "boolean"
+ },
+ "agentMessage": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "attempts": {
+ "type": "number"
+ },
+ "attribution": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "files": {
+ "items": {
+ "additionalProperties": {},
+ "properties": {},
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "untracked": {
+ "items": {
+ "additionalProperties": {},
+ "properties": {},
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "files",
+ "untracked"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "commands": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "command": {
+ "type": "string"
+ },
+ "exitCode": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ }
+ },
+ "required": [
+ "command",
+ "exitCode"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "diff": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "patch": {
+ "type": "string"
+ },
+ "status": {
+ "type": "string"
+ },
+ "statusTruncated": {
+ "type": "boolean"
+ },
+ "truncated": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "status",
+ "statusTruncated",
+ "patch",
+ "truncated"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "errors": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "exitCode": {
+ "anyOf": [
+ {
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "fileChanges": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "kind": {
+ "type": "string"
+ },
+ "path": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "path",
+ "kind"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "liveLog": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "notesPath": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "outputTruncated": {
+ "type": "boolean"
+ },
+ "parseErrors": {
+ "type": "number"
+ },
+ "resumeReasons": {
+ "items": {
+ "enum": [
+ "timeout",
+ "transient-turn-failure",
+ "no-completion-marker"
+ ],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "runId": {
+ "type": "string"
+ },
+ "sawCompletion": {
+ "type": "boolean"
+ },
+ "schemaVersion": {
+ "type": "number"
+ },
+ "sessionId": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "status": {
+ "enum": [
+ "success",
+ "partial",
+ "failed",
+ "aborted"
+ ],
+ "type": "string"
+ },
+ "stderr": {
+ "type": "string"
+ },
+ "timedOut": {
+ "type": "boolean"
+ },
+ "turnCount": {
+ "type": "number"
+ },
+ "unknownEvents": {
+ "type": "number"
+ },
+ "usage": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "cachedInputTokens": {
+ "type": "number"
+ },
+ "inputTokens": {
+ "type": "number"
+ },
+ "outputTokens": {
+ "type": "number"
+ },
+ "reasoningOutputTokens": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "inputTokens",
+ "cachedInputTokens",
+ "outputTokens",
+ "reasoningOutputTokens"
+ ],
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "warnings": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "sessionId",
+ "agentMessage",
+ "fileChanges",
+ "commands",
+ "usage",
+ "errors",
+ "parseErrors",
+ "unknownEvents",
+ "sawCompletion",
+ "warnings",
+ "turnCount",
+ "schemaVersion",
+ "status",
+ "runId",
+ "diff",
+ "attribution",
+ "exitCode",
+ "timedOut",
+ "aborted",
+ "outputTruncated",
+ "stderr",
+ "liveLog",
+ "notesPath"
+ ],
+ "type": "object"
+}v0.8.0codex_batchcodex_continue1 field changedInput schema / properties / writeNotesAdded value: +{
+ "description": "Persist a markdown summary of this run to <cwd>/.codex-flow/notes/<sessionId>.md (default false).",
+ "type": "boolean"
+}codex_execute1 field changedInput schema / properties / writeNotesAdded value: +{
+ "description": "Persist a markdown summary of this run to <cwd>/.codex-flow/notes/<sessionId>.md (default false).",
+ "type": "boolean"
+}codex_metricscodex_review1 field changedInput schema / properties / writeNotesAdded value: +{
+ "description": "Persist a markdown summary of this run to <cwd>/.codex-flow/notes/<sessionId>.md (default false).",
+ "type": "boolean"
+}codex_sessionsv0.2.0codex_continuecodex_executecodex_healthcodex_reviewScored across 7 tools
Each tool has a clearly distinct purpose: discovering sessions, executing new tasks, resuming sessions, reviewing changes, batching work, reading metrics, and checking health. Though execute and batch both run Codex, their scope (single vs. fanned-out) is explicit and easy to distinguish.
All tools share the consistent codex_ prefix and snake_case style, which makes them predictable. However, the suffix mixes verbs (execute, continue) with nouns (sessions, metrics, batch, health), so it is not a strict verb_noun convention.
Seven tools is well-scoped for a Codex-focused server. Each tool covers a meaningful workflow: session discovery, execution, continuation, review, batch processing, metrics, and health checks, with no obvious bloat.
The set covers the core Codex lifecycle: create and run sessions, resume them, review changes, batch tasks, and observe usage/health. Minor gaps exist, such as no explicit tool for full session transcripts or canceling in-progress sessions, but agents can work around these using returned sessionIds and the CLI.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
No-data MCP handoff for local Claude Code to Codex harness moves. $49 lifetime.
Live SEO workflow tools for Claude Code, Codex, and AI agents.
AI code review for GitHub PRs with an MCP autofix loop for Claude Code and Cursor
