Start a Codex job
codex_startSubmit a self-contained coding task for background execution while you continue working. Use for slow refactors, migrations, bulk edits, and output-heavy work like generating tests or boilerplate.
Instructions
Hand a coding task to the Codex CLI and get a jobId back immediately — Codex runs in the background while you keep working. Two reasons to reach for it. One: the task is self-contained and slow (refactors, migrations, test writing, bulk edits across files), so running it in the background buys concurrency. Two: the task is self-contained and output-heavy (generating a lot of code, tests, or boilerplate), so letting Codex produce those tokens conserves your own usage — this reason holds even when the task is fast, because you and Codex bill separately. Codex edits files on disk directly in cwd, so treat the working tree as modified once the job finishes. Keep working while it runs; check codex_status when you need to and collect the answer with codex_result — don't re-check in a tight loop, since each check is a model turn. Still the wrong tool for a quick question you need answered right now, and for trivial triage or classification (relevance filtering, labelling, risky-or-not) send those to a local model instead — this returns a job id, not an answer, so anything cheaper to resolve another way should be. Model and reasoning effort are chosen automatically from the task text unless you set them; the choice and its reasoning come back in the response, and setting either one explicitly overrides it. Call codex_models to see what is available.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Absolute path to the directory Codex should treat as its working root. | |
| model | No | Pin the model instead of letting it be chosen from the task. Available: (model index unavailable; Codex config defaults apply). Omit to let routing pick one. | |
| prompt | Yes | The task for Codex. Be specific and self-contained: Codex cannot see this conversation, so restate the relevant context, constraints, and what 'done' looks like. | |
| addDirs | No | Extra absolute directories Codex may write to, beyond cwd. | |
| sandbox | No | read-only = cannot modify anything; workspace-write (default) = may edit files under cwd; danger-full-access = unrestricted, avoid unless the caller explicitly asked for it. | |
| autoRoute | No | Default true. Set false to suppress automatic selection entirely and use only what you pass (or the Codex config defaults) — useful when the keyword heuristic misreads a task and you want no inference at all. | |
| structured | No | Default true: Codex must return a typed handoff report (summary, status, filesChanged, verification, followUps, blockers, confidence). Set false only when you want a long prose explanation and the structure would get in the way. | |
| documentation | No | Default true for jobs that can write: Codex is asked to update the project's existing documentation when the change alters behaviour, adds a feature, or makes an existing statement untrue, and to report what it touched. It is told to edit existing docs rather than invent a changelog, and to skip when the change does not warrant any. Set false to suppress the instruction. Always off under read-only, which cannot write. | |
| reasoningEffort | No | How hard the model should think, overriding your Codex config for this job only. Match it to the task: 'low' for mechanical work where the answer is obvious and the cost is typing (renames, moving files, applying a stated pattern); 'medium' for ordinary implementation; 'high' or 'xhigh' for genuinely hard reasoning — tricky concurrency, subtle logic, design decisions with real trade-offs. Higher settings cost more and take longer, so raising it for simple work buys nothing. Note that accepted values vary by model: 'none', 'low', 'medium', 'high' and 'xhigh' are widely supported, while 'minimal' and 'max' are rejected by some models and will fail the job on its first API call. Omit to inherit the config default. |