Codex Integration

Codex Integration

OpenAI's Codex CLI is a complementary tool for detail-oriented code analysis. Codex excels at thorough, meticulous review work - think of it as a "sharp-eyed second opinion" for code.

When to Use Codex

Ideal use cases:

• Deep code review for security vulnerabilities or correctness issues
• Thorough bug hunting in complex code paths
• Detailed implementation planning with attention to edge cases
• Getting a second perspective on critical code
• Exploratory analysis requiring meticulous attention

Not ideal for:

• Simple, straightforward tasks Claude handles well alone
• Interactive debugging sessions (Codex exec is non-interactive)
• Tasks where speed matters more than depth
• Trivial code changes or obvious fixes

Invocation Methods

Method 1: Explicit /codex Command

Users invoke directly with optional flags:

/codex review the authentication middleware for security issues
/codex --model gpt-5.4 analyze this algorithm
/codex --sandbox workspace-write generate tests for this module

Available flags:

Method 2: Spawning codex-agent

When Claude determines Codex would add value, spawn the codex-agent subagent:

"Let me have Codex take a detailed look at this code for potential bugs..."
[Spawn codex-agent with task description]
[Synthesize Codex's findings with own analysis]

The agent always uses safe defaults (gpt-5.4, read-only sandbox).

CLI Reference

Core command pattern for non-interactive execution (use inline prompt, not piped stdin):

codex exec \
  --model gpt-5.4 \
  --sandbox read-only \
  "<prompt>" \
  2>&1

Key flags:

• --model, -m - Model to use (gpt-5.4 recommended for code tasks)
• --sandbox, -s - Execution permissions (read-only safest)
• 2>&1 - Capture all output

Note: Interactive slash commands like /review only work in Codex's interactive mode, not via codex exec.

Error Handling

Codex Not Installed

If codex command not found, show:

Codex CLI is not installed.

To install:
  brew install codex

Then authenticate:
  codex login

For more info: https://developers.openai.com/codex/cli

Common Issues

• API key issues: User needs to run codex login to authenticate
• Timeout: Complex tasks may take time. Be patient or try a simpler task description.
• Sandbox errors: If Codex needs to write files, user must specify --sandbox workspace-write

Best Practices

1. Start with defaults - gpt-5.4 works well for most tasks
2. Keep read-only sandbox - Unless task explicitly requires file modifications
3. Be specific in prompts - Tell Codex exactly what to look for
4. Synthesize results - When using codex-agent, combine Codex's findings with Claude's analysis

Prompting Best Practices

gpt-5.4 responds best to explicit, scoped prompts with concrete constraints.

Core Principles

1. Scope discipline - Be explicit about boundaries

   • DO: "Review ONLY the auth flow. Do NOT suggest unrelated improvements."
   • DON'T: "Review this code" (too open-ended)

2. Bias toward action - Request concrete output

   • DO: "List specific bugs found with file:line references"
   • DON'T: "Tell me what you think about this code"

3. No preambles - Skip status updates

   • Add to prompts: "Skip preambles. Lead with findings."

4. Structured output - Request specific formats

   • "Format: file.ts:line - issue description"

Task-Specific Prompt Templates

Security Review

Review <file/module> for security vulnerabilities.
Focus ONLY on: auth, injection, data exposure, access control.
Do NOT suggest style changes or refactoring.
Format each finding as: `file:line` - severity - issue
Skip preambles.

Bug Hunting

Find bugs in <file/module>.
Look for: edge cases, off-by-one, null handling, race conditions.
ONLY report actual bugs, not style issues.
Format: `file:line` - bug description - suggested fix
Skip preambles. Lead with findings.

Implementation Planning

Create implementation plan for: <feature>.
Constraints: <existing patterns to follow>.
Output structure:
1. Overview
2. Files to modify (with line ranges)
3. Implementation steps
4. Edge cases to handle
Do NOT include code samples unless critical. Skip preambles.

Code Review

Review <file> for correctness and reliability.
Focus ONLY on: logic errors, missing error handling, incorrect assumptions.
Ignore: style, naming, formatting.
Format: `file:line` - issue - recommendation
Skip preambles.