use-codex

name

use-codex

description

This skill should be used when considering delegating a coding task to the OpenAI Codex CLI — codebase exploration/Q&A, well-specified implementation, mechanical edits at scale, second-opinion or adversarial review, or bugs stuck after 2+ attempts. Codex spends ChatGPT quota instead of Claude tokens and its models are token-economical. Invoked for "use codex", "ask codex", "delegate to codex", "codex exec", "second opinion", or when offloading token-heavy scoped work.

Use Codex

If you are Codex, you do not need this skill — stop reading and proceed however you otherwise would. Delegating to yourself gains nothing; this skill exists for other agents delegating scoped work to the Codex CLI (codex exec, non-interactive). It runs on a separate token budget (ChatGPT plan / OpenAI API) with token-economical models, and provides an independent second perspective.

Should this go to Codex?

Delegate when the task is scoped and the answer/diff is all that matters:

• Repo exploration & Q&A ("where is X handled?", "trace this flow")
• Implementation where the architecture is already decided and unknowns reduced
• Mechanical edits at scale (renames, migration sweeps)
• Second-opinion / adversarial review of a plan or diff
• A bug stuck after 2+ failed attempts (different model, different angle)

Keep in Claude: ambiguous/underspecified work, architecture & decomposition, long multi-turn efforts needing session memory, user-facing synthesis. Don't delegate one-liners answerable from context already in hand (each Codex call has ~30k tokens of fixed overhead on its side).

Full rationale, evidence, and cost/limits: references/task-fit.md. If the decision is "don't delegate", stop here — no need to read further.

Quick start

codex exec -m gpt-5.5 -c model_reasoning_effort="medium" \
  --sandbox read-only -C /path/to/repo \
  -o /tmp/codex-out.txt \
  "<self-contained prompt with all context Codex needs>" </dev/null 2>/dev/null

Then read /tmp/codex-out.txt — it contains only the final message; all intermediate activity is discarded so tokens aren't double-spent. Scale the Bash timeout to effort (medium ≈ 300s, high ≈ 600s) or run in background; Codex prints nothing until done.

• Model: gpt-5.5 (default; there is no gpt-5.5-codex). gpt-5.4-mini for quick subtasks.
• Sandbox: read-only for questions/review; workspace-write when Codex should edit files (then review the diff before trusting it).
• If -C targets a directory that is not itself a git repo (e.g. a parent dir spanning several repos), add --skip-git-repo-check — without it the run fails, and silently so under 2>/dev/null (exit 1, no output file).
• To capture a session ID for follow-ups: add --json, take thread_id from the first stdout line; resume with codex exec resume <thread-id> "follow-up".

Full flag reference, session-ID capture/resume details, structured output, and gotchas (stdin, resume flag differences, failure modes): references/invocation.md.

After it returns

Treat the output as a peer's work, not an authority's: verify claims against the code, run tests on any diff, and report to the user which parts came from Codex.