Field guide / 12 min
Run repeatable headless work with codex exec
Move proven repository procedures into scripts without pretending autonomy is a control boundary.
codex exec is the non-interactive entry point for scripts and CI. It accepts a prompt as an argument or stdin, uses the same repository guidance and sandbox model as interactive Codex, returns a meaningful process status, and can resume saved exec sessions. Reliability comes from a bounded working directory, explicit permissions, isolated credentials, and verification that does not depend on a conversational transcript.
Verified terminal sequence
- $
codex exec "Run the affected tests and report evidence" - $
codex exec --ephemeral "Inspect the repository and make no changes" - $
codex exec resume --last "Continue with the failed checks"
Working principles
Automate a known procedure
Headless mode removes the live operator, so first prove the prompt, repository context, and acceptance checks in a supervised run.
Exit status is part of the contract
Treat a non-zero status, timeout, malformed output, or missing artifact as failure even when prose sounds optimistic.
Persistence is a choice
Use --ephemeral when a run should leave no session files. Resume only when continued history is intentional and the checkout still matches.
Field procedure
- 01
Pin the working root
Run in one checkout or use -C. Never let a job discover several unrelated repositories from a broad parent directory.
- 02
State the acceptance evidence
Name the files allowed to change, commands to run, and exact artifacts or test results the job must return.
- 03
Bound execution
Choose an appropriate sandbox, approval posture, timeout, and credential scope. Repository code must not inherit broad provider or deployment tokens.
- 04
Handle the process result
Capture stdout and stderr separately, enforce a time budget, retain useful diagnostics, and fail the pipeline on a non-zero status.
- 05
Retry deliberately
Retry only transient failures. Use a new ephemeral run or an explicitly selected session rather than guessing which history should continue.
PASS / FAIL
Acceptance checklist
- The job runs in one verified checkout.
- Permissions and credentials are least-privilege.
- Timeout and non-zero status fail closed.
- Produced changes still pass repository tests.
- Retries cannot duplicate an external side effect.
WATCH / REJECT
Failure patterns
- Using --yolo on an ordinary CI runner.
- Giving write credentials to code from an untrusted pull request.
- Parsing conversational text when a structured contract is required.