OpenAI Codex CLI setup — comparison with Claude Code and Cursor

OpenAI now ships its own coding-agent CLI. Codex CLI is the OpenAI counterpart to Anthropic's Claude Code: built on GPT-5 (or the o1/o3 line) and providing autonomous shell execution, multi-file editing, and a plan-then-execute flow.

This guide sets up Codex CLI and — assuming you already use Claude Code or Cursor — explains which tasks belong to Codex. Starting fresh? Read this alongside Claude Code setup.

TL;DR

1. Node.js 20+ → npm install -g @openai/codex → codex → browser auth
2. Use an OpenAI API key or ChatGPT Plus/Pro subscription
3. Default is approval mode (confirm each command) — --auto-edit / --full-auto raise autonomy
4. Pick a model: --model gpt-5 or o3 (perf vs. cost tradeoff)
5. Role split with Claude Code: see §5

Prerequisites

• Node.js 20+ (mac/dev-toolchain or windows/initial-setup)
• OpenAI account — platform.openai.com or ChatGPT Plus/Pro
• A git-managed project

1. Where Codex CLI fits

This is OpenAI's first-party coding-agent CLI. Unlike third-party tools (Cursor, Aider, Continue) that call OpenAI models, Codex CLI is OpenAI's own standard release.

Similarities to Claude Code

• Runs autonomously in the terminal
• Multi-file editing · shell commands · git integration
• Project context (Codex stores it in a .codex/ directory)
• Plan → execute → verify workflow

Differences

Who's it for

• Already on ChatGPT Plus/Pro — Codex CLI is included
• Already in the OpenAI ecosystem — share keys with Embeddings, DALL·E, etc.
• Want the o3/o4 reasoning advantage for long-thinking tasks
• Need GPT-5 multimodal — images / diagrams as input

2. Install

2.1 npm global

npm install -g @openai/codex
codex --version

If install fails or you hit permission errors, see Claude Code setup §1.1 for the npm-prefix workaround.

2.2 First run

cd ~/projects/my-repo
codex

A browser tab opens for OpenAI login → grant access → back to the CLI. The token is stored in the OS keychain.

2.3 Auth options

Three paths:

# A. ChatGPT Plus/Pro (subscription)
codex auth login --use-chatgpt
 
# B. OpenAI API key
codex auth login --use-api
# → reads OPENAI_API_KEY or prompts
 
# C. Dedicated Codex.com account (beta)
codex auth login --use-codex

Check:

codex auth status
# Account: <email>
# Plan: ChatGPT Plus / API tier 2

3. Autonomy modes

The default is conservative — confirm every shell command and edit. Levels:

Recommendation: stay on the default until you trust the tool, then switch to --auto-edit on familiar repos.

codex --auto-edit
> Refactor the auth module into smaller files

4. Core commands

4.1 Start a session

codex
> Plan: add a password reset feature

Natural-language prompt → Codex proposes a plan → you approve → execution.

4.2 Slash commands

Inside a session:

• /help — command list
• /init — analyze the project and create AGENTS.md
• /model gpt-5 — switch model
• /clear — reset context
• /exit — quit

4.3 AGENTS.md — project guidance

Codex's counterpart to CLAUDE.md. At the project root:

# AGENTS.md
 
## Stack
- Next.js 16 + TypeScript strict
- Supabase + Postgres
- pnpm 11
 
## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
 
## Conventions
- No `any` types
- Routes: kebab-case
- Commits: `[Project] type: description`
 
## Working principles
- Plan before 5+ file changes
- Tests + lint + build must pass before "done"
- Never commit secrets

Auto-loaded on session start. Functionally near-identical to CLAUDE.md.

When using both with Claude Code: either duplicate content between CLAUDE.md and AGENTS.md, or keep only AGENTS.md and reference it from CLAUDE.md via @AGENTS.md.

5. Claude Code vs Codex CLI — task mapping

Both work in the same repo without conflict (both are git-based).

6. Pricing (as of 2026-05)

API pricing (Codex CLI)

Subscriptions

Real spend varies. Rough average for a fullstack dev on API: $30-100/month. Heavy users come out ahead on Pro.

7. Verify

# 1. Installed
codex --version
 
# 2. Auth
codex auth status
 
# 3. Project files
ls -la AGENTS.md .codex/
 
# 4. First command test
echo "create a hello.py that prints 'hello'" | codex --auto-edit

All four passing = setup complete.

8. Troubleshooting

codex: command not found

• Check npm prefix: npm config get prefix's /bin must be on PATH
• Open a fresh terminal and retry

Browser auth won't open

• Headless environment (WSL2/SSH): copy the URL from the CLI into a browser
• Still failing? Delete ~/.codex/auth.json and use codex auth login --use-api with a key

"Insufficient quota"

• Your OpenAI usage cap was hit — platform.openai.com/usage
• The free tier is very restrictive. Tier 1+ (activated after $10 prepay) is the practical minimum

Codex and Claude Code edit the same file simultaneously

• Run one at a time, or have the second wait
• Or add a .codex-lock-style sentinel file to .gitignore to coordinate

--full-auto ran too aggressively

• Ctrl+C immediately
• git reset --hard HEAD or git stash to recover
• Stay on --auto-edit going forward

MCP server won't connect

• As of 2026-05, Codex CLI's MCP support is partial (beta)
• For full MCP integration, use Claude Code

9. What's next

• Claude Code setup — /ai-agents/claude-code
• Cursor setup — /ai-agents/cursor-setup
• Copilot setup — /ai-agents/github-copilot
• Multi-tool workflow — /ai-agents/multi-tool-workflow

References

• Codex CLI on GitHub
• OpenAI Platform
• Claude Code (for comparison)

Changelog

• 2026-05-16: First draft. Codex CLI install + three auth methods + autonomy modes + AGENTS.md + Claude Code comparison table + six troubleshooting cases.