Codex CLI guide: install, ChatGPT plans, sandbox modes and features
Codex CLI is OpenAI's terminal coding agent. OpenAI released it as open source in April 2025, rewrote it from TypeScript into Rust later that year, and has shipped updates at a fast pace since. The repository has around 130,000 GitHub stars, and the npm package is past version 0.160.
It shares the Codex name with OpenAI's cloud agent and IDE extension, and all three draw on the same ChatGPT plan limits. This page covers the CLI: how to install it, what your plan includes, how its sandbox works and when another agent fits better.
How it works
You start Codex in a project folder with codex. It opens a full-screen terminal interface. You type a task, such as "find why the date parser fails on leap years and fix it", and Codex:
- Searches and reads the relevant files.
- Plans the change and shows its reasoning as it goes.
- Edits files and runs commands such as tests and linters inside a sandbox.
- Reads the output and keeps working until the task is done or it needs you.
Every command and edit appears in the session. Depending on your approval policy, Codex either asks before acting or acts within the sandbox and reports back.
Installing Codex CLI
| System | Command |
|---|---|
| macOS, Linux | curl -fsSL https://chatgpt.com/codex/install.sh | sh |
| Windows (PowerShell) | irm https://chatgpt.com/codex/install.ps1 | iex |
| npm | npm i -g @openai/codex |
| Homebrew | brew install --cask codex |
Supported systems are macOS 12 or later, Ubuntu 20.04 or later, Debian 10 or later, and Windows 11 through WSL2. OpenAI lists 4 GB of RAM as the minimum and recommends 8 GB.
On first run, Codex asks you to sign in with your ChatGPT account or an OpenAI API key.
Plans and limits
Codex is included in every ChatGPT plan:
| Plan | Price (US) | Codex CLI |
|---|---|---|
| Free | $0 | Included, lowest limits |
| Go | $8/month | Included, low limits |
| Plus | $20/month | Included |
| Pro | From $100/month | Higher limits |
| Business, Enterprise, Edu | Per seat | Included, admin controls |
| API key | Pay per token | No plan limits, billed per use |
Free and Go plans can use Codex locally in the CLI and IDE extension, but not Codex cloud tasks. Limits reset on rolling windows. The /status command shows your current usage. OpenAI changes these limits more often than its prices, so check the Help Center page linked below for the current numbers.
Sandbox and approvals
Codex separates two questions: what commands can touch, and when Codex has to ask you.
Sandbox modes decide what a command can affect:
- read-only: Codex can read files and run commands that do not change anything.
- workspace-write: Codex can edit files inside the project folder. Network access is off by default and can be turned on in config.
- danger-full-access: no limits. Use this only in a container or a throwaway machine.
On macOS the sandbox uses Apple's Seatbelt, and on Linux it uses the kernel's own sandboxing features. That means the limits are enforced by the operating system, not only by the model's judgment.
Approval policies decide when Codex stops for you. on-request lets the model ask when it wants to go beyond the sandbox. never means it never asks, which suits CI. An older "untrusted" policy was removed in version 0.149. The --yolo flag combines full access with no approvals and exists for isolated environments only.
Change both inside a session with /permissions, or set defaults in ~/.codex/config.toml.
Features
AGENTS.md. Codex reads an AGENTS.md file from your repository and home folder as standing instructions. Run /init to generate a first draft. The format is shared by many agents, so it is a good place to keep build commands and code style rules.
Model choice. /model switches between the OpenAI models your plan allows and sets reasoning effort.
Code review. /review asks Codex to review your working changes or a branch diff and report problems before you commit. There is also an automatic reviewer that can check Codex's own changes.
Non-interactive mode. codex exec "task" runs without the interface and prints results, with JSON output for scripts. Use it in CI, cron jobs or git hooks.
MCP. Codex connects to Model Context Protocol servers configured in config.toml, and can itself run as an MCP server for other agents.
Worktrees and parallel agents. Codex can work in separate git worktrees so several tasks run in parallel without stepping on each other, and it can split work across multiple agents.
Images and voice. You can paste screenshots or diagrams into the prompt, and voice input is available in the interface.
Where Codex CLI works well
- Developers who already pay for ChatGPT and want an agent at no extra cost.
- Students and hobbyists who need a capable agent on a free plan.
- Teams that want the code of their agent to be open and auditable.
- Unattended work in CI, where the OS-level sandbox matters.
- Code review before pushing, using
/review.
Limits and risks
OpenAI models only. Codex CLI is built for OpenAI's models. Community forks and config options point it at other providers, but that is not the main path. For a multi-provider agent, see OpenCode or Aider.
Native Windows support is limited. OpenAI's supported path on Windows is WSL2.
Plan limits on Free and Go are low. A long session can use up the allowance. Heavy users move to Plus, Pro or API billing.
Full access is risky. The sandbox protects you only when it is on. Do not run --yolo or danger-full-access on a machine with credentials or data you care about.
Fast release pace. Commands, flags and config keys change between versions. Pin a version in CI and read the changelog before upgrading.
Codex CLI compared with other terminal agents
| Tool | Models | License | Cost to start | Sandbox |
|---|---|---|---|---|
| Codex CLI | OpenAI | Apache 2.0 | ChatGPT Free | OS-level, on by default |
| Claude Code | Claude | Proprietary | Claude Pro, $20/month | Permission rules, optional sandbox |
| Gemini CLI | Gemini | Apache 2.0 | Paid API or Code Assist | Optional container or Seatbelt |
| OpenCode | 75+ providers | MIT | Free tool, pay for model | Permission rules |
| Aider | Most providers | Apache 2.0 | Free tool, pay for model | Git commits as undo |
Choose Codex CLI if you have a ChatGPT account, want an open-source agent from a major lab, or need a sandbox enforced by the operating system. Choose Claude Code if you prefer Claude models and want its hooks and plugin system. For all the options, see the terminal tools guide.
Frequently asked questions
Is Codex CLI free?
The tool is free and open source. OpenAI includes Codex in every ChatGPT plan, including Free and Go, so you can sign in with a free ChatGPT account and use it within that plan's limits. Plus, Pro, Business and Enterprise plans raise the limits. Codex cloud tasks, which run in OpenAI's environment rather than on your machine, are not available on Free or Go. You can also sign in with an API key and pay per token instead of using plan limits.
How do I install Codex CLI?
On macOS or Linux, run curl -fsSL https://chatgpt.com/codex/install.sh | sh. On Windows PowerShell, run irm https://chatgpt.com/codex/install.ps1 | iex. You can also use npm i -g @openai/codex or brew install --cask codex. Codex supports macOS 12 or later, Ubuntu 20.04 or later, Debian 10 or later and Windows 11 through WSL2. Run codex in a project folder and sign in with ChatGPT or an API key.
What do the sandbox modes do?
They limit what commands Codex runs can affect. Read-only lets Codex read files but not change them. Workspace-write lets it edit files inside the project folder, with network access off by default. Danger-full-access removes the limits and is meant for isolated machines or containers. Separately, the approval policy decides when Codex stops to ask you, such as on-request or never. Change both with the /permissions command.
What is AGENTS.md?
AGENTS.md is a markdown file of instructions that Codex reads at the start of each session, covering things such as how to build and test the project, code style and areas to avoid. Run /init to have Codex draft one for your repository. The format is shared by several agents, including OpenCode, Pi and others, so one file can serve many tools.
Can I use Codex CLI in scripts and CI?
Yes. codex exec runs a task non-interactively and prints the result, so you can call it from shell scripts, cron jobs or a CI pipeline. OpenAI also publishes a GitHub Action. For unattended runs, set the sandbox and approval policy explicitly, and use API key authentication or a service account rather than a personal login.
How does Codex CLI compare with Claude Code?
Both are terminal agents that read code, make multi-file edits and run commands. Codex CLI is open source, runs OpenAI models, ships as a Rust binary and is included on ChatGPT Free. Claude Code is proprietary, runs Claude models and needs a paid Claude plan or API billing. Claude Code has a larger set of hooks and plugins. Codex CLI has an operating system sandbox on by default. Many developers keep both and use whichever subscription they already pay for.