Codex CLI Headless Mode: Run Bounded Tasks in Scripts

Codex CLI headless mode means running the tool non-interactively, without pausing for your approval at each step. You pass the task as an argument, the agent runs it to completion, and the script continues. Because there is no human in the loop during the run, the boundary of the task must be set correctly before it starts.

Headless runs are useful in CI pipelines, scheduled scripts, and multi-step automation. They require more careful upfront planning than an interactive session. A tool like fenbs keeps the task plan and the reviewed result outside the script, so the next person or session can see what ran and what it produced.

When headless is the right choice

Use headless mode when the task is well-defined, the scope is narrow, and the output is easy to check. A task like "format all files in the src directory" is a good candidate. A task like "review this pull request and suggest improvements" is not, because the result needs a human to evaluate it before anything changes.

For tasks where you want to see a plan before committing to it, use plan mode in an interactive session first, then convert the approved plan into a headless run once you know exactly what the agent will do. See codex cli plan mode for how that workflow looks.

Run Codex CLI non-interactively

Pass the task description as an argument and set the approval policy to full-auto to skip interactive prompts. The --quiet flag suppresses progress output, leaving only the final result:

codex --approval-policy full-auto --quiet "Format all TypeScript files in src/ using Prettier"

Without --quiet, Codex CLI prints its reasoning and steps as it works. In a script, you may want that output captured to a log file rather than sent to the terminal:

codex --approval-policy full-auto "your task" > codex-run.log 2>&1

Check the OpenAI Codex repository↗ (opens in a new tab) for the current list of flags, since the CLI is updated regularly.

Set the scope before running

In an interactive session, you can correct a misunderstanding mid-task. In a headless run, you cannot. The scope must be in the task description itself: which files, which directories, which operations are allowed, and what done looks like.

A scope boundary in a headless task looks like: "Apply the formatting changes only to files in src/components. Do not modify any test files. Stop and report an error if any file fails to parse."

Standing rules that apply across many headless runs, such as "never modify files outside the src directory" or "always commit changes with a descriptive message", belong in a shared Decisions and rules record, not in every task description. A connected assistant reads them before it starts.

Handle output and check results

A headless run finishes with an exit code: zero for success, non-zero for failure. Check the exit code in your script before treating the run as complete:

codex --approval-policy full-auto "your task"
if [ $? -ne 0 ]; then
  echo "Codex task failed" >&2
  exit 1
fi

A zero exit code means the agent finished without an error, not that the result is correct. Run a validation step after the agent finishes: a test suite, a lint check, or a build. Those automated checks tell you whether the output meets the criteria.

Review before acting on the result

Even in a headless run, a person should review the output before it affects a shared system. A CI pipeline that runs Codex CLI and automatically merges the result skips the review step entirely. Use headless runs to prepare a result for review, not to bypass it.

After a run, check the Git diff before committing. If the result looks correct, commit it with a clear message noting that it was produced by a Codex CLI run. If something looks wrong, investigate before committing.

The codex cli hooks guide covers post-session hooks that can send a notification or write a summary when a headless run ends.

Record the plan and result

A headless run produces a result and exits. Without a record, the next person who looks at the repository has to infer what ran and why from the commit messages alone. Keep the task plan and the reviewed result somewhere a future session can read them.

Record in the task: the task description used, the approval policy, the exit code, what you checked in the review, and whether the result was committed. That record takes two minutes and saves the next session from having to reconstruct the story.

How to do this with fenbs

1. Create a free account and add the task. Write the goal, scope, and completion criteria as the plan before the run.
2. Add standing constraints as Decisions and rules in the project: what the agent may and may not do, what counts as a successful run.
3. Connect Codex CLI from Integrations. For a headless run, the assistant reads the project rules from fenbs before it starts.
4. After the run, update the task in fenbs: the exit code, what you reviewed in the diff, whether it was committed, and what the next step is.
5. If the run revealed a gap or a recurring pattern, add a Lesson to the project so future headless runs start with that knowledge.