| name | codex |
| description | Drive OpenAI Codex from Claude Code — raw wrapper mechanics for prompts, structured JSON, image generation, and session resume. Use when the user wants to "ask Codex" or delegate a task that codex-review, codex-implementation, and codex-computer-use don't cover; those skills point here for command mechanics. |
Driving Codex from Claude Code
Codex CLI is installed locally (codex.exe on PATH, verified v0.142.x) and logged in
via ChatGPT. codex exec is the single interface for everything — in
non-interactive exec mode Codex still exposes its full toolset:
functions.shell_command, functions.apply_patch (write code), image_gen.imagegen
(image generation), browser:control-in-app-browser (browser use),
computer-use:computer-use (screen control), web.run (web search), and
functions.view_image. You do not need separate entry points for image gen or
computer use — you just ask for them in the prompt.
Prefer the wrapper scripts/codex-run.mjs; it runs codex exec --json, parses the
event stream, and prints a clean result (final message + files changed + thread id
for resuming). Fall back to raw codex exec only when you need something the wrapper
doesn't expose.
Quick start
node "<SKILL_DIR>/scripts/codex-run.mjs" "Explain what this repo's build.rs does"
node "<SKILL_DIR>/scripts/codex-run.mjs" --write --cd /path/to/repo \
"Add input validation to parseConfig() and a unit test for it."
node "<SKILL_DIR>/scripts/codex-run.mjs" --schema ./out.schema.json "..."
node "<SKILL_DIR>/scripts/codex-run.mjs" --write \
"Generate a 512x512 logo of a fox and save it to ./logo.png"
node "<SKILL_DIR>/scripts/codex-run.mjs" --resume-last "Now also handle the null case."
<SKILL_DIR> is this skill's directory. From Claude Code it is the folder holding
this file; when unsure, use the absolute path
C:\Users\shawn\.claude\skills\codex\scripts\codex-run.mjs.
Wrapper options
| Flag | Meaning |
|---|
--write | Sandbox workspace-write — Codex may edit files in the working dir. |
--read | Sandbox read-only (default) — Codex can read/run but not write. |
--full | danger-full-access — network + full disk. Use sparingly. |
--yolo | Bypass approvals and sandbox. Only inside an already-isolated env. |
--cd <dir> | Working root for Codex (defaults to cwd). |
--model <name> | e.g. gpt-5.3-codex, gpt-5.3-codex-spark (fast). |
--effort <lvl> | none|minimal|low|medium|high|xhigh reasoning effort. |
--schema <file> | JSON-Schema file; forces the final message to match it. |
--image <file> | Attach an image to the prompt (repeatable). |
--resume-last / --resume <id> | Continue a prior session (thread id is printed after each run). |
--raw | Emit the raw JSONL event stream instead of a summary. |
--timeout <sec> | Kill Codex after N seconds (default 900). |
The wrapper prints the thread id after every run; pass it to --resume (or use
--resume-last) to continue that conversation with only the delta instruction.
Capabilities and how to ask for them
- Write / edit code — use
--write. Codex plans, edits via apply_patch, and
can run tests in its sandbox. The wrapper reports which files changed.
- Structured output — pass
--schema file.json; the final agent message is the
JSON object (validated by Codex, retried on mismatch).
- Image generation — ask in the prompt and give a save path; needs
--write to
copy the file out. Images also land in ~/.codex/generated_images/<thread>/.
- Browser use — ask Codex to "use your browser tool to open and …".
Drives an in-app browser (CDP). Works headless for navigation/scraping.
- Computer use — ask Codex to "use computer-use to …". This controls the actual
screen/mouse/keyboard, so run it only when the user explicitly wants desktop
automation and is watching. Confirm before starting.
- Web search —
web.run is available; just ask Codex to look something up.
- Code review —
codex exec review (or codex review) runs a review of local
git changes with a built-in contract; use it instead of a hand-written prompt when
the job is reviewing a diff.
Prompting Codex well (OpenAI's guidance)
Prompt Codex like an operator, not a collaborator: compact, block-structured with XML
tags. One clear task per run.
- State the task and what "done" looks like — don't assume Codex infers the end state.
- Give an explicit output contract (exact shape/ordering/brevity).
- Set follow-through defaults so Codex keeps going instead of asking routine questions.
- For write/debug tasks add a verification step ("run the tests, report results") and
a safety constraint ("stay narrow, no unrelated refactors").
- Tighten the prompt before raising
--effort.
Skeleton:
<task>concrete job + relevant context</task>
<output_contract>exact shape / brevity</output_contract>
<follow_through>what to do by default vs. stop for missing high-risk detail</follow_through>
<verification>how to confirm success (tests, build)</verification>
Safety and reporting
- Default is read-only. Only add
--write when the user wants edits; only
--full/--yolo when explicitly justified and isolated.
- After a review or diagnosis, present findings and stop — do not auto-apply fixes;
ask the user which to apply.
- Report faithfully: if Codex edited files, say which; if a run failed or timed out,
surface the actionable stderr and stop rather than substituting your own answer.
- Preserve Codex's own distinctions (facts vs. inferences vs. open questions) when
relaying its output.
Advanced: app-server / MCP
codex exec covers almost all delegation. For long-lived interactive threads,
streaming turn events, or embedding Codex in another app, Codex also offers:
codex mcp-server — run Codex as an MCP server (stdio) so another MCP client can
call it as a tool.codex app-server — experimental JSON-RPC app server (the protocol the desktop
app / IDE extensions and OpenAI's own codex-plugin-cc use for streaming,
multi-thread, and computer-use interactivity). Generate its schema with
codex app-server generate-json-schema / generate-ts. Reach for this only when
exec's request/response model is genuinely insufficient.
See references/notes.md for the raw JSON event schema and command details.
