Headless Runs with codex exec

Everything in this automation module rests on a single distinction. Plain codex opens an interactive REPL/TUI — a conversation you steer turn by turn, approving actions as they come. codex exec (alias codex e) does the opposite: it runs one task non-interactively and exits. No prompt, no human in the loop, no waiting for input. You hand it an instruction, it works, it prints a result, and the process returns.

That single property — runs to completion and exits — is why codex exec is the foundation of all Codex automation. A CI job, a cron entry, a Git hook, a shell pipeline: none of these can sit at an interactive prompt waiting for a human to type "yes." They need a command that behaves like every other Unix tool — takes input, does work, produces output, sets an exit code. codex exec is that command.

# Interactive: opens a REPL you drive by hand
codex

# Headless: runs one task and exits — the automation entry point
codex exec "explain what the auth middleware does"
codex e "explain what the auth middleware does"   # same thing, shorter alias

Keep the larger Codex picture in mind here. "Codex" today is the 2025-era agent — an open-source CLI written in Rust, plus IDE, cloud, and SDK surfaces that all share one ChatGPT account. It is not the 2021 Codex language model (the GPT-3 variant behind early Copilot, deprecated in 2023). When this lesson says codex exec, it means the modern agent running headlessly — the same engine as the interactive CLI, just without the human at the keyboard.

The detail that makes codex exec genuinely pipe-friendly is how it splits its output across the two standard streams:

• While it runs, Codex streams progress to stderr — the reasoning, the commands it executes, the files it touches. This is the live narration you'd watch in a terminal.
• When it finishes, it prints only the final agent message to stdout (or a newline-delimited JSON event stream when you pass --json).

That clean separation is the whole game. Because the answer lands on stdout and the noise lands on stderr, you can capture exactly the result with ordinary shell command substitution — no log-scraping, no regex, no parsing the chatter:

# RESULT holds ONLY the final message; progress still shows on your terminal via stderr
RESULT="$(codex exec 'in one sentence, what does src/auth.ts export?')"
echo "$RESULT"

This is the same Unix discipline behind tools like curl or grep: data on stdout, diagnostics on stderr. It means you can pipe the answer into the next stage of a pipeline, assign it to a variable, or redirect it to a file, while a human (or a CI log) still sees the progress narration separately.

# Send the answer into a file; keep watching progress on the terminal
codex exec 'summarize the changes in this branch' > summary.txt

# Or silence the progress entirely and keep only the result
codex exec 'list the public functions in src/' 2>/dev/null

A practical note on failure: codex exec exits non-interactively, so treat a non-zero exit code as failure (a failed turn surfaces as an error). A precise exit-code table isn't pinned in the public docs, so in scripts, check the exit status and don't assume 0 blindly — verify against codex exec --help on your installed version.

Before you let an unattended agent loose, you need to know what it's allowed to do. Codex separates two controls that are easy to confuse — keep them distinct:

• Sandbox = WHERE Codex can act (the OS-enforced filesystem and network boundary).
• Approvals = WHEN Codex must stop and ask a human.

These are independent. In headless automation there's no human to approve anything, so the sandbox is your real safety boundary — it's what physically prevents the agent from writing files or reaching the network, regardless of approval policy.

The critical default: codex exec runs read-only. Out of the box it can inspect and reason about your code but cannot edit files or run mutating commands. That's a deliberate safe-by-default posture for automation. To let it change things, you must opt in:

# Read-only (default): safe analysis, no changes possible
codex exec 'find any TODO comments and summarize them'

# Opt in to edits for a task that must modify files
codex exec --sandbox workspace-write 'fix the failing lint errors in src/'
codex exec -s workspace-write 'fix the failing lint errors in src/'   # -s is the alias

# Equivalent via config override
codex exec --config sandbox_mode="workspace-write" 'fix the lint errors'

Use danger-full-access (or its blunt cousin --yolo / --dangerously-bypass-approvals-and-sandbox, which drops both sandbox and approvals) only in trusted, ephemeral environments — a throwaway CI container you're about to destroy — never on a developer's machine or a persistent runner. The deprecated --full-auto flag is a legacy alias; prefer --sandbox workspace-write explicitly.

Automation usually means handing Codex the output of something else — a failing test log, an error dump, a diff. codex exec supports two distinct ways to pipe data in, and the difference matters.

Mode 1 — prompt-plus-stdin. You give the instruction as the argument, and whatever is piped in becomes additional context appended to that instruction. This is the common case: a fixed task applied to variable input.

# The piped test output is context; the quoted string is the task
npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix"

Mode 2 — codex exec - (the dash sentinel). When the argument is a single -, stdin becomes the entire prompt. Nothing is hard-coded; the whole instruction arrives over the pipe. Use this when the prompt itself is assembled dynamically.

# stdin IS the prompt — assemble it however you like, then feed it in
printf "Summarize this error log in 3 bullets:\n\n%s\n" "$(tail -n 200 app.log)" | codex exec -

The mental shortcut: with a quoted task argument, stdin is extra context; with -, stdin is the whole prompt. Mode 1 is what you reach for when the job is fixed and only the input varies ("always summarize whatever test output I pipe you"). Mode 2 is for when your script is composing the instruction from templates, variables, or files at runtime.

codex exec has a focused set of flags built for scripting. Here are the ones that earn their keep, all verified against the CLI reference:

Global flags also apply to exec, including --ask-for-approval / -a (untrusted | on-request | never) for approval policy, --config / -c key=value (repeatable, overrides any config key), --image / -i, --profile / -p, and --search.

# Pin the model, run outside a git repo, write the answer to a file, no color
codex exec \
  --model gpt-5.5 \
  --skip-git-repo-check \
  --output-last-message answer.md \
  --color never \
  "draft release notes from the CHANGELOG"

Two of these flags — --json and --output-schema — are the gateway to programmable Codex: parsing exactly what it did, and forcing schema-conforming output you can validate instead of free text. They're the entire subject of the next lesson, so this one just plants the flag; don't worry about the event shape yet.

A note on volatile values: exact model identifiers (--model gpt-5.5, gpt-5.4-codex, and whatever is "recommended" today) shift release to release, and the CLI/SDK versions move together. Don't hard-code a model name from memory — run codex exec --help for the live flag list and check the changelog for current model ids.

A headless run doesn't have to be a dead end. Codex persists each session so a later invocation can pick up the same thread — its conversation history and context — and continue. That turns a one-shot into a resumable, multi-step automation: a first job investigates, a second (perhaps in a different workflow step) acts on what the first learned.

# Resume a specific session by id and add a follow-up instruction
codex exec resume <SESSION_ID> "now implement the fix you proposed"

# Resume the most recent session from THIS directory
codex exec resume --last "continue where you left off"

# The follow-up prompt is optional — resume can simply re-run the thread
codex exec resume --last

Two modifiers shape what "resume" can find:

Where do these sessions live? Under ~/.codex/sessions by default — unless you ran the original with --ephemeral, which tells Codex not to persist the rollout file at all. That's the trade-off to internalize: --ephemeral is the privacy/cleanliness choice for sensitive or throwaway runs, but it means there is nothing to resume. If your pipeline needs a second step to continue the first, don't make the first one ephemeral.

To make this concrete, a two-phase pattern: a first read-only pass diagnoses a problem and prints a session id you capture (you'll learn to pull that id cleanly from the --json stream's thread.started event next lesson); a second pass resumes that session with workspace-write to actually apply the fix.