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

This updated edition assumes Codex CLI 0.128.0 or newer. Version 0.128.0, released on 2026-04-30, added /goal, permission profiles, external agent session import, and more explicit multi-agent configuration ^[13]. Check:

codex --version

If lower, run codex update or npm update -g @openai/codex ^[13].

By June 2026, the first choice is not only "install the CLI." It is "which Codex surface should touch this repository first?" Use CLI or App Local for a local Claude Code repository, Worktree for isolated parallel experiments, Cloud for longer remote work, and automation only after the verification loop is routine ^[13].

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"

# Conservative bridge for Claude Code repositories
project_doc_fallback_filenames = ["CLAUDE.md"]
project_doc_max_bytes = 65536

Without model, Codex chooses a default based on your environment and account. model_reasoning_effort options: minimal / low / medium / high / xhigh (availability varies by model). For everyday work, use medium; for complex refactors, use high ^[13].

project_doc_fallback_filenames = ["CLAUDE.md"] is a conservative bridge before migration. Codex prefers AGENTS.md, but in a repo without one it can still read existing CLAUDE.md guidance. This does not mean deleting the Claude harness. It only lets Codex understand the repository while you build a proper shared AGENTS.md.

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 ^[13].

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 ^[5].

Shift 2: "Terminal session" → "Diff-sized task"

In Claude Code: you open a terminal, have a conversation, and the session ends with context lost.

In Codex: you keep tasks small enough to inspect as diffs. The CLI edits your current checkout. The Codex app can run threads in Worktree mode, isolating changes in a Git worktree, and Cloud mode runs long work remotely ^[13]:

# Single task
codex exec "refactor the auth module to use JWT"

# For parallel experiments, prefer Codex app Worktree mode over backgrounded CLI jobs

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 ^[13].

3.4 Command Mapping: Claude Code → Codex

Claude Code only: /ultrareview, Claude-specific remote-control workflows, Agent Teams' SendMessage runtime collaboration.

Codex only: /goal, app Local/Worktree/Cloud modes, TOML-based agents, Linux Foundation AGENTS.md standard compatibility.

3.5 Taking Over a Local GitHub Repo Written with Claude Code

If your projects already live locally, were mostly written with Claude Code, and sync to GitHub, use this sequence. The goal is not a one-shot migration. The goal is to let Codex safely take one small task while the Claude Code setup still works.

1. Start read-only: choose Read Only in /permissions, then ask Codex to inspect only repo structure, .claude/, CLAUDE.md, scripts, and test commands.
2. State the no-delete rule: the first prompt should say not to delete or rename CLAUDE.md, .claude/, hooks, skills, or subagents.
3. Write a handoff file: use HANDOFF.md or docs/codex-handoff-YYYY-MM-DD.md for current state, build commands, risky files, and next tasks.
4. Add a minimal AGENTS.md: copy only universal rules from CLAUDE.md. Leave Claude-specific hooks, slash commands, and memory configuration alone.
5. Run one small task: fix a typo, add one test, or improve one README section. Make it easy to revert.
6. Verify before expanding: inspect /diff, run /review, and run tests before the next task.

First prompt:

This repository already uses a Claude Code harness.
Do not delete or rename CLAUDE.md, .claude/, existing hooks/skills/subagents.
First read the repo structure and Claude Code harness, then propose the smallest
safe AGENTS.md/HANDOFF.md scaffold for Codex. Do not edit files yet.

First edit after approval:

Execute only step 1 of the plan.
Add AGENTS.md, but do not touch any Claude-specific files.
After the change, summarize the diff. Do not run tests yet.

This matters more as the harness gets stronger. Do not use the hardest harness repository as your first experiment. Learn the Codex diff/review/test loop on documentation-heavy repositories or smaller personal projects, then migrate the strongest harness last.

If you use the official "Import other agent setup" flow, put it before step 4, not after step 6. Treat the imported output as a draft classification. Check that CLAUDE.md and .claude/ still exist, that AGENTS.md contains only shared project rules, that settings.json became a conservative config.toml, and that migrated skills, hooks, slash commands, and subagents did not silently gain broader permissions ^[13].

3.6 Running Your First Task

With installation done, try it. Practical prompts from Saladi's "Codex 101" ^[7]:

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." ^[10]

3.7 FAQ for Claude Code Users Trying Codex

"Do I need to remove Claude Code before using Codex?": No. In the first phase, keep CLAUDE.md, .claude/, hooks, skills, and subagents in place. Add Codex as another execution surface. If Codex does not fit, you should be able to return to Claude Code immediately.

"Can I just rename CLAUDE.md to AGENTS.md?": No. CLAUDE.md often mixes Claude-specific instructions with universal project rules. Codex needs the universal rules, build/test commands, and constraints. Leave Claude-specific hooks, slash commands, and memory rules in CLAUDE.md and .claude/. As a temporary bridge you can set project_doc_fallback_filenames = ["CLAUDE.md"], but long term the shared rules should move into AGENTS.md ^[13].

"Does official import mean migration is solved?": No. Import is a scaffolding tool. It can map obvious files and open a follow-up Codex thread for the rest, but it cannot know which old hook encodes a safety policy, which slash command is really a publishing workflow, or which subagent should remain Claude-only. Review the import as a risk register.

"Should I port all .claude/agents, hooks, and skills into Codex formats?": No. A one-to-one port is usually the wrong first move. First write down why each harness piece exists. Rebuild only repeated workflows as Codex skills, subagents, or wrapper scripts. The stronger the Claude Code harness, the more important coexistence is before migration.

"How do I get something like Claude Code Plan Mode?": Use Read Only and explicitly ask for a plan only. After reading the plan, approve one small step with a prompt like "execute only step 1." If you are unsure which model, approval policy, or writable roots are active, run /status ^[13].

"How do I carry over a long Claude Code conversation?": Do not try to move the whole conversation. Compress it into HANDOFF.md: current state, recent decisions, remaining tasks, risky files, and verification commands. Shared links and old sessions are useful references, but the durable handoff unit for Codex is a plain-text file in the repository.

"Should I start with CLI, App, or Cloud?": For a Claude Code user taking over a local repository, start with the CLI or the App's Local mode. You can inspect the current checkout diff and revert locally. App Worktree and Cloud are useful for parallel or long-running tasks, but they add GitHub environments, branches, and PRs to the learning curve ^[13].

"If Codex output is worse than Claude Code, did the migration fail?": No. The default strategy in this book is hybrid. Keep Claude Code for design and interactive judgment when it is stronger. Expand Codex only where small diffs, independent review, sandboxed execution, Worktree, or Cloud work give you a practical advantage.

Chapter 5 covers how to write AGENTS.md well and set up subagents. For now, three rules are enough: preserve the Claude harness, separate planning from small diffs, and leave handoff context in plain-text files.

References

1. OpenAI, "Codex CLI changelog," 2026. [OpenAI, 2026]
2. OpenAI, "Codex config reference," 2026. [OpenAI, 2026]
3. OpenAI, "Codex config basic setup," 2026. [OpenAI, 2026]
4. OpenAI, "AGENTS.md specification," 2026. [OpenAI, 2026]
5. AGENTS.md Open Standard, "60K+ projects," 2026. [Foundation, 2026]
6. DeployHQ, "Codex CLI getting started guide," 2026. [DeployHQ, 2026]
7. Saladi, "Codex 101: 33 ready-to-use prompts," 2026. [Saladi, 2026]
8. TechBytes, "Claude Code command cheatsheet," 2026. [TechBytes, 2026]
9. Augment, "How to write a great AGENTS.md," 2026. [Code, 2026]
10. Zack Proser, "Codex daily-use review," 2026. [Proser, 2026]
11. OpenAI, "Migrate to Codex," 2026. [OpenAI, 2026]
12. OpenAI, "Codex app worktrees," 2026. [OpenAI, 2026]
13. OpenAI, "Codex automations," 2026. [OpenAI, 2026]