Codex Implementation

Codex Implementation

Drive the OpenAI Codex CLI as a code-changing agent from scripts or an agent harness. The contract: explicit scope, explicit acceptance criteria, explicit verification, explicit output format — then verify the diff yourself.

Command surface verified against codex-cli 0.142.5; on flag errors, recheck codex --help and codex exec --help — placement and availability shift between versions.

When to use

• Bulk or mechanical implementation with a clear spec (migrations, refactors, well-defined features)
• Work explicitly routed to gpt-5.6 / Codex by the user or a model-routing policy
• Parallel implementation lanes where Codex handles one branch of work

Not for: tasks needing your own conversation context Codex can't see (write a self-contained prompt instead), or taste-critical UI/copy work unless the routing policy sends it there.

Preflight

codex --version                 # confirm CLI present; stop and report if missing
git status --short              # know the starting state
git switch -c codex/<task-slug> # work on a branch when the change is nontrivial

Canonical invocation

codex \
  -a never \
  exec \
  -m gpt-5.6-sol \
  -c model_reasoning_effort='"high"' \
  -s workspace-write \
  -C "$PWD" \
  --output-last-message /tmp/codex-final.txt \
  "<implementation prompt — see contract below>" \
  </dev/null 2>/tmp/codex-progress.log

Key mechanics:

• Flag placement matters. -a (approval policy) and --search are global flags — they go before exec. codex exec -a never is rejected by 0.142.5. Equivalent post-exec forms: -c approval_policy='"never"', -c web_search='"live"'. -s is accepted both globally and on exec, but subcommands like exec review only get it globally.
• stdin gotcha. codex exec reads stdin and can hang forever if stdin is open-but-empty (zero output, zero CPU). Always append </dev/null unless intentionally piping data.
• stdout vs stderr. Final agent message → stdout. Progress/thinking/tool activity → stderr. Suppress with 2>/dev/null or capture to a log.
• --full-auto is deprecated (hidden in 0.142.5 help). Spell out -s workspace-write plus -a never instead.
• Git check. Codex refuses to run outside a git repo. --skip-git-repo-check only for disposable scratch dirs.

Flag reference

Sandbox modes

Network inside workspace-write: -c sandbox_workspace_write.network_access=true, or preinstall dependencies before the run.

Effort selection and timeout budgets

Codex produces no intermediate stdout — killed early means silently empty output. Run in background with a generous timeout, or wrap: /usr/bin/perl -e 'alarm shift; exec @ARGV' 3600 codex ….

Prompt contract

GPT-5-class Codex models respond to operational specificity. Every implementation prompt states four things:

Implement <task, or "the change described in ./task.md">.

Scope:
- Edit only <paths/globs>. Do not touch <exclusions>.
- Do not change <public APIs / schemas / generated files>.

Acceptance criteria:
- <observable behavior 1>
- <observable behavior 2>

Verification:
- Run <exact test command>.
- If tests cannot run, state the exact blocker.

Final message:
- Bullet list only — changed files, tests run, residual risks.

Bad: Fix the auth bug. — no symptom, scope, tests, or output contract.

For machine-parseable results, add --output-schema and demand "final response must match the schema", then parse the --output-last-message file.

Passing context in

• Point at paths, don't paste files: "Read ./docs/api.md and ./src/server. Implement the described behavior."
• Pipe a snapshot when immutability matters: git diff | codex exec "…" (stdin appended as a <stdin> block).
• Whole prompt from file: codex exec - < task.txt.
• Images: -i mockup.png (repeatable).
• AGENTS.md is auto-discovered: ~/.codex/AGENTS.md (global), then project root down to cwd; AGENTS.override.md wins at each level.

Session resume

codex exec resume --last "fix the race conditions you found" </dev/null
codex exec resume <SESSION_ID> "continue; run the narrowest relevant tests" </dev/null

--last picks the newest session for the cwd (--all for any dir). Conversation context and prior tool observations carry over; shell state and env changes do not — restate critical constraints. Don't add config flags on resume; the session keeps its model/effort/sandbox.

After the run — always verify

1. Check exit code; nonzero → inspect the stderr log before trusting anything.
2. git diff --stat && git diff — read the change, confirm scope was respected.
3. Run the tests yourself; don't take Codex's word for it.
4. Report faithfully: separate what you verified from what Codex claimed.

Troubleshooting