Codex — Quick reference
OpenAI's agentic coding tool — a terminal agent (plus a VS Code/JetBrains extension and a managed cloud) that reads your repo, edits files, runs commands, and iterates on failures until they pass.
At a glance
What it is: a coding agent that reads, edits, and runs code. The CLI is open source and runs locally in your own checkout; the models are OpenAI's.
Where it runs: Terminal CLI, IDE extension (VS Code, Cursor, Windsurf, JetBrains), and the cloud at chatgpt.com/codex — plus GitHub by tagging @codex.
Pricing: Free $0 · Go $8/mo · Plus $20/mo · Pro from $100/mo (5×/20× limits). Or pay per token via the OpenAI API.
Install & first task
Install
macOS/Linux: curl -fsSL https://chatgpt.com/codex/install.sh | sh. Windows PowerShell: irm https://chatgpt.com/codex/install.ps1 | iex. Also npm install -g @openai/codex or brew install --cask codex.
Start
Run codex in your project folder; sign in with your ChatGPT account or an API key. Codex starts in Agent mode — read, run, and write in your working directory.
codex "Read anova_analysis.R, find the bug on line 34, fix it,
and run the script to confirm it works."
Key commands & flags
| Command / flag | What it does |
|---|
codex | Start an interactive terminal (TUI) session. |
codex -m gpt-5.5 | Start with a specific model (--model/-m). |
codex resume --last | Resume a recent session (resume opens a picker). |
codex exec "…" | Run non-interactively (no TUI) — for scripts and CI. |
codex mcp | Manage MCP servers from the CLI. |
-i / --image | Attach a screenshot or design spec to your prompt. |
/model | Switch model or reasoning during a session. |
/permissions | Switch approval mode (Read-only · Auto · Full Access). |
/review · /fork | Built-in slash commands; author your own team shortcuts too. |
Approval & sandbox
Use /permissions to set how much Codex does without asking. The IDE offers the same range, from Chat to Agent (Full Access).
| CLI mode | Behaviour |
|---|
| Read-only | Reads and explains, but asks before editing or running. |
| Auto (default Agent mode) | Reads, runs, and writes in your working directory; steps outside prompt. |
| Full Access | Fewest interruptions — use only when you trust the task. |
Under the hood the approval policy is untrusted, on-request, or never, paired with a sandbox such as workspace-write that scopes edits to your project and protects paths like .git.
Models
| Model | When |
|---|
gpt-5.5 | Default recommendation — strongest for complex coding, computer use, and research. |
gpt-5.4-mini | Faster, lower-cost option for lighter tasks or subagents. |
gpt-5.3-codex-spark | Research preview (ChatGPT Pro) — tuned for near-instant, real-time iteration. |
Project rules: AGENTS.md
Codex reads AGENTS.md before doing any work. Put working agreements in it — "Always run npm test after changing JavaScript", "Run the linter before opening a PR", project conventions.
Files layer by location: a global ~/.codex/AGENTS.md plus per-project files from the Git root down to your current folder; closer files override broader ones. It's an open standard, so the same file guides other agents too.
Go deeper
IDE extension
Install from the VS Code Marketplace (also Cursor, Windsurf, JetBrains). Use open files, selections, and @file references; offload long jobs to the cloud without leaving the editor.
Codex cloud
Delegate background tasks (in parallel) via chatgpt.com/codex, the IDE, or GitHub @codex. Connect GitHub and Codex opens PRs from its work.
MCP
Add STDIO or streaming-HTTP servers in ~/.codex/config.toml or via codex mcp; Codex launches them automatically at session start.
codex exec (CI)
codex exec "summarize repo risks" | tee report.md. Flags: --json, --output-schema, -o <path>, --sandbox workspace-write. Use the official Codex Action in GitHub Actions.
Image input
Paste a screenshot into the composer or pass -i/--image so Codex reads visual details alongside your prompt.
Debug in checkpoints
Paste the error; Codex traces it, proposes a minimal fix, runs the tests, and works migrations in controlled steps — not one giant rewrite.
Pricing & limits
| Plan | Price | What you get |
|---|
| Free | $0 | Explore Codex's capabilities. |
| Go | $8/mo | Lightweight coding tasks. |
| Plus | $20/mo | Several focused coding sessions a week. |
| Pro | from $100/mo | 5× or 20× higher rate limits than Plus. |
| Business | pay-as-you-go | Team usage billed as you go. |
| Enterprise & Edu | custom | Contact sales. |
Usage is metered per model in rolling windows, so heavier models consume your allowance faster. The CLI is free and open source — or skip the subscription and pay per token via the OpenAI API. Verify current numbers at developers.openai.com/codex.
Gotchas & tips
• OpenAI models only — no bring-your-own-model and no local-model option.
• Needs a paid plan or API credits — the Free tier is for exploring, not heavy use.
• Scope your asks — "minimal, high-confidence changes" beats "fix everything"; give it a failing test to verify against.
• Match the approval mode to the risk — Read-only for unfamiliar work, looser modes once you trust the direction.
• Verify current numbers at developers.openai.com/codex — models, plans, and limits change.