Headless Codex CLI Automation

What it does

When your agent uses it

• Running Codex CLI unattended inside a CI pipeline
• Automating Codex inside a Docker or Kubernetes job
• Choosing a sandbox and approval mode for a headless Codex run
• Recovering from a Codex run stuck waiting on user input

Example prompts

• “Set up a read-only Codex exec command to review this repo for a CI check.”
• “Write a workspace-write Codex exec call that won't stop for approval prompts.”
• “Why does my Codex job hang waiting for input inside Kubernetes?”

Requirements

• OpenAI Codex CLI

Workflow steps

9 steps, taken from the first numbered list in SKILL.md.

1. 1Use codex exec, not the interactive codex TUI.
2. 2Pass the task as the positional PROMPT argument. Do not use -p for the prompt; -p selects a profile.
3. 3For ordinary unattended code changes, prefer
4. 4Use --yolo only inside an externally hardened and disposable runner. It disables Codex approvals and sandboxing.
5. 5For harnesses and CI, prefer --json plus --output-last-message.
6. 6Do not make the run depend on a human answering questions. Resolve ambiguity using repository evidence and conservative defaults.
7. 7Treat credentials as secrets. Inject CODEX_API_KEY only into the single codex exec process when possible.
8. 8Before giving version-sensitive advice, inspect codex exec --help or current official Codex documentation if available.
9. 9On Windows, choose one execution environment per task: native PowerShell for Windows toolchains or WSL2 for Linux toolchains. Do not…

What it can do on your machine

Read from SKILL.md and the folder at commit 6babeb0. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Shell commands in SKILL.md call:

  • codex
  • npm

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md. Its commands use npm, which can reach the network depending on how they are called.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • CODEX_API_KEY
  • OPENAI_API_KEY

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Headless Codex CLI Automation loads about 2.7k tokens when it runs, and up to ~7.4k if it reads all its reference files. Until then it costs about 131 tokens; SKILL.md has 1,019 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~131

When it runs · the whole SKILL.md, loaded when a task matches

~2.7k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~7.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from XiaomiMiMo/MiMo-Code at commit 6babeb0, republished under its MIT licence (© XiaomiMiMo). 1,019 words, ~2,683 tokens.

name

codex

description

Run, configure, and troubleshoot OpenAI Codex CLI in non-interactive headless environments. Use for Codex automation in Bash or PowerShell, native Windows or WSL2, shell scripts, CI/CD, Docker, Kubernetes, remote servers, agent harnesses, or batch jobs; for constructing `codex exec` commands; selecting sandbox and approval modes; consuming JSONL events or structured output; resuming sessions; passing prompts through stdin; and handling failures caused by unavailable interactive input such as `request_user_input`.

codex exec \
  -C /path/to/repo \
  --sandbox workspace-write \
  --ask-for-approval never \
  "<TASK>"

codex exec \
  -C /path/to/repo \
  --sandbox read-only \
  --ask-for-approval never \
  "Analyze the repository and report risks. Do not modify files."

codex exec \
  -C /path/to/repo \
  --sandbox workspace-write \
  --ask-for-approval never \
  "Implement the task, run relevant tests, and report unresolved blockers."

codex exec \
  -C /workspace/repo \
  --yolo \
  "Implement the task and validate the result."

Work fully autonomously.

Do not ask the user questions and do not request interactive input.
Inspect the repository and available context before making assumptions.
When several valid approaches exist, choose the option that:
1. minimizes unrelated changes,
2. preserves backward compatibility,
3. introduces the fewest new dependencies,
4. avoids destructive or irreversible actions.

Continue until the task is complete or a concrete blocking error is reached.
Record assumptions, validation performed, and unresolved blockers in the final response.

codex exec "Summarize the repository structure."

codex exec - < prompt.md

npm test 2>&1 | codex exec "Analyze this test output and fix the repository."

codex exec \
  --skip-git-repo-check \
  -C /tmp/task \
  "Analyze the files in this directory."

codex exec \
  -C /workspace/repo \
  --output-last-message /output/final.md \
  "Review the codebase."

codex exec \
  -C /workspace/repo \
  --json \
  --sandbox workspace-write \
  --ask-for-approval never \
  "Run tests and fix failures." \
  > /output/events.jsonl

codex exec \
  -C /workspace/repo \
  --json \
  --sandbox workspace-write \
  --ask-for-approval never \
  --output-last-message /output/final.md \
  "Complete the task autonomously." \
  | tee /output/events.jsonl

codex exec \
  -C /workspace/repo \
  --sandbox workspace-write \
  --ask-for-approval never \
  --output-schema /input/result.schema.json \
  --output-last-message /output/result.json \
  "Implement the task, validate it, and return the requested structured result."

codex exec resume --last "Continue the previous task and fix remaining issues."

codex exec resume "$SESSION_ID" "Continue with the next stage."

codex exec --ephemeral "Analyze the repository."

codex login

codex login --device-auth

CODEX_API_KEY="$OPENAI_API_KEY" \
codex exec --json "Triage the repository."

© XiaomiMiMo, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (references) in packages/cli/src/skill/builtin/.bundle/codex of XiaomiMiMo/MiMo-Code.

• SKILL.md
• agents/openai.yaml
• references/recipes.md
• references/windows.md

Open the folder on GitHubat commit 6babeb0