Codex
Codex is an independent agent on PATH (codex — invoke as command codex if
a shell alias shadows it), sharing this working tree and already authenticated. It is a second opinion, not ground truth: verify what it
reports, own what it changes. It reads the same skills your repo carries.
Leave Codex's model at its CLI default unless the user asks for a specific
one. The default follows the current Codex release; do not pin a dated model
ID in this skill. If an explicit override is needed, verify it is current and
pass the requested model with -m <model>.
If codex is not installed
When codex is missing from PATH, offer to install it — ask the user for
approval first, never install on your own initiative. On yes, follow the
current instructions at https://developers.openai.com/codex/cli. First-run
authentication is interactive — hand that step to the user. Verify with
codex --version before proceeding.
Prompting Codex
Prompt Codex like an operator, not a collaborator: compact, block-structured
with XML tags. State the task, what "done" looks like, and the few constraints
that matter. A tighter prompt beats a bigger run — improve the contract before
raising reasoning effort.
- One task per run. Split unrelated asks (review, then fix, then docs) into
separate runs; a mixed prompt gets a mixed result.
- Name installed skills instead of restating them. Codex reads the same
skills your repo carries — say "follow write-skills for the skill" or
"follow codebase-design for module boundaries." Don't re-explain what a
skill already carries.
- Blocks, added only where the task needs them:
<task> — the concrete job, the repo/failure context, the expected end
state. Nearly always present.
<output_contract> — exact shape, highest-value first, compact.
<default_follow_through> — take the low-risk interpretation and keep
going; stop only when a missing detail changes correctness, safety, or an
irreversible action.
<verification_loop> — before finalizing, check the result against the
requirements and the changed files; revise rather than ship the first
draft. Any risky fix.
<grounding> — ground every claim in code or tool output; label inferences
as inferences. Review and research.
<action_safety> — keep the diff tightly scoped; no drive-by refactors.
Write tasks.
- Anti-patterns: vague framing ("take a look"), no output contract ("report
back"), "think harder" in place of a contract, mixing jobs in one run, and
demanding certainty the evidence can't support.
Review — integrating agent
When assigned to review code, inspect the diff yourself and return findings. Do
not invoke Codex or delegate another review. The launch procedure below is only
for the integrating agent.
Run one read-only Codex review after implementation and local checks are complete,
immediately before creating a substantive PR. Also run a review when the user
explicitly asks for one. An existing completed review covering the proposed PR
does not need to be repeated automatically.
Do not automatically review ordinary edits, commits, audits, or exploratory work.
Loading this skill for prompting guidance or implementation delegation does not
trigger a review. Fix confirmed findings and run affected local checks without
starting another review pass; fixes, commits, pushes, and PR updates are not
automatic repeat-review triggers. Run another pass only when explicitly requested.
Honor recorded standing user authorization for read-only reviews, including
transmission of task-relevant private or uncommitted code through the existing
authenticated Codex service. Include that authorization in approval justifications;
do not request fresh consent solely because review sends code to Codex. Preserve
native sandbox and approval controls, exclude unrelated secrets, and keep
implementation-delegation authorization separate.
Standing consent permits reviews within the triggers above; it does not require
a review after every substantive change.
Fix the diff scope before launching: --uncommitted for working-tree
changes, --base <branch> for a branch diff, --commit <sha> for a landed
commit. Before PR creation, review the proposed changes against the intended
target branch. Resolve a landed commit to its full SHA. Use the non-interactive
review entry point with an explicit read-only sandbox and separate progress
and verdict files in a fresh temporary directory:
review_dir=$(mktemp -d "${TMPDIR:-/tmp}/codex-review.XXXXXX")
if codex exec --sandbox read-only -C "$(git rev-parse --show-toplevel)" review \
--commit "$(git rev-parse HEAD)" --json -o "$review_dir/verdict.md" \
< /dev/null > "$review_dir/events.jsonl" 2> "$review_dir/stderr.log"; then
printf '0\n' > "$review_dir/exit-code"
else
printf '%s\n' "$?" > "$review_dir/exit-code"
fi
Background the whole block for long runs and retain its process/session handle. Scope flags
and custom instructions are mutually exclusive: a scope flag takes no
prompt. For custom framing, specify the exact diff to inspect in the prompt;
don't rely on default scope or traverse all refs/checkpoint history. Never
state the answer you expect; give the reviewer evidence and a neutral task.
Monitor with scripts/review-status.py: run
python3 "$HOME/.agents/skills/codex/scripts/review-status.py" "$review_dir".
It reports bounded progress, errors and completion receipts; read the full
verdict separately. Inspect retained logs only when diagnosing a specific
failure, rather than tailing raw JSONL with embedded command output. An active
reviewer reading relevant code is not hung merely because five minutes
elapsed. If it stalls or drifts outside the diff and its dependencies,
inspect the last command/error before interrupting; correct the cause or
narrow the task before retrying. Completion requires exit status zero,
turn.completed, and a nonempty final verdict. A timeout, turn.failed, or
missing verdict is incomplete, never a clean review.
Triage every finding: confirm it against the code before acting. Preserve
Codex's evidence boundaries — an inference it labelled is not a fact.
Overlap with your own doubts is high-priority evidence; a finding you
dismiss needs a stated reason, not silence.
Report the outcome to the user — what Codex flagged, what you fixed, what
you dismissed and why. Done when every finding is either fixed or
explicitly dismissed.
Implementation — explicit ask only
Delegate implementation to Codex only when the user names Codex for the task.
Keep delegation within the authorized task. In-scope follow-ups retain that
authorization; ask again only when the proposed delegation expands its scope.
- Slice the task sharp before delegating — goal, constraints, and how to
verify — using the prompt discipline above. An underspecified task stays
with you until a fresh agent couldn't misread it.
- Start from a clean tree (or record the baseline commit) so Codex's diff is
separable from yours.
- Pick the sandbox by what the task must RUN:
- Pure code + typecheck/unit:
codex exec --sandbox workspace-write "<task>".
Network is off; add -c sandbox_workspace_write.network_access=true only
when the task must fetch (e.g. new deps).
- Browser verification, dev servers, or full test runs: use the host’s
approved sandbox and scoped approval mechanism. A worktree separates Git
state but is not a security boundary. If a required operation is denied,
surface the exact capability needed rather than disabling safeguards.
Use
-o <file> to capture the final message and background long calls;
retain stderr in a separate temporary log so failures remain diagnosable,
and add --skip-git-repo-check to run outside a git repo. Verify supported
flags with the installed CLI help when behavior differs.
- Follow up with
codex exec resume <session-id> "<follow-up>", taking the
id from the run header. resume --last means the most recent session
globally — a review or any other codex run in between will hijack it. If
two resume rounds don't converge, stop delegating and finish it yourself —
iterating a confused agent costs more than taking over.
- You own the result: read the full diff, run the tests, and only then report
it. "Codex says it's done" is not done.
Exec liveness — a hang looks like work
A backgrounded codex exec can wedge at startup: process alive at 0% CPU, but
no session file under `/.codex/sessions/<Y/M/D>/`, no network socket, no tree
changes. "Process running" is NOT "working."
- Stdin is always a file or
/dev/null, never an inherited terminal. Left
on an interactive/piped stdin with no prompt source, exec prints Reading additional input from stdin... and blocks forever — the most common hang.
Either pass the prompt as a positional arg with < /dev/null, or feed a
prompt file with codex exec [flags] - < prompt.txt (the - makes codex
read the task from stdin, and a missing file fails the redirect loudly —
unlike "$(cat prompt.txt)", which silently sends the fallback string as
the task). Add nohup/& as needed.
- Watchdog: inspect this run’s event and error logs and its process handle.
Correct a concrete startup failure before retrying. Stop only the process
launched for this task; elapsed time alone does not prove a hang.
- Check worktree trust. Headless execution may require the new worktree
path to be trusted. Use the host’s normal trust flow and preserve existing
configuration; a skill invocation does not authorize changing trust policy.
- Don't launch two execs in the same instant, and kill stale hung execs
before starting a new one.
- Launch from the repo/worktree ROOT. The writable sandbox root is the
CWD at launch: exec'd from a subdirectory (e.g.
web/), every edit outside
it is rejected as "writing outside of the project" and a never approval
policy can't recover — the run burns with zero files changed. Pass
-C <root> to set the working root explicitly instead of cd-ing into it.
Rules
- Don't touch the working tree while a Codex exec is running on it.
- Explicit
--sandbox read-only for reviews, consultation and questions;
workspace-write only for delegated implementation.
- Preserve the host’s sandbox and approval controls. Do not substitute bypass
flags when a command is blocked.
--full-auto is absent from the installed
CLI; use the supported sandbox options instead.
- Reasoning effort and model are config/flag overrides —
-c model_reasoning_effort=high, -m <model> (the old --effort flag is gone
in current Codex). Leave both at their defaults unless the user asks;
tighten the prompt first and keep model IDs unversioned. If a version is
required, verify that it is current before using it.
1---2name: codex3description: Use the local Codex CLI as an independent second agent. As the integrating agent, run `codex review` once immediately before creating a substantive PR, or when the user explicitly asks for a review. When assigned to review code, inspect the diff yourself without invoking Codex or delegating another review. Do not automatically review ordinary edits, commits, audits, or exploratory work. Delegate implementation via `codex exec` only when the user explicitly asks for Codex to do it. Also covers how to prompt Codex.4metadata:5 source: https://skillmd.com/skills/transitive-bullshit/codex6---78# Codex910Codex is an independent agent on PATH (`codex` — invoke as `command codex` if11a shell alias shadows it), sharing this working tree and already authenticated. It is a second opinion, not ground truth: verify what it12reports, own what it changes. It reads the same skills your repo carries.1314Leave Codex's model at its CLI default unless the user asks for a specific15one. The default follows the current Codex release; do not pin a dated model16ID in this skill. If an explicit override is needed, verify it is current and17pass the requested model with `-m <model>`.1819## If `codex` is not installed2021When `codex` is missing from PATH, offer to install it — **ask the user for22approval first**, never install on your own initiative. On yes, follow the23current instructions at https://developers.openai.com/codex/cli. First-run24authentication is interactive — hand that step to the user. Verify with25`codex --version` before proceeding.2627## Prompting Codex2829Prompt Codex like an operator, not a collaborator: compact, block-structured30with XML tags. State the task, what "done" looks like, and the few constraints31that matter. A tighter prompt beats a bigger run — improve the contract before32raising reasoning effort.3334- **One task per run.** Split unrelated asks (review, then fix, then docs) into35 separate runs; a mixed prompt gets a mixed result.36- **Name installed skills instead of restating them.** Codex reads the same37 skills your repo carries — say "follow write-skills for the skill" or38 "follow codebase-design for module boundaries." Don't re-explain what a39 skill already carries.40- **Blocks, added only where the task needs them:**41 - `<task>` — the concrete job, the repo/failure context, the expected end42 state. Nearly always present.43 - `<output_contract>` — exact shape, highest-value first, compact.44 - `<default_follow_through>` — take the low-risk interpretation and keep45 going; stop only when a missing detail changes correctness, safety, or an46 irreversible action.47 - `<verification_loop>` — before finalizing, check the result against the48 requirements and the changed files; revise rather than ship the first49 draft. Any risky fix.50 - `<grounding>` — ground every claim in code or tool output; label inferences51 as inferences. Review and research.52 - `<action_safety>` — keep the diff tightly scoped; no drive-by refactors.53 Write tasks.54- **Anti-patterns:** vague framing ("take a look"), no output contract ("report55 back"), "think harder" in place of a contract, mixing jobs in one run, and56 demanding certainty the evidence can't support.5758## Review — integrating agent5960When assigned to review code, inspect the diff yourself and return findings. Do61not invoke Codex or delegate another review. The launch procedure below is only62for the integrating agent.6364Run one read-only Codex review after implementation and local checks are complete,65immediately before creating a substantive PR. Also run a review when the user66explicitly asks for one. An existing completed review covering the proposed PR67does not need to be repeated automatically.6869Do not automatically review ordinary edits, commits, audits, or exploratory work.70Loading this skill for prompting guidance or implementation delegation does not71trigger a review. Fix confirmed findings and run affected local checks without72starting another review pass; fixes, commits, pushes, and PR updates are not73automatic repeat-review triggers. Run another pass only when explicitly requested.7475Honor recorded standing user authorization for read-only reviews, including76transmission of task-relevant private or uncommitted code through the existing77authenticated Codex service. Include that authorization in approval justifications;78do not request fresh consent solely because review sends code to Codex. Preserve79native sandbox and approval controls, exclude unrelated secrets, and keep80implementation-delegation authorization separate.81Standing consent permits reviews within the triggers above; it does not require82a review after every substantive change.83841. Fix the diff scope before launching: `--uncommitted` for working-tree85 changes, `--base <branch>` for a branch diff, `--commit <sha>` for a landed86 commit. Before PR creation, review the proposed changes against the intended87 target branch. Resolve a landed commit to its full SHA. Use the non-interactive88 review entry point with an explicit read-only sandbox and separate progress89 and verdict files in a fresh temporary directory:9091 ```sh92 review_dir=$(mktemp -d "${TMPDIR:-/tmp}/codex-review.XXXXXX")93 if codex exec --sandbox read-only -C "$(git rev-parse --show-toplevel)" review \94 --commit "$(git rev-parse HEAD)" --json -o "$review_dir/verdict.md" \95 < /dev/null > "$review_dir/events.jsonl" 2> "$review_dir/stderr.log"; then96 printf '0\n' > "$review_dir/exit-code"97 else98 printf '%s\n' "$?" > "$review_dir/exit-code"99 fi100 ```101102 Background the whole block for long runs and retain its process/session handle. Scope flags103 and custom instructions are mutually exclusive: a scope flag takes no104 prompt. For custom framing, specify the exact diff to inspect in the prompt;105 don't rely on default scope or traverse all refs/checkpoint history. Never106 state the answer you expect; give the reviewer evidence and a neutral task.1072. Monitor with [scripts/review-status.py](scripts/review-status.py): run108 `python3 "$HOME/.agents/skills/codex/scripts/review-status.py" "$review_dir"`.109 It reports bounded progress, errors and completion receipts; read the full110 verdict separately. Inspect retained logs only when diagnosing a specific111 failure, rather than tailing raw JSONL with embedded command output. An active112 reviewer reading relevant code is not hung merely because five minutes113 elapsed. If it stalls or drifts outside the diff and its dependencies,114 inspect the last command/error before interrupting; correct the cause or115 narrow the task before retrying. Completion requires exit status zero,116 `turn.completed`, and a nonempty final verdict. A timeout, `turn.failed`, or117 missing verdict is incomplete, never a clean review.1183. Triage every finding: confirm it against the code before acting. Preserve119 Codex's evidence boundaries — an inference it labelled is not a fact.120 Overlap with your own doubts is high-priority evidence; a finding you121 dismiss needs a stated reason, not silence.1224. Report the outcome to the user — what Codex flagged, what you fixed, what123 you dismissed and why. Done when every finding is either fixed or124 explicitly dismissed.125126## Implementation — explicit ask only127128Delegate implementation to Codex only when the user names Codex for the task.129Keep delegation within the authorized task. In-scope follow-ups retain that130authorization; ask again only when the proposed delegation expands its scope.1311321. Slice the task sharp before delegating — goal, constraints, and how to133 verify — using the prompt discipline above. An underspecified task stays134 with you until a fresh agent couldn't misread it.1352. Start from a clean tree (or record the baseline commit) so Codex's diff is136 separable from yours.1373. Pick the sandbox by what the task must RUN:138 - Pure code + typecheck/unit: `codex exec --sandbox workspace-write "<task>"`.139 Network is off; add `-c sandbox_workspace_write.network_access=true` only140 when the task must fetch (e.g. new deps).141 - Browser verification, dev servers, or full test runs: use the host’s142 approved sandbox and scoped approval mechanism. A worktree separates Git143 state but is not a security boundary. If a required operation is denied,144 surface the exact capability needed rather than disabling safeguards.145 Use `-o <file>` to capture the final message and background long calls;146 retain stderr in a separate temporary log so failures remain diagnosable,147 and add `--skip-git-repo-check` to run outside a git repo. Verify supported148 flags with the installed CLI help when behavior differs.1494. Follow up with `codex exec resume <session-id> "<follow-up>"`, taking the150 id from the run header. `resume --last` means the most recent session151 globally — a review or any other codex run in between will hijack it. If152 two resume rounds don't converge, stop delegating and finish it yourself —153 iterating a confused agent costs more than taking over.1545. You own the result: read the full diff, run the tests, and only then report155 it. "Codex says it's done" is not done.156157## Exec liveness — a hang looks like work158159A backgrounded `codex exec` can wedge at startup: process alive at ~0% CPU, but160no session file under `~/.codex/sessions/<Y/M/D>/`, no network socket, no tree161changes. "Process running" is NOT "working."162163- **Stdin is always a file or `/dev/null`, never an inherited terminal.** Left164 on an interactive/piped stdin with no prompt source, exec prints `Reading165 additional input from stdin...` and blocks forever — the most common hang.166 Either pass the prompt as a positional arg with `< /dev/null`, or feed a167 prompt file with `codex exec [flags] - < prompt.txt` (the `-` makes codex168 read the task from stdin, and a missing file fails the redirect loudly —169 unlike `"$(cat prompt.txt)"`, which silently sends the fallback string as170 the task). Add `nohup`/`&` as needed.171- **Watchdog:** inspect this run’s event and error logs and its process handle.172 Correct a concrete startup failure before retrying. Stop only the process173 launched for this task; elapsed time alone does not prove a hang.174- **Check worktree trust.** Headless execution may require the new worktree175 path to be trusted. Use the host’s normal trust flow and preserve existing176 configuration; a skill invocation does not authorize changing trust policy.177- **Don't launch two execs in the same instant,** and kill stale hung execs178 before starting a new one.179- **Launch from the repo/worktree ROOT.** The writable sandbox root is the180 CWD at launch: exec'd from a subdirectory (e.g. `web/`), every edit outside181 it is rejected as "writing outside of the project" and a `never` approval182 policy can't recover — the run burns with zero files changed. Pass183 `-C <root>` to set the working root explicitly instead of `cd`-ing into it.184185## Rules186187- Don't touch the working tree while a Codex exec is running on it.188- Explicit `--sandbox read-only` for reviews, consultation and questions;189 `workspace-write` only for delegated implementation.190- Preserve the host’s sandbox and approval controls. Do not substitute bypass191 flags when a command is blocked. `--full-auto` is absent from the installed192 CLI; use the supported sandbox options instead.193- Reasoning effort and model are config/flag overrides — `-c194 model_reasoning_effort=high`, `-m <model>` (the old `--effort` flag is gone195 in current Codex). Leave both at their defaults unless the user asks;196 tighten the prompt first and keep model IDs unversioned. If a version is197 required, verify that it is current before using it.