codex-guide

name	codex-guide
description	This skill should be used when the user asks about 'codex の使い方', 'codex exec のやり方', 'codex でレビュー', 'codex review', 'codex の設定', 'how to use codex', 'codex CLI guide', or wants to run OpenAI Codex CLI from within Claude Code. Covers exec patterns, sandbox modes, output separation, configuration, and integration guidelines.

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)