Codex CLI Quick Start

What's in this pack

You just ran npm install -g @openai/codex, typed codex, and now you're staring at a Rust-fast prompt wondering what to do next. Codex CLI feels obviously powerful out of the box — but the first hour decides whether you ship something real or close the tab. This pack is the opinionated short list that fixes the first ten problems every new Codex user actually hits.

Codex is the sister product to Claude Code: both are terminal coding agents, both speak the Agent Skills standard, both read a per-repo instruction file. Codex's differentiator is its strong CLI ergonomics, its multi-model support, and its opt-in sandbox for running commands. This pack leans into that: project memory first (AGENTS.md), then the runtime defaults you want to lock down (sandbox), then the marketplaces and helpers, then the bridge back to Claude Code for cross-review.

Who this is for: a developer with a working terminal, a real codebase, an OpenAI API key (or a Codex subscription), and zero patience for browsing every plugin in alphabetical order. By the time you finish step 10, you'll have a Codex install that knows your repo conventions, runs in a real sandbox, talks to MCP servers, and pairs with Claude Code when you want a second opinion on a tricky diff.

Install in this order

1. OpenAI Codex CLI — the agent itself — Start here. npm install -g @openai/codex then codex in any repo. Rust-based, supports the Agent Skills standard, multi-model (GPT-5, o-series, custom), and ships with sandboxed execution. Get a session running before you install anything else — every later pick configures this tool.
2. AGENTS.md — the project memory file — The single highest-leverage file you'll ever write for Codex. Drop a short markdown at repo root: dev-env tips, test commands, PR conventions, things the agent must not touch. Codex reads it on every session. Same idea as CLAUDE.md, but cross-tool: Cursor, Continue, and other agents read AGENTS.md too. 5 minutes to fill in. Saves hours every week.
3. OpenAI Cookbook — Official Prompting Guides — Codex's behavior is heavily shaped by how you ask. The Cookbook has the official prompting guides for GPT-5, Codex, meta-prompting, and the Realtime API. Skim the Codex-specific section once before you start cargo-culting prompt patterns from random tweets.
4. MCP Reference Servers — Official Anthropic Collection — Codex speaks MCP. Connect the filesystem, git, memory, fetch, and sequential-thinking reference servers and you've unlocked the same MCP ecosystem Claude Code uses. These are reference implementations — small, auditable, good starting points before you reach for third-party MCP servers.
5. AIO Sandbox — Secure Agent Runtime in Docker — Decide your sandbox story early. Codex's built-in sandbox is good for file writes; AIO Sandbox containerizes the whole runtime (browser + shell + files + MCP) so a misbehaving session can't touch your laptop. 30-second Docker quick-start on port 8080. Install it before you let Codex auto-run shell commands on real code.
6. Awesome Codex Plugins — Curated Marketplace — A community-curated list of installable plugin bundles. This is your browse-instead-of-grep index for the next six months. Skim once, bookmark the categories that match your stack, come back when you need something specific. (Codex calls these plugins; Claude Code calls them skills — same shape, slightly different packaging.)
7. zcf — Zero-Config Setup for Claude Code & Codex — npx zcf i and it sets up workflows, routing rules, and MCP wiring in minutes. Useful if step 2-5 felt like a lot of manual config. It opinionates so you don't have to think about each toggle. Best on a fresh setup; don't run it on top of careful hand-tuning.
8. Awesome QA Skills — Test Skills for Codex & Claude — A reusable testing-skills bundle that works across Codex, Cursor, and Claude Code. Once Codex starts writing code, you want a test pass that runs the same way every time. Drop these in and Codex stops shipping subtle regressions.
9. Codex Plugin for Claude Code — OpenAI Cross-Review — The bridge. Install this inside Claude Code and you can hand a diff to Codex for an adversarial review, or delegate a sub-task. Two coding agents on the same problem catch different bugs. Pairs especially well for tricky refactors where one model gets stuck.
10. Cursor vs Claude Code vs Codex — 2026 Comparison — Read this last. After you've installed Codex and the bridge to Claude Code, this primer tells you which agent to reach for in which situation: context window, MCP support, pricing, sandbox model, agent ergonomics. It's not about picking a winner — it's about knowing the tradeoffs you just opted into.

How they fit together

Codex CLI (#1)
   │
   └─ the agent, reads everything below
         │
AGENTS.md (#2)
   │
   └─ per-repo memory, loaded every session
         │
OpenAI Cookbook (#3)
   │
   └─ how to write prompts Codex actually follows
         │
MCP Reference Servers (#4)
   │
   ├─ filesystem, git, memory, fetch
   └─ structured access to your environment
         │
AIO Sandbox (#5)
   │
   └─ containerized runtime so shell commands
      can't escape into your dotfiles
         │
Marketplaces: Awesome Codex Plugins (#6)
   │
   └─ browse instead of guess
         │
zcf (#7)  — optional zero-config helper
   │
   └─ wires #2/#4/#6 if you skipped manual setup
         │
QA Skills (#8)
   │
   └─ post-edit testing so Codex stops shipping regressions
         │
Codex Plugin in Claude Code (#9)
   │
   └─ cross-review: Codex critiques Claude's diff or vice versa
         │
Cursor/Claude Code/Codex comparison (#10)
   │
   └─ when to reach for which agent

The Codex + AGENTS.md + AIO Sandbox trio is the load-bearing wall. Everything else is decoration without those three. If you only have 10 minutes, install #1, write a 20-line #2, and decide on #5 before you let Codex run a single shell command. The marketplace browsing (#6, #8) and the cross-product bridge (#9) are upgrades for week two.

Tradeoffs you'll hit

• Codex CLI vs Claude Code — Both are terminal coding agents, both speak Agent Skills, both read a per-repo instruction file. Codex leans on OpenAI models (GPT-5, o-series) and has the cleaner sandbox story today; Claude Code leans on Anthropic models and has the deeper subagent + hooks ecosystem. Most serious users install both — Codex for raw speed and OpenAI-specific tasks, Claude Code for orchestrated long sessions — and use the cross-review plugin (#9) to play them against each other.
• AGENTS.md vs CLAUDE.md — Same idea, different conventions. AGENTS.md is the cross-tool open format (Codex, Cursor, Continue, others read it). CLAUDE.md is Claude Code's own file. If you only run one agent, use that agent's native file. If you run both, write AGENTS.md and have CLAUDE.md @import it — single source of truth.
• Codex built-in sandbox vs AIO Sandbox (#5) — Codex's built-in sandbox protects file writes and gates network access; it's process-level. AIO Sandbox wraps the entire runtime in a container — browser, shell, files, MCP. Built-in is enough for solo tinkering on your own code. AIO is what you want before you let an agent run arbitrary shell on a real machine — especially on a work laptop or production-adjacent host.
• Reference MCP servers (#4) vs third-party MCP — Reference servers are Anthropic-authored, small, auditable, and have boring scopes (filesystem, git, fetch). Third-party MCP servers are often more capable but vary wildly in code quality. Always start with reference servers — they're the floor that everything else gets compared against.
• zcf (#7) vs hand-tuning — zcf gets you 80% of a sensible setup in 60 seconds. The other 20% is the part that matters to your repo: which MCP servers you want, what AGENTS.md should actually say, which sandbox model fits your security posture. Run zcf for the scaffolding, then hand-edit the parts that survive a project review.

Common pitfalls

• Skipping AGENTS.md because Codex "seems smart enough" — Without it, every session re-learns your conventions. The agent will keep using tabs in a spaces repo, run pytest in a project that uses uv run pytest, and edit files you told three previous sessions not to touch. 30 lines of markdown solves it permanently.
• Running Codex outside a sandbox on a work machine — The default is reasonable, but "reasonable" is not "safe enough for a misconfigured prompt at 2am." AIO Sandbox (#5) takes 30 seconds and removes a whole class of bad days.
• Treating AGENTS.md as a long doc — 30–80 lines is the sweet spot. People paste their architecture doc in and burn thousands of tokens every turn. Keep it terse: stack, commands, conventions, hard NOs. Move long-form architecture into linked docs that the agent can read on demand.
• Installing every plugin from the marketplace (#6) at once — More plugins = more context Codex has to scan to route correctly = slower and dumber routing. Start with the four or five that match your stack. Add only when you hit a real workflow gap.
• Ignoring the cross-review plugin (#9) until you're stuck — The right time to install it is before you need it. The wrong time is at hour three of a debugging session when Codex and Claude Code are both spinning on the same wrong hypothesis and you have to context-switch to install something just to break the loop.