Codex CLI: OpenAI's Coding Agent for Your Terminal
Codex CLI: OpenAI's terminal coding agent and when to use it
Updated
Codex CLI is OpenAI's open-source coding agent that reads your repository, edits files and runs commands from your terminal. This page is Step 12 of 12 in the Vibe Coding guide. You leave with a working install, a safe approval setting, a context file for Bookly, and a clear way to choose between Codex and Claude Code.
Codex comes in five surfaces: the terminal CLI, cloud tasks, an IDE extension, the ChatGPT desktop app and an SDK. This page starts with the CLI, then covers cloud tasks, the desktop app, current plans and usage limits, and a side-by-side with Claude Code. Bookly, the salon booking app from this guide, is the running example throughout.
Codex follows the same method as the rest of the guide: a PRD and acceptance checks before the first task, one branch per task, and tests that gate the merge. Each of those topics has its own page, and this page links to them where Codex changes the details.
Related guides: Claude Cowork, Claude Code deep dive, vibe coding workflow.
Part 1: One Agent, Five Surfaces
The short version
Codex is OpenAI's coding agent. It reads your repository, edits files, runs commands, and proposes changes as diffs or pull requests. The CLI launched in April 2025. The cloud agent followed on May 16, 2025. By mid-2026 it runs on five surfaces. You pick the surface per task. Local messages and cloud chats share one usage allowance.
Terminal CLI
Run codex for an interactive terminal agent. The CLI is open source under Apache-2.0. Best for hands-on local work where you watch each step and steer.
Cloud / Web
Delegate tasks to Codex cloud environments. Tasks run in the background, in parallel, and come back as reviewable diffs or pull requests. Start one from the web, mobile, the desktop app or the CLI with codex cloud. Connect GitHub to tag @codex in pull-request comments.
IDE extension
The same agent inside VS Code and VS Code Insiders, Cursor and Windsurf. JetBrains IDEs have their own Codex integration: open AI Chat and select Codex. Xcode has its own integration too.
ChatGPT desktop app
Since July 2026, Codex is a mode of the ChatGPT desktop app, next to Chat and Work. Part 4 covers it.
SDK & headless
codex exec runs one task and exits, so it fits scripts and CI. Official SDKs embed the agent in your own tools: @openai/codex-sdk for TypeScript and openai-codex for Python.
Models: the GPT-6 family
Codex runs on the GPT-6 family. GPT-6 Astra is the most capable model. GPT-6.1 Sol is the default in config.toml. GPT-6.1 Terra reached Work and Codex on October 26, 2026.
| Model | CLI flag | Use it for | Plan access | API $ per 1M tokens, in / out |
|---|---|---|---|---|
| GPT-6 Astra | codex -m gpt-6-astra | Most capable model for complex work across code, apps, and research | Paid plans (availability varies) | $10 / $50 |
| GPT-6.1 Sol | codex -m gpt-6.1-sol | Near-Astra performance for complex work at a lower cost than Astra. The default in config.toml. | Plus and above | $2 / $10 |
| GPT-6.1 Terra | codex -m gpt-6.1-terra | Fast, efficient model for clear writing, visual understanding, and computer use. Needs CLI 0.159.0 or later. | Plus and above (added October 26, 2026) | $1 / $5 |
| GPT-6 Luna | codex -m gpt-6-luna | Most efficient model for focused, high-volume tasks | Free, Go and paid plans | $0.10 / $0.50 |
All four models have a 1.05M-token context window and up to 128K output tokens in the API.
Pick the tier first. Raise reasoning effort only when a task needs deeper reasoning. Effort levels now include Max and Ultra, and GPT-6 Luna supports effort up to Max, not Ultra. Use /model with inline arguments to set the model, effort and speed in one command (CLI 0.164.0).
A practical default: start with GPT-6.1 Terra on a paid plan for everyday edits, move to GPT-6.1 Sol when a task keeps failing, and use GPT-6 Luna for bulk mechanical changes. Model retirements are covered in Part 7.
Part 2: Codex CLI: install, sign in and run your first task
Install and sign in
Install with npm, Homebrew or the install script on macOS and Linux. On Windows, use the PowerShell installer, or run Codex in WSL2. Sign in with your ChatGPT account or an API key.
Codex works on macOS, Linux, and Windows (native or WSL2). A ChatGPT sign-in uses your plan's included usage. An API key bills at API rates. Run /init in the project to create an AGENTS.md. If the CLI cannot reach the service, check your network and proxy settings in the CLI docs.
Recent CLI versions
Check the changelog when a flag or a command in this guide does not match your install.
- CLI 0.166.0 (October 29, 2026).
- CLI 0.165.0 (October 27, 2026): a built-in Google Cloud Vertex AI provider (model_provider = "gcp"), Memory v2 as the default for new profiles, and reasoning effort that can change mid-conversation.
- CLI 0.164.0 (October 23, 2026): /presets with 10 slots, and inline arguments for /model and /permissions.
- CLI 0.163.0 (October 15, 2026): network proxy security fixes, resumed threads restore their permissions, the leader key defaults to Ctrl+X, and voice mute moved to F9.
Terra needs CLI 0.159.0 or later.
Approval modes: the safety dial
Three modes, switched with /permissions. Each mode sets a sandbox mode and an approval policy in config.
Read-only
Sandbox mode read-only. Codex can read and analyze the repository, but the sandbox blocks writes. Start here on a repo you do not know yet.
Auto (default)
Sandbox mode workspace-write with on-request approvals. Codex edits files and runs commands inside the workspace. The .git, .agents, .codex and .aws folders stay read-only. Version-controlled folders get Auto by default. Other folders get read-only.
Full Access (not recommended)
Sandbox mode danger-full-access. No sandbox limits on the machine. Use it only in a disposable VM or container.
Set approvals_reviewer to auto_review to route eligible approval requests to a reviewer agent. Protected folders stay read-only even inside writable roots.
Retired names: older tutorials use Suggest, Auto-edit and Full-auto. Those names are no longer documented, and neither is the --full-auto flag. The untrusted approval policy is retired too. To keep that behavior, set trust_level = "untrusted" for the project in ~/.codex/config.toml.
Session commands and top-level commands
The interactive TUI works like an editor more than a chat window. These are the commands worth memorizing first.
/initCreate an AGENTS.md file for the project/statusShow the session configuration/permissionsSet what Codex may do: Read-only, Auto or Full Access. Takes an inline profile argument since CLI 0.164.0./modelSwitch model, effort and speed. Takes inline arguments since CLI 0.164.0./reviewReview uncommitted changes, a commit or a base branch, without changing the working tree/presetsPreset slots, 10 in total (CLI 0.164.0)codex resumeContinue an earlier sessioncodex execRun one task and exitcodex cloudSubmit work to a cloud environment and apply the results locallycodex mcpAdd and manage MCP serverscodex --searchTurn on live web searchcodex --imageAttach an imagecodex completionPrint shell completioncodex mcp adds and manages MCP servers, and skills, plugins and subagents also work in the CLI.
AGENTS.md: your repo's rules for the agent
Codex reads a global file in ~/.codex, then the files from the project root down to your folder. The file closer to your folder wins on conflicts. Put setup, test and style rules in it.
This is the file for Bookly, the salon booking app. It is an illustration: it tells the agent how to run tests and what a booking may never do.
Keep the file under the 32 KiB default limit (see Part 7), and review changes to it in pull requests, because every run follows it. The context file idea is on the workflow page.
Headless: codex exec
codex exec runs one task and exits, so it fits scripts and CI.
In CI, set CODEX_API_KEY on the single exec step. Do not set it at job level in a workflow that runs repository code. Secret handling beyond CI is on the security page.
Part 3: Codex cloud: run tasks in the background
How a cloud task runs
Each cloud task gets its own workspace, and it keeps working while your computer is asleep. Several tasks can start from one published environment, and each keeps its own state.
- The environment starts from the universal image.
- The repo checks out, and the setup script runs with internet access.
- The agent runs with internet off by default. Allow package-manager domains or extra domains in the environment network settings to change that.
- Secrets reach only the setup script, and they are removed before the agent runs.
- Container state is cached for up to 12 hours, so follow-up tasks start faster.
- Environments run behind an HTTP/HTTPS proxy.
- A new environment must show "Environment published" before tasks start.
- Cloud tasks draw from the same usage allowance as local messages, and they can use more of it.
Bookly in the cloud: the mechanical backlog suits cloud tasks. Examples are a dependency bump, a missing test for cancelled bookings, or a lint sweep. Each task comes back as a diff or pull request for you to review.
From the terminal: codex cloud submits work to a cloud environment and applies the results locally. Use it when you start a cloud task from the CLI.
Hosting, monitoring and cost controls after a task ships are on the deployment page.
GitHub-native workflow
Connect a repo, then comment @codex on a pull request. @codex review runs a review. Any other @codex mention starts a legacy cloud chat with the pull request as context.
- Turn on automatic reviews in your Personal preferences.
- GitHub reviews flag only P0 and P1 issues.
- Put review rules under a
## Code Review Rulesheading in AGENTS.md. Use the root file for repo-wide rules and nested files for one service.
CI automation with the official Action
openai/codex-action@v1 is the GitHub Action for Codex. By default, only users with write access can trigger the run. The safety-strategy input defaults to drop-sudo, and allow-users and allow-bots control who can trigger it.
The official example reads an OPENAI_API_KEY secret and posts the result as a pull-request comment. Windows runners need safety-strategy set to unsafe. The sandbox input accepts workspace-write, read-only or danger-full-access.
Part 4: Codex app: the ChatGPT desktop app with Codex mode
One desktop app, three modes
In July 2026, the standalone Codex app became part of the ChatGPT desktop app. The app has three modes: Chat, Work and Codex. This part covers Codex mode.
Chat, Work and Codex sit in one app. Codex mode runs the coding agent on your repository.
macOS and Windows. The docs include a Linux install guide. iOS is also available.
Local messages and cloud chats share one allowance. The plan limits in Part 5 apply.
Where to start: the quickstart recommends the desktop app. Use the CLI when you want scripts with codex exec, or a terminal-first workflow.
Part 5: Codex pricing: plans, usage limits and credits
Plans
Codex is included in every ChatGPT plan, including Free. Plus and Business meter usage in a 5-hour rolling window. Pro has no five-hour limit at present, though weekly limits may apply.
| Plan | Price | What you get |
|---|---|---|
| Free | $0 | Codex with GPT-6 Luna at Standard speed in the desktop app, subject to rollout |
| Go | $8 per month | GPT-6 Luna, for lightweight coding tasks |
| Plus | $20 per month | GPT-6.1 Sol, GPT-6.1 Terra (since October 26, 2026) and GPT-6 Luna, with web, CLI, IDE and iOS |
| Pro | $100, $200 or $500 per month | No five-hour limit at present, though weekly limits may apply. Ultrafast mode is on the $500 plan. |
| Business | $20 per user per month billed annually, or $25 per user per month billed monthly | Minimum of two users |
| Enterprise and Edu | Contact sales | Ultrafast mode for eligible accounts |
How many local messages fit in 5 hours on Plus
These are estimates for Plus and Standard Business, not fixed limits. Each row shows local messages per 5-hour window.
| Model | Local messages per 5 hours (estimate) |
|---|---|
| GPT-6 Astra | 5 to 45 |
| GPT-6.1 Sol | 15 to 160 |
| GPT-6.1 Terra | 35 to 285 |
| GPT-6 Luna | 350 to 3,000 |
Cloud tasks may use more of your allowance than local messages. The estimates shift with model choice, so a long task on GPT-6 Astra uses far more of the window than the same task on GPT-6 Luna.
Credits and speed modes
Credit rates per 1M tokens at Standard speed. Use them to estimate the cost of a task on a credit-based plan.
| Model | Input credits | Cached input credits | Output credits |
|---|---|---|---|
| GPT-6 Astra | 250 | 25 | 1,250 |
| GPT-6.1 Sol | 50 | 2.5 | 250 |
| GPT-6.1 Terra | 25 | 1.25 | 125 |
| GPT-6 Luna | 2.5 | 0.25 | 12.5 |
- Fast mode uses 2.5 times the subscription usage, and 2 times the credits.
- Ultrafast mode on GPT-6 Astra and GPT-6.1 Sol uses 8 times the subscription usage, and 6 times the credits.
- Ultrafast mode is on the $500 Pro plan and on eligible Enterprise and Edu accounts.
API-key sessions
Codex used through the CLI, the SDK or the IDE extension with an API key bills at API rates.
An API-key session has no cloud features, such as GitHub review or Slack. The API prices per 1M tokens are in the models table in Part 1. Pick the API key when a script or CI job needs a key, and keep ChatGPT sign-in for interactive work on a plan.
Part 6: How to use Codex: a first-hour workflow
A sane default workflow
Five steps, in the order that keeps you out of trouble.
Write AGENTS.md first. Setup, test and style rules. Write them once, so every run starts with your repo's rules. The context file idea is covered on the workflow page.
Checkpoint with Git before and after each task. The CLI guidance is to create Git checkpoints before and after a task. Branch and rollback habits are on the workflow page.
Start in Auto mode locally. Pair on the risky, ambiguous work in the CLI or IDE, where you watch every diff.
Delegate the mechanical backlog to the cloud. Dependency bumps, missing tests and lint sweeps come back as reviewable diffs or pull requests.
Gate everything with tests in CI. The rules on the TDD page apply to agent output as much as to human code. If the suite fails, nothing merges.
The branch and rollback steps are on the workflow page, and the test rules are on the TDD page.
A good task prompt: goal, context, constraints, done-when
A task prompt states four things. This is an illustration of the steps for Bookly, not a recorded run.
The steps Codex would take:
- Reads AGENTS.md from the project root and from the folder it works in.
- Finds bookSlot and the existing booking tests in tests/.
- Adds the test for a second booking on the same slot, if it is missing, and runs npm test to see it fail.
- Changes bookSlot until that test passes and the rest of npm test stays green.
- Shows the diff for your review.
Run /review on the uncommitted changes, then read the diff yourself. Commit on the feature branch yourself. Git checkpoints before and after the task make a rollback easy.
Part 7: Gotchas that bite real users
Five traps, and the fix for each
A retired model in ~/.codex/config.toml makes runs fail or switch. gpt-5.4 and gpt-5.4-mini left Codex with ChatGPT sign-in on August 31, 2026. GPT-5.3-Codex-Spark left on September 14, 2026, and GPT-5.5 on October 14, 2026. When behavior changes, check the model line first.
Credits follow the tokens a model reads and writes. A large refactor costs more of your window than a one-line fix. The credit rates are in Part 5. Watch the usage meter on big tasks, and split large work into smaller tasks.
The default combined limit is 32 KiB. Keep the file short, and move long reference material into docs that AGENTS.md links to.
Setup scripts can reach the internet. The agent phase starts with network access off, and secrets are removed before the agent runs. That default is safe, but a cloud task cannot install a new dependency mid-run unless the setup script installs it first. For secret handling in general, see the security page.
--dangerously-bypass-approvals-and-sandbox (alias --yolo) disables approvals and the sandbox. The docs label it Elevated Risk. It has one sane home: an isolated, disposable environment that holds nothing you would miss. Never use it on your laptop, and never with real credentials in reach.
Part 8: Codex vs Claude Code: which one to use for which task
Claude Code vs Codex: pricing, models and workflow side by side
Read this as a routing guide, not a scoreboard. Both tools run real coding work in a repository.
| Dimension | OpenAI Codex | Claude Code and Cowork |
|---|---|---|
| Vendor and models | OpenAI: GPT-6 family (Astra, GPT-6.1 Sol, GPT-6.1 Terra, GPT-6 Luna) | Anthropic: Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5 |
| Repo instructions | AGENTS.md, read from the project root down to your folder. 32 KiB default limit. | CLAUDE.md in the working folder and each parent, plus subfolder files on demand. Reads AGENTS.md when no CLAUDE.md exists in or above the working folder. Recommended size under 200 lines per file. |
| Cloud delegation | Cloud tasks in their own workspace, @codex on pull requests, codex cloud from the CLI | Cloud sessions on Anthropic-managed VMs. claude --cloud starts one, claude --teleport pulls it back, and /autofix-pr handles PRs. Needs a claude.ai login. Remote Control is separate: it steers a local session from a phone or browser. |
| Extension layer | MCP servers (codex mcp), skills and plugins, subagents, SDKs, GitHub Action | Skills, hooks, subagents, plugins and MCP. Agent teams are experimental and off by default. |
| Headless and CI | codex exec, and openai/codex-action@v1 | claude -p runs once and exits. Official GitHub Actions and GitLab CI/CD integrations. Flags include --max-turns, --max-budget-usd and --output-format json. |
| Permission model | Read-only, Auto and Full Access modes. Sandbox modes read-only, workspace-write and danger-full-access. | Six permission modes: default, acceptEdits, plan, auto, dontAsk and bypassPermissions. New terminal and VS Code sessions start in auto mode. The sandbox is opt-in through /sandbox on macOS, Linux and WSL2. |
| Non-code sibling | Not covered in this guide | Claude Cowork: the same agentic approach as Claude Code, built for non-coding knowledge work |
| Entry price | Free ($0) and Go ($8 per month) include Codex. Plus is $20 per month. | Pro is $20 per month billed monthly, or $17 per month billed annually ($200 up front). Max from $100 per month. Claude Code is in every paid plan. |
Which one for which task
Pick by the job, and test both on the same task.
- Work you start and leave running: Codex cloud tasks, or Claude Code cloud sessions. Both keep working when your laptop is closed.
- Pull-request review: Codex with
@codex, or Claude Code with its GitHub integration and automatic PR review. - Local depth with hooks and skills: the Claude Code page covers them in depth.
- Work that is not code: Claude Cowork.
No winner here: no neutral benchmark compares the two on the newest models, so this guide does not name one. Run one Bookly task in each tool on its own branch, then compare the diffs, the test results and the usage meter. Tool-by-tool plans are on the tools page.
Next step
Start your own project with the PRD builder, and use the PRD to write your first tasks for Codex. To review the first steps, go back to getting started.
Common Questions
Is Codex CLI free?
The Codex CLI is open source under Apache-2.0, but using it needs a ChatGPT plan or an API key. Plus at $20 a month includes the CLI, web, IDE and iOS with GPT-6.1 Sol and GPT-6 Luna. The Free and Go plans include Codex with GPT-6 Luna in the desktop app, subject to rollout. API-key use is billed at API rates.
How do I install Codex CLI on Windows?
Open a new PowerShell window and run the official install script: irm https://chatgpt.com/codex/install.ps1 | iex, with PowerShell's execution policy set to ByPass for that command. You can also install it with npm install -g @openai/codex. Codex works on Windows natively or in WSL2. Then run codex in your project folder and sign in with your ChatGPT account.
How do I update Codex CLI?
Update it the same way you installed it. On a Mac with Homebrew, run brew upgrade --cask codex. If you installed with npm, run npm install -g @openai/codex again to get the latest release. If a pinned model in ~/.codex/config.toml was retired, update that setting too, or runs will fail or switch models.
Codex CLI vs Codex app: what is the difference?
The CLI runs in your terminal and works on the repository in your current folder. The app is the ChatGPT desktop app, which has Chat, Work and Codex modes on macOS, Windows and Linux. Both use the same plan, and local work and cloud tasks share one usage allowance, so you can move between them without paying twice.
Is Codex better than Claude Code?
There is no neutral benchmark that settles it for the current models. Choose by plan, models and workflow: Codex comes with ChatGPT plans and reads AGENTS.md, and Claude Code comes with Claude plans and reads CLAUDE.md. Both support hooks, plan mode and cloud or background tasks. Try the same Bookly task in each and compare the diffs.
Which Codex models are retired, and what should I switch to?
OpenAI retired gpt-5.4 and gpt-5.4-mini from Codex with ChatGPT sign-in on August 31, 2026. It retired GPT-5.3-Codex-Spark on September 14, 2026, and GPT-5.5 on October 14, 2026. The gpt-5.2 and gpt-5.3-codex models are deprecated. Switch to gpt-6.1-sol on Plus and above, or to gpt-6-luna on Free and Go, and check the model line in ~/.codex/config.toml. API-key sessions were not affected by the GPT-5.5 retirement.