codex-cli

Files (1)

• SKILL.md

SKILL.md (first lines)

# Codex CLI

Codex is a second agent on the same machine, with its own model behind it.
That is the entire reason to reach for it: a model that did not write the code
has no memory of intending it to work. Everything below follows from that one
asymmetry — who wrote it, who reads it, and how much thinking each step is
worth paying for.

This skill is for the supervising agent, not for Codex. If you *are* Codex,
this does not apply — calling yourself buys nothing but a second opinion from
the same mind. Claude Code is the intended caller.

It also assumes the machine is already set up: `codex` on `PATH`, the user
logged in, and whatever MCP servers and tools they want available configured
in `~/.codex/config.toml`. If the binary is missing, auth has expired, or a
run dies on permissions, report that plainly and stop — quietly falling back
to doing it yourself hides the fact that the review the user asked for never
happened.

Concrete flags belong to `codex --help`, which is authoritative and moves
faster than this file. What follows is the judgment.

## When to reach for it

Every invocation is a second model spending the user's money and your
wall-clock time. It earns that when the problem is hard enough that another
model changes the outcome — not as a reflex after every edit. Doing the work
yourself and checking it with the project's own tests remains the normal path.

- **When the user asks for it.** They have already made the call; don't
  re-litigate it. Match the model and effort to the task and go.
- **After writing something complex or expensive to get wrong.** Your own
  review of your own diff is the weakest review available, because you are
  checking the code against the intent you already have in your head rather
  than against what it says. That weakness only matters when the defect would
  be costly — concurrency, migrations, security-adjacent paths, platform
  assumptions, anything on a compatibility surface. A routine edit that the
  suite already covers is not worth a review pass. *Counter-example: an agent
  changed one side of a path comparison to a normalized form and left the
  other side platform-native; every test it wrote passed, because it wrote
  them against the same wrong mental model.*
- **When a demanding change is bounded well enough to describe in a prompt.**
  A hand-off is worth it when you can state the goal, the files, and the
  acceptance check in a paragraph. That paragraph is also the honest test of
  whether *you* understand the change — if you cannot write it, delegating it
  just moves the confusion downstream. What "bounded" means is
  [`scoped-change`](https://github.com/scarletkc/agents/blob/main/skills/scoped-change/SKILL.md),
  and it binds Codex exactly as it binds you: pass the boundary along in the
  prompt, because Codex cannot infer where the user drew it.
- **When the work is long, mechanical, and verifiable.** Wide renames,
  repetitive migrations, and mass edits with a green suite proving them buy
  throughput rather than insight, and they are cheap to check.
- **When you are stuck.** After two failed attempts on the same defect, a
  third attempt from the same context tends to repeat the second. A fresh
  agent with the symptom and the reproduction, and none of your accumulated
  theory, is a better use of the next few minutes.

## When to keep it

- **Ordinary work you can verify yourself.** Most changes are this. Writing
  the prompt, waiting for the run, and reading the diff costs more than the
  edit, and a delegated pass over a small change mostly returns items you
  already knew. Absent a reason above, just do it.
- **Judgment about words.** User-facing copy, documentation, naming, and
  release notes need the taste and the context of the session that has been
  talking to the user, and they survive delegation badly. See
  [`ux-writing`](https://github.com/scarletkc/agents/blob/main/skills/ux-writing/SKILL.md).
- **Anything you cannot check afterwards.** Delegating work you have no way
  to verify converts an unknown into a confident-sounding report, which is
  worse than the unknown. Establish the check first.
- **Decisions the user reserved.** Choosing the approach, committing,
  pushing, opening or merging a PR — those stay where the user put them. A
  permissive sandbox makes it *possible* for a delegated run to do all of
  them, which is a reason to scope the prompt tightly, not a licence to let
  it decide.

## Choosing the model

Pick from the task's difficulty, not from habit. Reaching for the strongest
model every time wastes the user's money on renames; reaching for the cheapest
on a subtle bug wastes the user's afternoon.

- **`gpt-5.6-sol`** — the frontier model. Worth it for reviews that must not
  miss anything, root-cause hunts, concurrency and lock-ordering questions,
  cross-platform semantics, and any change whose failure mode is silent.
- **`gpt-5.6-terra`** — balanced, and the sane default for ordinary feature
  work inside a boundary you have already defined.
- **`gpt-5.6-luna`** — fast and cheap with a lower ceiling. Right when a test
  suite or a compiler, not the model, is what actually decides whether the
  result is correct.

## Choosing the effort

Reasoning effort buys deliberation, not knowledge, and it multiplies both
latency and cost. Scale it with how subtle the failure would be:

- **`medium`** — mechanical work with an immediate, objective check.
- **`high`** — real implementation work and routine reviews. The usual pick.
- **`xhigh`** — subtle bugs, unfamiliar subsystems, anything one attempt has
  already failed at.
- **`max`** — the hardest problems, when a wrong answer costs far more than
  the extra minutes. Deliberate, not habitual.

The pairing that matters most: **review the code at least as high as you wrote
it.** A cheap review of an expensive change finds the typos and misses the
reason you delegated it.

## Running it

Drive the non-interactive surface — `codex exec` for work, `codex exec review`
for review. Model and effort are per invocation: `-m <model>` and
`-c model_reasoning_effort=<level>`, both overriding the user's `config.toml`
defaults for that run only. Prefer `codex exec review` over the top-level
`codex review`, which is equally non-interactive but takes the model through
`-c model="..."` rather than `-m`. Review scope is `--base <branch>` for
a branch, `--uncommitted` for the working tree, `--commit <sha>` for one
commit. Everything else — `--json`, output files, resuming a session — is in
`codex --help`.

From scarletkc/agents, Apache-2.0.

More from scarletkc/agents