/codex-agent

name: codex-agent
description: Use when you want a second-opinion review via Codex CLI, cross-verification after another agent implements changes, debugging help, or alternative implementation proposals. Requires Codex CLI to be installed and authenticated.
compatibility: Designed for Claude Code with an installed and authenticated Codex CLI.
metadata:
  spellbook-runtimes: "claude_code"
allowed-tools:
  - Bash(REPORT=*)
  - Bash(DIFF_REPORT=*)
  - Bash(codex:*)
  - Bash(mktemp:*)
  - Bash(cat:*)
  - Bash(git diff:*)
  - Read
  - Edit
  - Grep
  - Glob

Codex Agent Collaboration Skill

This skill enables Claude Code to collaborate with OpenAI's Codex CLI agent for second-opinion review, cross-verification, debugging analysis, and alternative implementation proposals.

Default posture: Codex reviews in `read-only`; the primary agent applies changes only when the user asked for fixes or approved them after reading the review.

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 and Read Feedback

REPORT="$(mktemp -t codex-review.XXXXXX.md)"
codex exec -C <project_path> -s read-only -o "$REPORT" \
  "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."

cat "$REPORT"

Keep the write and read in the same Bash call, or pass a concrete report path between calls; shell variables do not persist across tool calls.

Step 2: Apply Fixes Based on Codex Feedback

When the user asked to apply fixes, handle 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

If the user only asked for a review or second opinion, report findings without editing files.

Step 3: 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
REPORT="$(mktemp -t codex-review.XXXXXX.md)"
codex exec -C /project -s read-only -o "$REPORT" \
  "Review src/auth/login.ts for security vulnerabilities and code quality issues. Provide specific line numbers and fixes."

# Step 2: Read the feedback
cat "$REPORT"

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
DIFF_REPORT="$(mktemp -t recent-changes.XXXXXX.diff)"
git diff HEAD~1 > "$DIFF_REPORT"

# Step 1: Have Codex review the diff
REPORT="$(mktemp -t codex-review.XXXXXX.md)"
codex exec -C /project -s read-only -o "$REPORT" \
  "Review the changes saved at $DIFF_REPORT. Check for bugs, security issues, and improvements needed."

# Step 2: Read and apply fixes
cat "$REPORT"

Example 3: Full Project Review

# Step 1: Comprehensive review
REPORT="$(mktemp -t codex-review.XXXXXX.md)"
codex exec -C /project -s read-only -o "$REPORT" \
  "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 "$REPORT"

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

| Option | Description | |--------|-------------| | `"<task>"` | Task description (positional, must be quoted) | | `-C <dir>` | Working directory (use absolute path) | | `-s read-only` | Read-only sandbox (use for reviews) | | `-o <path>` | Save output to file | | `--json` | Output as JSON Lines |

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

REPORT="$(mktemp -t codex-alternative.XXXXXX.md)"
codex exec -C /project -s read-only -o "$REPORT" \
  "Propose an alternative implementation for the caching in src/cache/manager.ts"
cat "$REPORT"

Debugging Assistance

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