Skip to content

claude-code-with-codex.md

Latest commit

 

History

History
190 lines (126 loc) · 6.19 KB

claude-code-with-codex.md

File metadata and controls

190 lines (126 loc) · 6.19 KB

Using Claude Code with Codex CLI

This guide covers how to use Anthropic's Claude Code and OpenAI's Codex CLI together effectively. Both are terminal-based AI coding agents, and they complement each other well.

What Is Codex CLI?

Codex CLI is OpenAI's open-source (Apache 2.0) coding agent that runs in your terminal. First released April 2025, it's built in Rust and supports GPT models optimized for coding.

Install:

# npm
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

Authenticate via ChatGPT sign-in (works with existing Plus/Pro/Team plans) or API key.

Key Differences

Claude Code Codex CLI
Models Claude Opus 4.6, Sonnet 4.5 GPT-5-Codex
Instructions file CLAUDE.md AGENTS.md
Sandbox macOS Seatbelt, configurable Sandboxed by default (configurable via sandbox_mode)
Approval modes Permission rules in settings.json approval_policy + sandbox_mode in config.toml; --auto-edit / --full-auto flags
Multi-agent Subagents, agent teams (experimental) Single agent (parallelize manually)
Slash commands Skills/commands system Not built-in
License Proprietary Apache 2.0
Config ~/.claude/settings.json ~/.codex/config.toml

When to Use Which

Both tools are highly capable across all tasks. In practice, use whichever you're more fluent with. Some reasons to reach for one over the other:

  • Claude Code has built-in multi-agent support (subagents, agent teams), skills/commands, and hooks
  • Codex CLI is open-source, has strict sandboxing by default, and works with your existing ChatGPT subscription
  • When you're stuck with one tool, try the other -- different models sometimes see different solutions

Shared Instructions: AGENTS.md Strategy

The key to using both tools on the same project is a shared instructions file.

Option 1: AGENTS.md as the Single Source of Truth

Put universal instructions in AGENTS.md and configure both tools to read it:

For Codex CLI: Reads AGENTS.md automatically.

For Claude Code: Add a fallback in CLAUDE.md:

# Project Instructions
See @AGENTS.md for build commands, architecture, and conventions.

# Claude Code-Specific
- Use `/self-review` before creating PRs
- Use subagents for codebase exploration

Option 2: Symlink

ln -s AGENTS.md CLAUDE.md

Simple but you lose the ability to have tool-specific instructions.

Option 3: Separate Files with Shared Core

AGENTS.md          # Universal instructions (both tools read this)
CLAUDE.md          # @AGENTS.md + Claude-specific features

This is the recommended approach -- it gives you cross-tool compatibility while letting you use tool-specific features.

Codex Fallback Configuration

Codex can also be configured to read CLAUDE.md as a fallback in ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md", "COPILOT.md"]

AGENTS.md Discovery

Codex discovers AGENTS.md using a cascading hierarchy:

  1. Home directory (~/.codex/AGENTS.md): Global defaults
  2. Project root → current directory: Walks down, reads one file per directory
  3. Override files: AGENTS.override.md takes priority over AGENTS.md in the same directory

Files are concatenated from root down. The closest file to the edited code wins for conflicting instructions.

See templates/AGENTS.md for a starter template.

Practical Workflows

1. Implement with Claude, Review with Codex

# Session 1: Claude Code implements the feature
claude
> "Implement the CSV export feature described in issue #234"

# Session 2: Codex reviews the implementation
codex "Review the changes on this branch for bugs, security issues, and test coverage"

2. Cross-Validation

Ask both tools to solve the same problem independently, then compare approaches:

# Git worktrees keep both isolated
git worktree add ../feature-claude feature-branch-claude
git worktree add ../feature-codex feature-branch-codex

# Terminal 1
cd ../feature-claude && claude

# Terminal 2
cd ../feature-codex && codex

3. Parallel Agents on Different Tasks

Use git worktrees to run both tools simultaneously on different tasks:

git worktree add ../task-auth auth-refactor
git worktree add ../task-api api-endpoints

# Run Claude Code on auth refactor
cd ../task-auth && claude

# Run Codex on API endpoints
cd ../task-api && codex

4. Spec-First Development

  1. Write the spec/tests with one tool
  2. Implement with the other
  3. The implementation tool can't "cheat" because it didn't write the tests

Codex CLI Quick Reference

Approval & Sandbox Modes

Configured via ~/.codex/config.toml with two independent settings:

  • approval_policy: "untrusted" (prompts before actions) or "on-request" (auto-approves)
  • sandbox_mode: "read-only", "workspace-write", or "danger-full-access"

Interactive UX flags:

codex --auto-edit    # Auto-approve file edits, prompt for commands
codex --full-auto    # No prompts, but sandboxed

Configuration (~/.codex/config.toml)

model = "gpt-5-codex"
approval_policy = "untrusted"
sandbox_mode = "workspace-write"

[profiles.fast]
model = "gpt-5-codex"
approval_policy = "on-request"

Tips

  • Keep AGENTS.md under 150 lines. Same principle as CLAUDE.md -- long files bury the signal.
  • Wrap commands in backticks in both files so agents can copy-paste them.
  • Use git worktrees when running both tools simultaneously to avoid file conflicts.
  • Don't fight the tools. If one tool is struggling with a task, try the other instead of correcting it repeatedly.
  • Update instructions when things change. Both tools rely on accurate build/test commands.

Cost Considerations

Both tools offer subscription-based access and pay-per-token API access. Check current pricing at claude.ai and chatgpt.com as plans and pricing change frequently.

For teams doing heavy AI-assisted development, having access to both gives you flexibility to use whichever is faster, cheaper, or better for the specific task at hand.