Chapter 3: Codex First Steps — Quick Adaptation Guide for Claude Code Users
3.1 For the First-Time Runner
You know the claude command. You're about to type codex for the first time. What's the same, and what's different?
This chapter answers that. Three things to install, three mental model shifts to make, and a command-mapping table to bookmark.
3.2 Install — Three Things
1. Codex CLI
npm install -g @openai/codex
Or with Homebrew:
brew install openai-codex
You need CLI version 0.125 or higher. Check:
codex --version
If lower, run npm update -g @openai/codex [OpenAI, 2026].
2. ~/.codex/config.toml
First run creates a default file, but to use GPT-5.5 you need to set it manually:
# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
Without model, the default is gpt-5.4. model_reasoning_effort options: minimal / low / medium / high / xhigh (availability varies by model). For everyday work, use medium; for complex refactors, use high [OpenAI, 2026].
3. Your First AGENTS.md
Create AGENTS.md at your project root. This minimal version is enough to start:
# Project Rules
## Stack
- Node.js / TypeScript
- Express.js API
- PostgreSQL
## Code Style
- Use ESLint + Prettier (configs in repo)
- TypeScript strict mode
- Functions < 40 lines
## Testing
- Jest for unit tests
- Run `npm test` before any commit
AGENTS.md's job: turn "what you tell Claude each conversation" into "rules Codex follows across all tasks." Write it once; don't repeat it every task [OpenAI, 2026].
3.3 Three Mental Model Shifts
Shift 1: "This conversation" → "Rules file"
In Claude Code: you front-load context at the start of each conversation, or write global config in CLAUDE.md.
In Codex: AGENTS.md plays that role. The difference: AGENTS.md is more structured, can live in subdirectories (applied to their scope), and is read by other AI tools too — Amp, GitHub Copilot, Google Jules all respect the same file [Foundation, 2026].
Shift 2: "Terminal session" → "Task"
In Claude Code: you open a terminal, have a conversation, and the session ends with context lost.
In Codex: you work in tasks. Each task runs on an independent branch and completes as a PR. You can queue multiple tasks simultaneously [DeployHQ, 2026]:
# Single task
codex exec "refactor the auth module to use JWT"
# Multiple tasks at once
codex exec "add input validation to all API endpoints" &
codex exec "write unit tests for UserService" &
Shift 3: "Per-tool permissions" → "Sandbox level"
In Claude Code: each tool prompts for confirmation, or you pre-allow via allowedTools.
In Codex: sandbox_mode sets it once. Start with workspace-write — allows file writes only within the current workspace directory [OpenAI, 2026].
3.4 Command Mapping: Claude Code → Codex
| Task | Claude Code | Codex | Note |
|---|---|---|---|
| Start | claude |
codex |
— |
| Run a task | Type prompt at terminal | codex exec " (alias codex e) |
Non-interactive single run. Interactive mode: bare codex |
| Config file | ~/.claude/CLAUDE.md (global) |
~/.codex/config.toml |
Different format |
| Project rules | CLAUDE.md (project) |
AGENTS.md (project) |
— |
| Subagent definition | .claude/agents/ |
.codex/agents/ |
Different format |
| Skills | .claude/skills/ |
.codex/skills/ |
Similar |
| Model selection | claude --model claude-opus-4-7 |
config.toml: model = "gpt-5.5" |
— |
| Effort setting | Built-in adaptive | config.toml: model_reasoning_model_reasoning_model_reasoning_effort = "xhigh" |
— |
| Code review | /ultrareview |
— (review PR) | Claude Code only |
| Undo | /undo |
Discard branch | Different approach |
Claude Code only: /ultrareview, hooks system (Python/bash scripts), Agent Teams' SendMessage runtime collaboration.
Codex only: branch-per-task automation, TOML-based agents, Linux Foundation AGENTS.md standard compatibility.
3.5 Running Your First Task
With installation done, try it. Practical prompts from Saladi's "Codex 101" [Saladi, 2026]:
Refactor:
codex exec "refactor src/auth.ts — extract token validation into a pure function, add JSDoc"
Add tests:
codex exec "write Jest tests for UserService.createUser(), mock the database"
Fix a bug:
codex exec "fix the race condition in connection pool — see issue #42"
Specific prompts get better results. "Refactor auth" is weaker than "extract the token validation logic in src/auth.ts into a pure function and add JSDoc comments." [Proser, 2026]
3.6 First-Time Friction and Fixes
"What's a PR?": The branch-per-task model feels unfamiliar. When codex exec completes, changes are committed to a new branch. git checkout to inspect, then git merge or git rebase to apply.
"How detailed should my AGENTS.md be?": Start simple. Stack info + code style defaults + test command is enough. Add to AGENTS.md when you notice Codex making recurring mistakes [Code, 2026].
"It's not using GPT-5.5": Check that ~/.codex/config.toml has model = "gpt-5.5". A Pro tier subscription may be required [OpenAI, 2026].
Chapter 5 covers how to write AGENTS.md well and set up subagents. For now, three installs and three mental shifts are enough.
References
- OpenAI, "Codex CLI changelog," 2026. [OpenAI, 2026]
- OpenAI, "Codex config reference," 2026. [OpenAI, 2026]
- OpenAI, "Codex config basic setup," 2026. [OpenAI, 2026]
- OpenAI, "AGENTS.md specification," 2026. [OpenAI, 2026]
- AGENTS.md Open Standard, "60K+ projects," 2026. [Foundation, 2026]
- DeployHQ, "Codex CLI getting started guide," 2026. [DeployHQ, 2026]
- Saladi, "Codex 101: 33 ready-to-use prompts," 2026. [Saladi, 2026]
- TechBytes, "Claude Code command cheatsheet," 2026. [TechBytes, 2026]
- Augment, "How to write a great AGENTS.md," 2026. [Code, 2026]
- Zack Proser, "Codex daily-use review," 2026. [Proser, 2026]