OpenAI Codex, the Coding Agent, Explained: How It Works and Where to Run It

OpenAI Codex is an agentic coding tool built by OpenAI: you describe a task in plain English, and the agent reads the codebase, edits files, runs tests, and opens a pull request on its own. According to Wikipedia, it launched in April 2025 as an open-source CLI and had grown to more than 2 million weekly active users by March 2026.

That agent is also the engine behind the Codex Micro macropad, a physical controller that shows the status of running Codex agents through color — idle, thinking, finished, or waiting on a question. This article covers what the Codex coding agent actually is, which models drive it, where you can run it, and how it stacks up against rivals like GitHub Copilot and Claude Code.

What OpenAI Codex Actually Is

OpenAI Codex is a type of AI coding agent, built and maintained by OpenAI, and it’s a different beast from the autocomplete tools that came before it. Rather than suggesting the next line as you type, it takes a feature-level instruction, searches across the codebase, edits multiple files, runs commands, and works through multi-step tasks on its own — pausing only when it needs a human to review its work. Codex CLI shipped on April 16, 2025, and a cloud preview of the agent followed exactly a month later, on May 16, 2025.

Across its surfaces, the agent is built to handle a recurring set of engineering jobs:

• Write new features from a natural-language description
• Fix bugs and explain why they happened
• Run the existing test suite and add new tests
• Refactor code across multiple files
• Open a pull request with a summary of the change

From autocomplete to an agent

The Codex coding agent doesn’t just finish a line of code. Give it an instruction like “add OAuth login,” and it will touch several files, run the test suite, and hand back a pull request ready for review. That shift — from suggestion to autonomous execution — is what separates it from older, line-by-line assistants. It’s also the same shift that defines vibe coding: describing what you want in words and letting an autonomous AI coding agent write the implementation.

A short history

The name isn’t new. The original Codex, released in 2021, was an autocomplete model descended from GPT-3. Today’s OpenAI Codex is a completely different product: an agent, not a text predictor — the CLI and cloud preview launches above marked the point where it turned into something closer to a teammate.

How the Codex Agent Works

Every Codex task runs inside an isolated cloud sandbox environment, preloaded with a copy of the user’s repository. General internet access is switched off by default, a deliberate security choice that limits what a misbehaving task could reach. Inside that sandbox, the agent reads the codebase, edits files, executes commands, runs tests, and — once it believes the work is done — opens a pull request for a human to review.

The task loop

Most Codex tasks follow the same loop, and it typically takes between 1 and 30 minutes end to end:

1. You describe the task in natural language.
2. Codex plans the steps needed to complete it.
3. It reads the relevant files across the codebase.
4. It writes and applies the code changes.
5. It runs tests inside the sandbox to check its own work.
6. It opens a pull request.
7. A human reviews, requests changes, or merges.

Parallel agents and worktrees

Because each task runs in its own environment, several Codex agents can work in parallel using git worktrees or separate cloud environments — OpenAI describes this as completing weeks of engineering work in days. Multi-agent workflows like this are also how the macropad earns its keep: a bank of keys, one agent status per key, so a developer running four Codex tasks at once can glance at the legend instead of tabbing between terminals.

The Models Behind Codex

Codex Cloud launched on codex-1, a version of OpenAI’s o3 reasoning model fine-tuned for software engineering, with a context window of roughly 192,000 tokens. By 2026, newer frontier models in the GPT-5.x-Codex line had taken over, including GPT-5.3-Codex. The lineup moves fast enough that any specific version number is a snapshot, not a fixed spec — what stays constant is the intent: reading large repositories, following multi-step instructions, and checking its own work before opening a pull request.

Where You Run Codex

The same underlying agent shows up in three places, and OpenAI ties all of them to a single ChatGPT account:

• The ChatGPT app — assign and monitor cloud tasks from the web or desktop
• A Codex IDE extension — inline agent work inside VS Code or Cursor
• Codex CLI — a terminal-based agent, open-source under Apache-2.0

One agent, three surfaces

Whether you open the ChatGPT app, install the IDE extension in VS Code or Cursor, or run Codex CLI from a terminal, it’s the same agent behind all three, tied to one account. The CLI itself is open-source under the Apache-2.0 license, hosted on GitHub. OpenAI folded its standalone Codex desktop app into the main ChatGPT desktop app in mid-2026, so there’s now one app to install rather than two.

Context and configuration

Codex reads an AGENTS.md file automatically if one exists in the repository — a plain-text place to document team conventions, coding standards, and rules the agent should follow on every task. Beyond that file, a few configuration pieces shape how the agent behaves on a given repo:

• Model Context Protocol (MCP) servers, for connecting Codex to external tools and data sources
• Web search, for pulling in current documentation while it works
• Image input and output, for reading design mockups or returning screenshots
• Skills, for teaching Codex a team’s repeatable workflows and standards

Codex vs Other Coding Agents

Codex performed best in our backend Python code-review benchmark. It was the only one to catch tricky backward compatibility issues and consistently found the hard bugs that other bots missed.

Aaron Wang, Senior Software Engineer, Duolingo

Agent, not autocomplete. GitHub Copilot built its reputation on inline autocomplete — it predicts the next few lines as you type. Codex, Claude Code, and Cursor sit in a different category: agentic tools that take a task description and carry it through planning, editing, testing, and review on their own, with far less moment-to-moment supervision.

Real-world results vary by team. Duolingo’s engineering team reported that Codex caught backward-compatibility issues in backend Python code review that other bots missed, cutting the time engineers spent chasing subtle regressions. Results like that are why review time and pull-request throughput have become the metrics teams actually track, rather than lines of code generated.

Pricing and Access

There’s no separate Codex subscription — access comes bundled with a ChatGPT plan:

• ChatGPT Plus: about $20 a month
• ChatGPT Pro: roughly $200 a month
• ChatGPT Business: about $25 per user per month (monthly billing; $20 on annual billing)
• Codex CLI on its own: free and open-source, no ChatGPT plan required for local runs

Cloud tasks and the hosted GPT-5.x-Codex models still require an underlying ChatGPT plan even though there’s no Codex-specific charge on top of it.

OpenAI’s hardware ambitions extend past software, too — the company has also been reported to be working with former Apple design chief Jony Ive on OpenAI’s rumored smart speaker, a sign that OpenAI, like the Codex Micro macropad itself, is betting that physical devices are a natural extension of an AI agent’s reach beyond the screen. For more on the hardware side of that story, bota.chat tracks the Codex Micro project and the agents it controls.

FAQ