OpenAI Codex

Codex is OpenAI's coding agent. It reads a repository, plans a change, edits files, runs the commands needed to check its work, and reports back — in a terminal, in VS Code, in a browser, or on a phone. The terminal client, Codex CLI, is the part most developers mean when they say "Codex", and it is open source under Apache-2.0.

Overview

Codex began in April 2025 as a small open-source terminal client and has since grown into OpenAI's full agentic-coding surface. The same agent now runs in five places: the CLI, a VS Code extension, the Codex web app, an iOS app, and — since June 2026 — Amazon Bedrock.

What separates Codex from an autocomplete tool is that it executes. It runs your test suite, reads the failure, and tries again. That is also what makes the sandbox the most important part of the product rather than a footnote: an agent with a shell is only as safe as the box you put it in.

The model underneath is the GPT-5.6 family, generally available since 9 July 2026. Codex defaults to Sol, the frontier tier, at medium reasoning effort, and lets you drop to Terra or Luna mid-session when the task does not justify the cost.

Codex is the closest direct competitor to Claude Code, and the two have converged on nearly the same shape — terminal-first, MCP-native, sandboxed, driven by a Markdown instructions file. The meaningful choice between them is which model you want on your codebase.

Key Features

• Three-tier sandbox. workspace-write is the default: read anything, edit inside the workspace, run commands, no network. read-only answers questions without touching disk. danger-full-access removes sandboxing entirely and is named to discourage you.
• Four approval policies. on-request prompts before escalations, untrusted auto-runs only known-safe reads, never runs autonomously inside whatever sandbox is configured, and auto_review routes approval requests through a reviewer agent instead of interrupting you.
• AGENTS.md. Standing project instructions the agent reads on every run — build commands, conventions, directories to leave alone. /init writes a first draft by inspecting the repo.
• MCP client and server. codex mcp connects external tools, and Codex can itself be exposed as an MCP server to other agents.
• Skills and plugins. Repeatable instructions packaged as reusable units, plus third-party plugin integration.
• Runtime model switching. /model changes both tier and reasoning effort without restarting the session, so an expensive planning step and a cheap mechanical step can share one conversation.
• Apache-2.0. The client is genuinely open source — 103k stars on GitHub, core written in Rust. You can read exactly what it does with your files.

How It Works

You start codex in a repository. It reads AGENTS.md if one exists, builds context by exploring the project rather than requiring you to paste files, and proposes a plan.

From there it works in a loop: edit, run, read the output, correct. The agentic part is that loop closing without you in it — Codex sees its own test failures and iterates. Your control point is the approval policy, which decides when the loop pauses to ask permission.

The sandbox is enforced by the operating system, not by the model's good intentions:

This matters more than it sounds. A reasoning model that has been talked into running a destructive command by a prompt injection hidden in a dependency's README is stopped by kernel-level confinement, and not by any amount of instruction-following. Network access being off by default in the standard mode is the single most useful line of that defence.

Technical Details

• License: Apache-2.0
• Core implementation: Rust (codex-rs)
• Default model: gpt-5.6-sol, medium reasoning effort
• Available tiers: Sol, Terra, Luna — all three share a 1,050,000-token context window and a February 2026 knowledge cutoff
• Authentication: ChatGPT account sign-in, or an OpenAI API key
• Config file: AGENTS.md in the repository root
• Debug commands: codex debug seatbelt on macOS, codex debug landlock on Linux — run an arbitrary command under the sandbox profile to see what it blocks

Use Cases

• Multi-file refactors. The case that justifies an agent over autocomplete: rename a concept across forty files, update the call sites, run the tests, fix what broke.
• Test-driven repair. Hand Codex a failing test and let the execute-and-read-output loop close on its own. This is where the sandbox pays for itself.
• Codebase onboarding. read-only mode turns Codex into a question-answering layer over an unfamiliar repository, with no risk of it editing anything while you learn.
• CI and review work. The cloud surface handles GitHub code review and long-running tasks that outlive a terminal session.
• Cost-tiered automation. Luna for mechanical bulk edits, Sol for the architecture decision at the start. Mid-session /model switching makes this practical rather than theoretical.
• Mobile follow-up. The iOS app is genuinely useful for checking on a long cloud task, and genuinely not useful for writing code.

Integrations

• Editors: VS Code extension (also covers Cursor and Windsurf via the VS Code extension API)
• Source control: GitHub, including automated code review on pull requests
• Cloud: Amazon Bedrock, added June 2026
• Protocol: MCP in both directions — Codex as client, Codex as server
• Chat: Slack integration on cloud-enabled plans

Pricing & Access

The CLI is free. The model usage behind it is not, and there are two separate ways to pay.

Through a ChatGPT plan — usage is metered in messages against rolling five-hour windows, and local CLI messages share that window with cloud chats. Weekly caps may also apply.

Per-window allowances on Plus run roughly 10–100 messages on Sol, 25–200 on Terra, and 250–2,000 on Luna; Pro multiplies those by 5× or 20×. The spread inside each range is real — a message that triggers a long agentic run costs far more than a one-line question, and there is no pre-task estimate.

Through an API key — pay per token at the standard GPT-5.6 rates: Sol $5.00 in / $30.00 out per million tokens, Terra $2.50 / $15.00, Luna $1.00 / $6.00, with cached input discounted 90%. If you exhaust a plan allowance you can also buy credits, priced per model — 125 credits per million input tokens on Sol against 5 on Luna.

For steady daily use, a plan is cheaper and simpler. For bursty or automated use, the API key avoids the five-hour window entirely.

Getting Started

# macOS / Linux
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# or via npm
npm install -g @openai/codex

# or via Homebrew
brew install --cask codex

Windows has a PowerShell installer, and release binaries are on GitHub for manual installation.

Then, in a repository:

codex                # start a session; sign in with ChatGPT or an API key
/init                # generate a starting AGENTS.md
/permissions         # set the sandbox and approval policy
/model               # switch tier or reasoning effort

Start in read-only on a repository you care about. Move to workspace-write once you have watched it work. Reach for danger-full-access when you have a specific reason and a disposable environment, which in practice means almost never.

Limitations

• The five-hour window is opaque. You cannot see what a task will cost before running it, and a single ambitious request can consume an afternoon's allowance. This is the most common complaint from daily users.
• Free and Go tiers exclude the cloud. No GitHub review, no Slack, no long-running tasks. Local-only is a real product but it is not the whole product.
• Benchmark positioning is contested. Coding leaderboards disagree sharply about Codex versus Claude Code depending on the harness, the reasoning effort and the scoring script. OpenAI publicly disputes SWE-Bench Pro's task quality, where its own models trail. Treat any single number as a claim about a configuration, not about the tool.
• Sandboxing is not free of friction. Network-off by default breaks dependency installs and any test that reaches a service, and the escalation prompts arrive at the least convenient moment. The alternative is worse.
• iOS is a monitoring surface. Useful for checking a running task, not for authoring.

Alternatives

• Claude Code — the closest equivalent. Same terminal-first shape, same MCP support, Anthropic models instead of OpenAI's, proprietary rather than open source. Strong on large multi-file refactors and context efficiency.
• Cursor — if you want an editor rather than a terminal. Better when you stay in the loop on every edit; weaker for long autonomous runs.
• GitHub Copilot — the incumbent, now agentic too, and the path of least resistance in a GitHub-centric organisation.
• Aider — open source, model-agnostic, Git-native. The right answer if you want to bring your own model or keep everything local.
• Cline — open-source VS Code extension with a bring-your-own-key model, for teams that want agentic editing without a vendor subscription.

For a side-by-side, see Claude Code vs Cursor vs Windsurf.

Community & Support

• GitHub: openai/codex — Apache-2.0, 103k stars, issues and releases
• Documentation: developers.openai.com/codex
• Support: OpenAI Help Center for billing and usage limits; GitHub issues for the client itself

Because the client is open source and the model is not, bug reports split cleanly: anything about sandboxing, the TUI, MCP wiring or config belongs on GitHub, and anything about model behaviour or quota belongs to support.