Codex Agent

Codex Agent Collaboration Skill

This skill enables Claude Code to collaborate with OpenAI's Codex CLI agent.

Optional Codex Review Workflow

Use this workflow when the user asks for Codex review, wants a second opinion, or needs cross-verification from a separate coding agent.

Step 1: Call Codex for Review

codex exec -C <project_path> -s read-only -o /tmp/codex-review.md \
  "Review the code in <file_or_directory>. Check for:
   - Security vulnerabilities
   - Performance issues
   - Code quality and best practices
   - Potential bugs and edge cases
   - Naming and readability
   Provide specific, actionable feedback with file paths and line numbers."

Step 2: Read Codex Feedback

cat /tmp/codex-review.md

Step 3: Apply Fixes Based on Codex Feedback

For each issue identified by Codex: 1. Read the relevant file 2. Apply the fix using Edit tool 3. Verify the fix addresses Codex's concern

Step 4: Re-verify with Codex (Optional)

codex exec -C <project_path> -s read-only \
  "Verify the fixes applied to <files>. Confirm issues are resolved."

Workflow Examples

Example 1: Review and Fix a Single File

# Step 1: Get Codex review
codex exec -C /project -s read-only -o /tmp/codex-review.md \
  "Review src/auth/login.ts for security vulnerabilities and code quality issues. Provide specific line numbers and fixes."

# Step 2: Read the feedback
cat /tmp/codex-review.md

Then the primary agent reads the feedback, applies fixes with Edit tool, and optionally re-verifies.

Example 2: Review Recent Changes

# Get diff of recent changes
git diff HEAD~1 > /tmp/recent-changes.diff

# Step 1: Have Codex review the diff
codex exec -C /project -s read-only -o /tmp/codex-review.md \
  "Review the changes in the last commit. Check for bugs, security issues, and improvements needed."

# Step 2: Read and apply fixes
cat /tmp/codex-review.md

Example 3: Full Project Review

# Step 1: Comprehensive review
codex exec -C /project -s read-only -o /tmp/codex-review.md \
  "Perform a comprehensive code review of src/. Focus on:
   1. Security vulnerabilities (OWASP Top 10)
   2. Error handling patterns
   3. Performance bottlenecks
   4. Code duplication
   Prioritize issues by severity (critical/high/medium/low)."

# Step 2: Read prioritized feedback
cat /tmp/codex-review.md

Review Request Format

When asking Codex for review, include:

Review <target_files_or_directory>.

Context:
- Project type: <TypeScript/Python/etc>
- Framework: <Express/React/etc>
- Focus areas: <security/performance/quality>

Check for:
1. Security vulnerabilities
2. Performance issues
3. Error handling
4. Code quality
5. Edge cases

Output format:
For each issue:
- File: <path>
- Line: <number>
- Severity: critical/high/medium/low
- Issue: <description>
- Fix: <specific code change>

Applying Fixes

After receiving Codex feedback, apply fixes systematically:

1. Parse the review - Extract each issue with file, line, severity 2. Prioritize - Fix critical/high issues first 3. Read file - Use Read tool to see current code 4. Apply fix - Use Edit tool with precise old_string/new_string 5. Track progress - Mark each issue as fixed

Prerequisites

Codex CLI must be installed and authenticated:

# Install via npm
npm install -g @openai/codex

# Or via Homebrew (macOS)
brew install --cask codex

# Authenticate
codex login

Command Reference

Basic Command Pattern

codex exec [options] "<task_description>"

Core Options

AI-to-AI Communication

When communicating with Codex, PRIORITIZE ACCURACY AND PRECISION:

• Use structured data and exact technical terms
• Provide full file paths and precise details
• Include relevant context from the current codebase
• NO conversational formatting needed

Other Use Cases

Cross-Verification (after Claude implements)

codex exec -C /project -s read-only \
  "Verify the implementation in src/feature/. Check correctness and edge cases."

Get Alternative Implementation

codex exec -C /project -s read-only -o /tmp/alternative.md \
  "Propose an alternative implementation for the caching in src/cache/manager.ts"

Debugging Assistance

codex exec -C /project -s read-only \
  "Debug: tests in tests/auth.test.ts failing with timeout. Analyze root cause."

Session Management

For multi-turn reviews:

# Initial review
codex exec -C /project -s read-only "Review src/api/ for security issues"
# Note session ID from output

# Follow-up after fixes
codex exec resume <session_id> "I've applied the fixes. Please re-verify."

Troubleshooting

Authentication Issues

codex logout
codex login

Check Installation

codex --version
which codex

See Also

• scripts/check-codex.sh - Local Codex CLI availability check
• scripts/codex-wrapper.sh - Wrapper for repeatable Codex CLI invocation
• sandbox-modes.md - Sandbox security levels
• examples.md - More usage examples
• advanced.md - Advanced configuration

Advanced Configuration

Advanced usage patterns, MCP integration, and configuration options.

Configuration Files

Codex CLI reads configuration from ~/.codex/config.toml.

Basic Config

# ~/.codex/config.toml

# Default model
model = "gpt-5-codex"

# Default sandbox mode
sandbox = "workspace-write"

# Default approval mode
approval = "on-request"

# Enable web search
search = true

Profiles

Create named profiles for different use cases:

[profiles.review]
model = "gpt-5-codex"
sandbox = "read-only"

[profiles.implement]
model = "gpt-5-codex"
sandbox = "workspace-write"
approval = "on-request"

[profiles.dangerous]
sandbox = "danger-full-access"
approval = "never"

Use with -p flag:

codex exec -p review -C /project "Analyze code"
codex exec -p implement -C /project "Add feature"

MCP Integration

Codex supports Model Context Protocol (MCP) for external tool integration.

Add MCP Server (stdio)

codex mcp add my-server -- /path/to/mcp-server

Add MCP Server (HTTP)

codex mcp add remote-server --url https://mcp.example.com/api

List MCP Servers

codex mcp list --json

Run Codex as MCP Server

codex mcp-server

This allows other MCP clients to use Codex as a tool provider.

Environment Variables

CI/CD Usage

export CODEX_API_KEY="sk-..."
codex exec --json "Generate changelog from git log"

Feature Flags

Enable/disable experimental features:

# Enable feature
codex exec --enable some-feature "task"

# Disable feature
codex exec --disable some-feature "task"

Custom Instructions (AGENTS.md)

Create AGENTS.md in your project root to provide project-specific context:

# Project Context

This is a TypeScript Node.js project using Express.

## Conventions
- Use async/await, not callbacks
- Use Zod for validation
- Tests use Jest with supertest

## Architecture
- src/api/ - Express routes
- src/services/ - Business logic
- src/models/ - Data models

Codex will read this file for context.

Shell Completions

Generate shell completions:

# Bash
codex completion bash > /etc/bash_completion.d/codex

# Zsh
codex completion zsh > ~/.zfunc/_codex

# Fish
codex completion fish > ~/.config/fish/completions/codex.fish

JSON Schema Validation

Enforce structured output:

# schema.json
{
  "type": "object",
  "properties": {
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file": { "type": "string" },
          "line": { "type": "integer" },
          "severity": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    }
  }
}

# Use with Codex
codex exec -C /project --output-schema schema.json \
  "Find all security issues and output as structured JSON"

Local/OSS Mode

Run with local models via Ollama:

# Requires Ollama installed with compatible model
codex exec --oss "Explain this code"

Running in Sandbox

Test sandbox policies:

# Run command in sandbox
codex sandbox -s read-only -- cat /etc/passwd

# Test policy rules
codex execpolicy "rm -rf /" --sandbox read-only

Examples

Practical examples of Claude-Codex collaboration patterns.

Code Analysis & Review

Analyze Code Structure

codex exec -C /project -s read-only \
  "Analyze the architecture of src/services/ directory. Identify patterns, dependencies, and potential improvements."

Security Review

codex exec -C /project -s read-only --json \
  "Review src/api/ for OWASP Top 10 vulnerabilities. Focus on injection, auth, and data exposure." \
  | jq -r '.content.text // .message'

Performance Analysis

codex exec -C /project -s read-only \
  "Identify performance bottlenecks in src/database/queries.ts. Check for N+1 queries and missing indexes."

Cross-Verification

Verify Implementation

Claude implements a feature, then:

codex exec -C /project -s read-only \
  "Review the implementation in src/auth/oauth.ts. Verify correctness, check edge cases, and suggest improvements."

Compare Approaches

codex exec -C /project -s read-only -o /tmp/codex-approach.md \
  "Propose an alternative implementation for the caching logic in src/cache/manager.ts"

Then Claude can read and compare:

cat /tmp/codex-approach.md

Implementation Tasks

Implement Feature (with review)

codex exec -C /project --full-auto \
  "Add rate limiting middleware to src/api/middleware/. Use sliding window algorithm, 100 req/min per IP."

Fix Bug

codex exec -C /project -s workspace-write \
  "Fix the race condition in src/queue/worker.ts line 45-60. Ensure thread-safe access to shared state."

Refactor Code

codex exec -C /project --full-auto \
  "Refactor src/utils/helpers.ts: split into separate modules, add TypeScript types, improve naming."

Multi-Turn Sessions

Start a Session

# First interaction - note the session ID in response
codex exec -C /project --json \
  "Analyze the test coverage in tests/. What areas need more testing?" \
  | tee /tmp/session.json | jq -r '.session // empty'

Continue Session

# Use session ID from previous response
codex exec resume <session_id> \
  "Generate test cases for the auth module you identified"

Resume Last Session

codex exec resume --last "What was the priority order again?"

Output Handling

Save to File

codex exec -C /project -o /tmp/analysis.md \
  "Document the API endpoints in src/api/routes/"

cat /tmp/analysis.md

JSON Processing

# Extract just the message content
codex exec -C /project --json "Explain main.ts" \
  | jq -s 'map(select(.type == "turn.completed")) | .[0].content'

Stream Events

# Watch events in real-time
codex exec -C /project --json "Implement logging" \
  | while read -r line; do
      echo "$line" | jq -r '.type // "event"'
    done

Integration Patterns

Claude + Codex Code Review Pipeline

1. Claude writes code 2. Run Codex review:

codex exec -C /project -s read-only -o /tmp/review.md \
  "Review the uncommitted changes. Check for bugs, security issues, and code style."

3. Primary agent reads review and addresses issues

Parallel Analysis

Run multiple Codex analyses in background:

codex exec -C /project -s read-only -o /tmp/security.md \
  "Security audit of src/" &

codex exec -C /project -s read-only -o /tmp/perf.md \
  "Performance analysis of src/" &

wait
cat /tmp/security.md /tmp/perf.md

Structured Output

codex exec -C /project --json --output-schema /path/to/schema.json \
  "List all TODO comments in the codebase with file, line, and content"

Debugging Collaboration

Analyze Test Failures

codex exec -C /project -s read-only \
  "Tests in tests/auth.test.ts are failing. Analyze the test setup, mocks, and async handling."

Debug Runtime Error

codex exec -C /project -s read-only \
  "Getting 'undefined is not a function' at src/app.ts:123. Trace the call stack and identify root cause."

Memory Leak Investigation

codex exec -C /project -s read-only \
  "Investigate potential memory leaks in src/cache/. Check for event listener cleanup and cache eviction."

Codex Agent Skill

A Spellbook skill for optional Codex-based second-opinion reviews, cross-verification, debugging, and alternative implementation proposals.

Core Workflow

Code Review Request
       ↓
   ┌───────────────────┐
   │  Codex Reviews    │  ← Primary agent calls Codex CLI
   │  (read-only)      │
   └───────────────────┘
       ↓
   ┌───────────────────┐
   │  Codex Feedback   │  ← Issues with file:line:severity
   └───────────────────┘
       ↓
   ┌───────────────────┐
   │  Primary Agent    │  ← Primary agent fixes code using Edit tool
   │  Fixes            │
   └───────────────────┘
       ↓
   ┌───────────────────┐
   │  (Optional)       │  ← Codex re-verifies
   │  Re-verify        │
   └───────────────────┘

Features

• Second-Opinion Review: Use Codex when you want an independent review pass
• Guided Fixes: Apply fixes based on Codex's specific feedback
• Structured Output: Codex provides file paths, line numbers, and severity levels
• Re-verification: Optional second pass to confirm fixes

Prerequisites

Install Codex CLI

# Via npm
npm install -g @openai/codex

# Via Homebrew (macOS)
brew install --cask codex

Authenticate

codex login

Installation

Option 1: User-level (all projects)

cp -r codex-agent ~/.claude/skills/codex-agent
cp -r codex-agent ~/.codex/skills/codex-agent

Option 2: Project-level

mkdir -p .claude/skills
cp -r codex-agent .claude/skills/codex-agent

Usage

When you ask for a Codex second opinion, the primary agent will:

1. Call Codex to perform the review 2. Parse feedback from Codex (file, line, severity, issue, fix) 3. Apply fixes using Edit tool 4. Optionally re-verify with Codex

Example Prompts

Review my authentication code and fix any issues

Do a security review of src/api/ and apply the fixes

Review the recent changes and fix problems Codex finds

Workflow Details

Step 1: Codex Review

The primary agent executes:

codex exec -C /project -s read-only -o /tmp/codex-review.md \
  "Review src/auth/. Check for security, performance, code quality.
   Provide file paths, line numbers, and specific fixes."

Step 2: Parse Feedback

Codex outputs structured feedback:

- File: src/auth/login.ts
- Line: 45
- Severity: high
- Issue: SQL injection vulnerability
- Fix: Use parameterized query instead of string concatenation

Step 3: Primary Agent Applies Fixes

The primary agent reads the file, applies the fix with Edit tool:

old_string: `SELECT * FROM users WHERE id = '${userId}'`
new_string: `SELECT * FROM users WHERE id = $1`, [userId]

Step 4: Re-verify (Optional)

codex exec -C /project -s read-only \
  "Verify fixes in src/auth/login.ts. Confirm SQL injection is resolved."

File Structure

codex-agent/
├── SKILL.md           # Main skill with optional Codex review workflow
├── sandbox-modes.md   # Sandbox security documentation
├── examples.md        # Usage examples
├── advanced.md        # Advanced configuration
├── scripts/
│   ├── codex-wrapper.sh   # Helper wrapper script
│   └── check-codex.sh     # Installation checker
└── README.md          # This file

Configuration

Recommended Permissions

Add to .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(codex:*)"
    ]
  }
}

Sandbox Modes

Troubleshooting

Codex not found

npm install -g @openai/codex

Authentication issues

codex logout
codex login

License

MIT

References

• OpenAI Codex CLI
• Claude Code Skills
• Codex Documentation

Sandbox Modes

Codex CLI provides three sandbox security levels to control file system access.

Mode Comparison

Read-Only Mode (Default)

codex exec -s read-only -C /project "Analyze code quality"

• Cannot create, modify, or delete files
• Safe for analysis and review tasks
• Recommended for most read operations

Workspace Write Mode

codex exec -s workspace-write -C /project "Refactor the auth module"

• Write access limited to:
• Current workspace directory
• /tmp directory
• Cannot modify files outside workspace
• Recommended for safe code modifications

Full Access Mode

codex exec -s danger-full-access -C /project "Update system config"

Use with extreme caution:

• Unrestricted file system access
• Can modify any file on the system
• Only use in isolated/sandboxed environments (VMs, containers)

Full Auto Mode

codex exec --full-auto -C /project "Implement feature X"

Combines:

• workspace-write sandbox
• Automatic approval for actions (no prompts)

Equivalent to:

codex exec -s workspace-write -a on-request -C /project "task"

Approval Modes

Control when human approval is required:

Best Practices

1. Start with read-only - Default to analysis mode 2. Use workspace-write for edits - Contains changes to project 3. Avoid full-access - Only in truly isolated environments 4. Review before commit - Always verify Codex's changes 5. Use `--add-dir` - Grant specific directory access instead of full-access

# Better than danger-full-access:
codex exec --add-dir /path/to/other/dir -C /project "task"