codex

# Codex Delegation `codex` is an installed CLI agent backed by GPT-6 astra. Its value is independence: it did not write what it reviews. It is optional — an additional reviewer beside the Opus reviewers of the pr skill, a second opinion on a plan, a debugger, an implementer of a well-scoped task. Use it only when it is logged in (`codex login status`) and has quota; when either fails, carry on without it and without comment. The one exception is the triage skill, which stops instead: its classification never leaves codex's sandbox. ## Invocation ```bash codex exec -m gpt-6-astra -c model_reasoning_effort=xhigh \ --dangerously-bypass-approvals-and-sandbox \ -o /tmp/codex-<topic>.md \ "<prompt>" < /dev/null ``` - Always pass `-o` — it writes the final reply to a file; stdout mixes it into the transcript and truncates easily. `-o` holds only the last assistant message: never point it at a file the prompt asks codex to write its report to (or one it might guess) — the message overwrites the report. When the prompt names a report file, give `-o` a clearly different name (`*-final-message.md`). - The full bypass is deliberate: the sandbox breaks builds and tooling. Codex therefore runs with your permissions — scope the prompt accordingly. - xhigh runs take minutes to tens of minutes: run in the background and keep working, no sleep polling. A background `codex exec` must get `< /dev/null`: with a non-TTY stdin it reads the pipe for extra input and blocks forever (the prompt argument does not help). The same applies to Node — spawn it with `stdio: ["ignore", ...]`. Right after launch, `head` the log and confirm the `session id` header appeared; a live process alone proves nothing. - The startup header prints `session id: <uuid>` — capture it whenever a follow-up round is plausible. - If `gpt-6-astra` is rejected (plan/auth), drop `-m` to use the account default, and say so when reporting results. - `-c service_tier=fast` switches the run to the fast service tier; use it when the maintainer asks for speed (long migrations, translation passes). - Prompt shape: the task, the exact files/commands in scope, and the answer format you want (e.g. "numbered findings, each with a minimal counterexample"). Codex reads files itself — point at paths instead of pasting content. - Codex does not auto-load `.claude/` docs — it discovers only `AGENTS.md`, which this repo does not have. Any run that should follow project rules (review, test writing, implementation) must be told in the prompt which rule files to read first, e.g. `.claude/CLAUDE.md` and the cpp-style skill. The review command for the pr skill's self-review loads the repo rules and carries the same fixed constraints as the Opus reviewers: ```bash codex exec -m gpt-6-astra -c model_reasoning_effort=xhigh \ --dangerously-bypass-approvals-and-sandbox -o /tmp/codex-review-<topic>.md \ "Read .claude/CLAUDE.md, .claude/skills/cpp-style/SKILL.md and, when test code changed, .claude/skills/write-tests/SKILL.md, and apply their rules. Review the changes in 'git diff origin/main...HEAD' for correctness, rule violations and test coverage. Report only defects that lead to a concrete failure scenario — the input or state, and the wrong result it produces — each with file:line. Nothing outside this diff's scope. No refactoring, restructuring or style-preference suggestions. No findings is a valid answer." < /dev/null ``` `codex exec review --base origin/main` cannot take a prompt (`--base` and the prompt argument are mutually exclusive), so it never sees the repo rules — not for self-review. ## Multi-round sessions `codex exec resume <session-id> "<follow-up>"` continues with full context (`--last` picks the newest session). Use it for successive adversarial rounds, "now fix what you found", or clarifying questions — never restate context in a fresh session. Execution-scoped flags are NOT inherited from the resumed session: repeat `-m gpt-6-astra`, `-c model_reasoning_effort=xhigh`, `--dangerously-bypass-approvals-and-sandbox`, and a fresh `-o` path on every resume, or the follow-up silently runs on the default model at default effort, sandboxed, and without an output file. `codex exec fork <session-id>` branches one history into independent continuations. ## Wording Prompts and everything codex reads go through OpenAI's cybersecurity filter, which judges phrasing, not intent, and kills the session mid-run (the content stays in that session's history, so `resume` trips it again — only a fresh session recovers). Rules: - Use QA vocabulary: "review", "latent correctness defects", "regression check". Never "attack surface", "hunt/dig for bugs", "fabricate the conditions for the bug"; a negative control is "a control variant expected to fail". Open with the fact that this is routine quality work on our own open-source project (the repo's git config and LICENSE back it up). - Do not feed codex internal notes written in hunting slang — extract the scope into a neutral file and keep the ledger edits on this side. Ask for terse, report-only output: long analytical prose triggers the filter too. - Successive rounds `resume` the same session (or list the prior findings as exclusions), or the round re-reports what is already known. ## Discipline - **Codex output is hypothesis, not verdict.** Every concrete claim ("this input breaks it") gets an empirical probe before you act on it; "looks fine" carries no weight. Codex has correctly refuted arguments this side was sure of, and confidently asserted things a probe then disproved. The probe decides, never authority. - **Adversarial loop** (plans/designs): write the doc → codex attacks it (demand concrete counterexamples, not general commentary) → probe each counterexample → revise the doc, recording adopted and refuted findings → `resume` the session for the next round. Stop when a round yields no new confirmed finding. - **When codex edits code** (implementation, debug fixes, new tests): review its diff as you would a PR — you own what gets committed. Verification (build + suites) happens in the main session, and the hard rules apply unchanged to codex-authored code. Any run that may modify files gets its own git worktree — the main checkout is for analysis-only runs, or edits will race with this session's. - **Codex builds and runs suites on a box, never on this machine** — its prompt has it read `.claude/skills/build/SKILL.md` and `.claude/skills/test/SKILL.md` first. Never let it run the cases on a box this session might also run them on: two full runs at once slow both. Either codex runs them and you don't, or codex analyzes and you verify. - **Keep codex's raw output out of the main context.** Progress checks on a background run (log tail, new commits, report landed?) go through an Opus subagent that returns a digest; a codex-authored diff gets the pr skill's Opus reviewers. The main session spot-checks and decides. ## Recipes - **Plan review**: point it at the doc path; ask for attacks ranked by severity, each with a minimal counterexample. Fold confirmed findings back into the doc. - **Code review**: the review command above, beside the pr skill's Opus reviewers. - **Debug**: give the failing test, the repro command, and the suspect area; ask for a root-cause hypothesis plus the experiment that would confirm it. Let it run the repro itself. - **Test writing**: point it at the write-tests skill, `tests/README.md` and 2-3 neighboring cases as the template; ask it to add cases probing a specific behavior and report which outputs look wrong versus expected. Suspicious snapshot diffs are findings — never `UPDATE_SNAPSHOTS` over them. - **Implementation**: a well-scoped task with acceptance criteria and pointers to the 2-3 existing features whose structure it should copy. Then review and verify as above. ## Recovery To stop a hung run, kill the PID you recorded at launch (`$!` for a shell background job, the task's PID otherwise) and its subtree — other codex runs may be live in parallel. When the PID is lost, `pgrep -af 'codex exe[c]'` lists the candidates to pick from; never `pkill -f 'codex exec'`, which matches your own shell's command line and kills it. If a run dies before writing `-o`, the transcript is at `~/.codex/sessions/YYYY/MM/DD/*.jsonl`; the final reply is the last record with payload `type == "message"` and `role == "assistant"`. These transcripts persist indefinitely and record full prompts, file contents, and command output — treat `~/.codex/sessions/` as sensitive local data.