Codex CLI Sub-Agent

A skill for invoking the OpenAI Codex CLI as a sub-agent in non-interactive mode (codex exec).

Prerequisites

• Installed via npm install -g @openai/codex (verified against codex-cli 0.144.1)
• Authenticated — either codex login (ChatGPT sign-in) or an OPENAIAPIKEY environment variable

How to run

codex exec runs Codex non-interactively via the Bash tool. Choose the sandbox by what the task needs — there is no --full-auto/--quiet/--ephemeral flag (those were removed; exec is already headless and stateless).

# Read-only analysis / review (safe default — Codex cannot modify files)
codex exec -s read-only "<task>"

# Task that must edit files in the current workspace
codex exec -s workspace-write "<task>"

Pass the prompt as the positional argument, or via stdin (see Long prompts). Add --skip-git-repo-check when running outside a git repository.

Flags

Long prompts

Pass the prompt on stdin with a trailing - (a heredoc avoids quoting issues):

cat <<'EOF' | codex exec -s read-only --color never -
<long prompt>
EOF

If both a positional prompt and piped stdin are given, stdin is appended as a <stdin> block.

Image generation (GPT-Image-2)

Codex has a built-in imagegen tool backed by GPT-Image-2 (feature imagegeneration, enabled by default). It works with the ChatGPT sign-in — no OPENAIAPIKEY required. Use -s workspace-write: Codex generates under $CODEXHOME/generatedimages/ and then copies the file into the workspace.

# Generate a new image
codex exec -s workspace-write "Generate an image of <subject> and save it as assets/hero.png in the current directory."

# Edit an existing image: attach it with -i and terminate the flag with --
# (-i is variadic; without -- it swallows the prompt as another file path and
#  codex falls through to "Reading prompt from stdin..." and exits 1)
codex exec -s workspace-write -i input.png -- "Edit the attached image: <change>. Keep everything else unchanged. Save the result as input-edited.png."

How to instruct it (all verified):

• Always name the destination file in the prompt — otherwise the output may stay under $CODEXHOME/generatedimages/ instead of the workspace.
• State the size in the prompt and it is honored, e.g. "Output size 1024x1024". GPT-Image-2 accepts edges up to 3840px (multiples of 16, aspect ratio ≤ 3:1); common sizes: 1024x1024, 1536x1024 landscape, 1024x1536 portrait, 3840x2160 4K.
• Structure the prompt: subject → style/medium → composition/framing → lighting/mood → constraints ("no text, no watermark"). Quote any text to render verbatim.
• For edits, spell out invariants ("change only X; keep the background and composition identical") — Codex passes the attached image to the edit flow.
• Transparent backgrounds work by asking for them ("with a transparent background"): GPT-Image-2 has no native transparency, but Codex generates on a chroma-key background and removes it locally, producing an alpha PNG.

Notes

• Progress is written to stderr; the final result goes to stdout. Redirect stderr (e.g. 2>/tmp/codex.err) to keep the result clean, and inspect it on failure.
• Set a generous timeout (up to 10 minutes: timeout: 600000).
• Each codex exec is a fresh session — no context carries over between calls. Put everything the task needs into the prompt.
• Prefer the least privilege that fits: read-only for review/analysis, workspace-write only when edits are required.
• Summarize the result back to the user rather than dumping raw output.