Run a Codex task
codex_runDelegates a coding task to OpenAI Codex by starting a new thread or continuing an existing one, then returns status, latest message, changed files, diff preview, and commands run.
Instructions
Give Codex (OpenAI coding agent) a task. Starts a new thread, or continues an existing one when thread_id is given. Blocks up to wait_seconds, then returns status, Codex's latest message, files changed, diff preview, and commands run. status "inProgress" → codex_wait; "waitingForInput" → answer pending_requests with codex_respond. Run several threads in parallel by calling codex_run with wait_seconds: 0 (prefer worktree: true), then codex_wait with all thread_ids. Verify Codex's diff/changes before reporting them as done.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"prompt": "<prompt>"
},
"name": "codex_run"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Absolute working directory. Required for a new thread. | |
| model | No | Model override (see codex_models). Defaults to Codex config. | |
| effort | No | Reasoning effort override, e.g. low | medium | high | xhigh (see codex_models). | |
| images | No | Optional local image file paths to attach to this turn. | |
| prompt | Yes | Instructions for Codex. Be specific: goal, files, constraints, verification, and what "done" looks like. | |
| sandbox | No | Sandbox for a new (or resumed) thread; fixed after that. Default: workspace-write. | |
| approval | No | When Codex must ask before acting; can change between turns. "never" auto-approves everything. Default: on-request. | |
| worktree | No | New thread only: run in an isolated git worktree + branch (codex/<stamp>) created from cwd's HEAD. Note: uncommitted parent changes are not copied into a new worktree. | |
| thread_id | No | Continue this existing Codex thread (keeps its context). | |
| web_search | No | New thread only: enable live web search for Codex. | |
| wait_seconds | No | Seconds to block before returning a progress snapshot (default 120). Returns early when the turn finishes or Codex needs an answer. The turn keeps running after this returns. | |
| output_schema | No | JSON Schema the final message must follow (structured output). |