Codex CLI

Codex CLI

Use this skill when the user asks this agent to talk to Codex, consult Codex, delegate a coding/review/research task to Codex CLI, or ask Codex to generate an image.

The core interface is:

codex exec "prompt"

For automation, prefer non-interactive codex exec over interactive codex.

First Check

Before using Codex CLI, verify it is available:

command -v codex
codex --version
codex exec --help

If codex is missing, tell the user Codex CLI is not available in this environment and stop. Do not simulate a Codex response.

If codex exec --help is available, use it as the source of truth for the installed CLI flags. Codex CLI changes over time.

One-Off Task Workflow

Use this for normal delegation:

codex exec -C "$PWD" -s read-only "Review this repository and identify likely bugs"

For tasks that may edit files, use the sandbox the user requested or the host agent allows:

codex exec -C "$PWD" -s workspace-write "Implement the requested change"

For a response file:

codex exec -C "$PWD" -o /tmp/codex-last-message.md "Summarize this project"

For machine-readable events:

codex exec -C "$PWD" --json -o /tmp/codex-last-message.md "Analyze this project"

If the prompt is long, pass it via stdin:

codex exec -C "$PWD" - < /tmp/prompt.txt

When using shell commands from another agent, avoid dangerous flags unless the user explicitly asked for them. Prefer read-only for review, planning, critique, image generation, and analysis.

Prompt Shape

For non-trivial tasks, shape the delegated prompt with OpenAI's Codex best-practices structure:

Goal:
Context:
Constraints:
Done when:

Keep the prompt scoped to one task. For complex implementation work, ask Codex for a plan first in read-only mode, then run a separate write task after the plan is accepted.

Session Resume

Codex emits a session id in normal startup output and in JSONL events as thread.started.

To resume:

codex exec resume <session-id> "Continue from the previous task"

If the installed CLI supports a different resume syntax, follow codex exec resume --help.

Image and File Input

Codex cannot browse or read image files on its own. To let Codex see an image, attach it explicitly with -i/--image. This is the input side; image generation (below) is the output side.

Attach a single image:

codex exec -C "$PWD" -s read-only -i screenshot.png "Explain the error shown here"

Attach multiple images. Both forms work — comma-separated or a repeated flag:

codex exec -i before.png,after.png "Compare these two UI states"
codex exec -i mock1.png -i mock2.png "Which layout is closer to the spec?"

Best practices:

• Put -i flags before the prompt text.
• Use common raster formats: PNG (best for screenshots/UI, lossless) or JPEG. Keep images reasonably small; very large images slow the request.
• Combine images with a clear text instruction — the image alone is rarely enough context.
• For visual review/analysis, pair with -s read-only so Codex inspects but does not edit.

For non-image files there is no attach flag. Two options:

• Let Codex read the file from the workspace: point it at the directory with -C "$PWD" and name the file in the prompt ("Review src/auth.ts"). Use this for files already in the repo.
• Pipe file contents via stdin. With a prompt also present, stdin is appended to the prompt as a <stdin> block:

codex exec -C "$PWD" "Summarize the attached log" < /tmp/build.log

Image Generation Workflow

Codex can generate images through its built-in image generation tool when asked through codex exec.

Example:

codex exec "Generate a black banana image with aspect ratio 16:9"

Important behavior:

• Built-in image generation commonly saves files under $CODEX_HOME/generated_images/<codex-session-id>/.
• If CODEX_HOME is unset, use ~/.codex/generated_images/<codex-session-id>/.
• Codex may not print the path in its final response.
• The agent using this skill must proactively locate and report generated image paths after image generation.
• The PNG metadata may not expose the exact image model. Do not claim a specific backend model unless Codex output, CLI logs, or metadata clearly show it.