codex-guide

Codex CLI Guide

OpenAI Codex CLI (codex) is a terminal-based AI coding agent powered by OpenAI models. This skill covers how to invoke Codex from within Claude Code sessions — primarily as a second-opinion reviewer or non-interactive task runner.

Current Environment

!codex --version 2>/dev/null || echo "codex not installed"

Key Concepts

Codex CLI has two main execution modes:

• Interactive (codex "prompt"): Opens a TUI session. Not suitable for use within Claude Code — use exec instead
• Non-interactive (codex exec "prompt"): Runs headlessly, returns output. This is the primary integration point with Claude Code

Sandbox Modes

Sandbox controls what file-system and network access Codex-spawned commands have:

• read-only: Can read the repo but cannot write files or run destructive commands. Use for reviews and analysis
• workspace-write: Can write within the project directory. Use for code generation and fixes
• danger-full-access: No sandbox restrictions. Use only when explicitly needed

Set via -s flag: codex exec -s read-only "prompt"

Usage Patterns

Pattern 1: Plan / Code Review via codex exec

Run Codex as a reviewer with output separated from logs. This is the standard pattern used by the planner persona.

cat <file> | codex exec -s read-only -o <output-file> "review instructions" > <log-file> 2>&1

• -o <file>: Write only the final answer to this file. Read this file for results
• > <log> 2>&1: Redirect verbose execution logs (thinking, tool calls) to a separate file. Do NOT read this unless debugging — it is large and will bloat context
• Stdin pipe: Content piped via stdin is appended as a <stdin> block to the prompt

function review_with_codex(content_path, instructions):
  output = tmp_file("codex-output.txt")
  log = tmp_file("codex-log.txt")

  exit_code = run("cat {content_path} | codex exec -s read-only -o {output} '{instructions}' > {log} 2>&1")

  if exit_code != 0:
    record_failure(reason: "codex failed", exit_code)
    return fallback_to_self_review()

  return read(output)

Failure handling: If codex is not installed, not logged in, times out, or exits non-zero — record the failure reason and fall back to self-review. Never block the main workflow on Codex failure.

Pattern 2: Code Review via codex review

Dedicated review subcommand that automatically diffs against a base branch or commit.

codex review --base main
codex review --uncommitted
codex review --commit <sha>

• --base <branch>: Review diff between current branch and the base branch
• --uncommitted: Review staged, unstaged, and untracked changes
• --commit <sha>: Review changes introduced by a specific commit
• --title <title>: Optional commit title for the review summary

Pattern 3: Non-interactive Task Execution

Run a one-shot task with Codex and capture the result.

codex exec -s workspace-write -o result.txt "implement the function described in TODO.md"

Use -s workspace-write when Codex needs to write files. Use -s read-only for analysis-only tasks.

Pattern 4: Image Input

Attach images for visual context.

codex exec -i screenshot.png "describe what this UI shows"

Pattern 5: Image Generation

Codex has a built-in image generation tool (DALL-E). Unlike Claude Code, Codex can generate actual raster images (PNG) — not just SVG, HTML, or Mermaid diagrams. To trigger it, explicitly instruct Codex to use its image generation tool in the prompt.

codex exec -s workspace-write -o result.txt "画像生成ツールを使用して、<description> の画像を生成し、<path> に保存して"

• MUST: Include "画像生成ツールを使用して" (or "use the image generation tool") explicitly in the prompt — without this phrase, Codex may default to code-based alternatives (SVG, matplotlib, etc.)
• MUST: Use -s workspace-write so Codex can write the generated image file to disk
• Use when a real raster image is needed: UI mockups, diagrams with rich visuals, icons, illustrations, or any case where SVG/Mermaid/HTML is insufficient

Output Separation Rule

When calling codex exec from within Claude Code:

• MUST: Use -o <file> to capture the final answer separately
• MUST: Redirect stdout/stderr to a log file (> log.txt 2>&1)
• MUST: Read only the -o output file for results
• PROHIBIT: Read the log file unless actively debugging a Codex failure
  • The log contains verbose execution traces (tool calls, thinking steps) that will bloat the Claude Code context window

Configuration

Global config: ~/.codex/config.toml (TOML format)

Key settings:

• model: Default model (e.g., "gpt-5.5")
• model_reasoning_effort: Reasoning effort level (e.g., "high", "xhigh")
• sandbox_mode: Default sandbox mode
• personality: Agent personality style

Override any config value inline with -c:

codex exec -c model="gpt-5.5" -s read-only "prompt"

Project-level Config

Place .codex/ directory in the project root:

• .codex/config.toml: Project-specific configuration overrides
• .codex/instructions.md: Project-specific instructions (equivalent to CLAUDE.md)

MCP Servers

Add external MCP servers to Codex:

codex mcp add <name> -- <command> [args...]
codex mcp list
codex mcp remove <name>

Plugins

Manage Codex plugins from marketplace:

codex plugin list
codex plugin add <name>
codex plugin remove <name>

Session Management

• codex resume: Resume a previous interactive session (picker UI)
• codex resume --last: Resume the most recent session
• codex fork: Fork a previous session to start from a checkpoint
• codex archive <id>: Archive a saved session
• codex delete <id>: Permanently delete a session

Session index: ~/.codex/session_index.jsonl Archived sessions: ~/.codex/archived_sessions/*.jsonl

Diagnostics

codex doctor          # Full diagnostic report
codex doctor --json   # Machine-readable report
codex doctor --summary # Grouped summary only

Check installation health, auth status, config validity, and runtime availability.

Integration with Claude Code

When Claude Code calls Codex, treat Codex as an advisory tool — not an authority:

• Codex feedback is advice. Adopt or reject based on project constraints and user agreements
• Do not adopt suggestions that contradict AGENTS.md rules or user-approved decisions
• If Codex is unavailable, continue with self-review — never block the workflow

The planner persona demonstrates this pattern: it pipes plan files to codex exec -s read-only for review, treats the feedback as input, and makes the final judgment itself.

Bundled Resources

(No bundled resources found)