OpenAI Codex — what it is and how it works

What is OpenAI Codex?

OpenAI Codex is an AI coding agent that can inspect a codebase, modify files, run commands and tests, and report the result of a software task. It is not one fixed model, but a product layer that combines OpenAI models with tools, execution environments and project-specific instructions. A useful mental picture: the model is the "brain", while Codex is the "hands and workspace" in which that brain acts.

That framing answers the three questions a newcomer usually has. What is today's Codex? An agent that carries out software tasks end to end. How does it differ from the old Codex? The old one was a single model that generated code; the new one is a product that uses models. Why is it more than autocomplete? Because it does not just suggest the next lines — it can take a task, work on the repository and verify the result.

Why the name is confusing

The label "Codex" has been used for two different things, and mixing them up is easy. The original Codex was a language model that translated natural-language prompts into code and helped power the first versions of GitHub Copilot. Today's Codex is a coding agent relaunched under the same name in 2025. Same name, different products, built for different kinds of work.

A short history makes the distinction clearer:

Read this way, the model names are milestones in a development history — not a description of a permanent product architecture.

A product, not one fixed model

Today's Codex should not be understood as one fixed AI model. It is a coding-agent product that can use different OpenAI models depending on the interface, task and current product configuration. The first cloud version ran on a model called codex-1, a variant of the o3 reasoning model tuned for software engineering; a later, GPT-5-based variant added stronger support for long refactors and code review.

The important point is not any single model name. The models available inside Codex change over time — OpenAI's model catalog is the place to check what currently powers a given task. This is exactly why it helps to separate the agent product from the model behind a particular run, and why the article does not lean on a frozen list of engines.

How a Codex task works

Instead of listing capabilities, it helps to follow one task. Suppose someone asks Codex to fix a bug: the newsletter sign-up form accepts an empty email address — you click "Subscribe" with the field empty and the sign-up still goes through.

1. Codex reads the task and the project instructions (from AGENTS.md): an empty email must not be accepted.
2. It searches the app's code and finds where this form is handled — what happens when "Subscribe" is clicked.
3. It looks at how it works today and what tests exist — what "correct" behaviour means here.
4. It reproduces the problem: submits the form with an empty field and confirms the sign-up goes through when it shouldn't.
5. It fixes the code: adds validation that rejects an empty or invalid address.
6. It runs the tests and checks: an empty email must be rejected, a valid one must still work.
7. If a test fails, it analyzes the result and fixes it again — until everything is green.
8. It shows a human what changed, the test results and any doubts — the human decides whether to accept.

This does not mean Codex always completes every step successfully. What matters is that it can participate in the entire workflow rather than only generate an isolated code snippet.

After walking through that loop, the difference between an agent and autocomplete is concrete: autocomplete helps you type the next line, while an agent takes responsibility for a chain of steps and checks its own work.

Where Codex runs

Codex is one product with several entry points and one configuration layer.

• Desktop and local environments — Codex works with files and commands on the user's machine, subject to configured permissions.
• Cloud environments — tasks run in isolated environments associated with a repository.
• CLI and IDE integrations — developers can work with Codex from a terminal or supported editors such as Cursor and Windsurf.
• Remote and automated workflows — tasks such as code review can run without keeping a local editor session open.

The Codex CLI itself is open source under the Apache-2.0 license and installs via npm, Homebrew or prebuilt binaries (openai/codex repository).

How Codex is configured

Codex reads configuration in layers — from user settings, through project settings, to policy imposed by your organization:

• User settings — the ~/.codex/config.toml file (in the CODEX_HOME directory, ~/.codex by default).
• Project settings — .codex/config.toml files in the repository. Codex walks from the project root to your current directory and merges them; the closest file wins. It loads the project layer only for trusted projects — in untrusted ones it ignores it.
• Managed layer — an organization can impose a requirements.toml file that, for example, forbids risky settings (such as approval_policy = "never" or sandbox_mode = "danger-full-access").
• Prose instructions — how to build, test and which conventions to follow — live in the AGENTS.md file.

Permissions and sandbox

What the agent may do comes down to two settings:

• sandbox_mode — read-only, workspace-write (write inside the working directory; network access restricted by default) or danger-full-access (full access).
• approval_policy — when Codex asks a human to approve an action: untrusted, on-request or never.

The sandbox protects sensitive paths (including .git and .codex), and isolation relies on the operating system's native mechanisms (on Windows via elevated/unelevated modes).

Where to set this and how to make your own profiles:

• Put your defaults in ~/.codex/config.toml.
• Config profiles are selected with --profile <name>; they overlay a ~/.codex/<name>.config.toml file on top of the base config — keep shared defaults in one place and put only what differs in the profile (for example a separate "deep-review" profile).
• Permission profiles (reusable file- and network-access policies) come in built-in flavors — :read-only, :workspace, :danger-full-access — and you define your own in [permissions.<name>] tables.
• A single run can be overridden from the command line with dot notation (for example mcp_servers.context7.enabled=false).

Verification: builds and tests

Codex has no test format of its own — it runs your project's existing commands (such as npm test, pytest, make) inside the sandbox and reads the result, iterating until they pass. The key is to tell it how to build and test:

• In AGENTS.md you describe the build commands, tests and repository conventions — the agent applies these instructions without you restating them in every prompt.
• Project hooks (scripts in .codex/hooks/, such as pre_tool_use) let you wire in your own policies and checks before or after the agent's actions.
• Because "success" is a passing test or a clean build, a well-maintained test suite is at the same time the mechanism that verifies the agent's work.

Skills and integrations

A skill is a way to package a reusable workflow. Technically it is a directory with a SKILL.md file (required name and description fields plus instructions) and optional subdirectories: scripts/ (code to run), references/ (documentation), assets/ (templates) and agents/openai.yaml (appearance and dependencies).

• Where they run and where to find them. Standalone skills are available in the ChatGPT desktop app, the Codex CLI and the IDE extension; in the ChatGPT app you browse them in the "Skills" panel in the sidebar. Skills and connectors are also distributed as plugins through a shared plugin directory common to ChatGPT and Codex.
• How they work. Codex uses "progressive disclosure": it starts with only each skill's name, description and file path (that initial list uses at most ~2% of the context window), and loads the full SKILL.md only when it decides to use a skill. Activation can be explicit (type @ in ChatGPT, run a command in the CLI/IDE) or automatic.
• Can you write your own — and how. Yes. You create a my-skill/ directory with a SKILL.md file, add scripts/ and references/ if needed, and place it where Codex looks for skills. The same format works in ChatGPT and in Codex.
• Competitors' skills. The "folder + SKILL.md" convention is not unique to Codex — other agentic tools use a similar format — but portability is not guaranteed: Codex loads skills from its own locations and the plugin directory, so a skill from another ecosystem usually has to be adapted rather than used unchanged.
• External integrations. Codex adds access to tools and services beyond the repository through MCP servers (configured under the mcp_servers. key), as well as agent roles in the [agents] section.

What Codex is useful for

Codex is designed for concrete, verifiable engineering work:

• Writing new features from a natural-language description.
• Fixing bugs, from diagnosis to test-based verification.
• Large-scale refactoring across many files.
• Code review — navigating a repository, analyzing dependencies and running tests to produce review comments.
• Answering questions about a codebase — "how does this module work?", "where is this defined?".
• Running tests and iterating until they pass.

On OpenAI's own evaluation of long, multi-step software-engineering tasks, the GPT-5-based Codex variant performed better than the standard GPT-5 baseline used for comparison. Treat that as evidence of specialization, not a universal measure of coding quality.

Benchmark context: OpenAI reported roughly 51% vs 34% on a multi-step refactoring benchmark, the ability to work autonomously for hours on a single task, and far lower token use on trivial requests (about 93.7% fewer on the simplest tenth of inputs). These figures come from OpenAI's own testing, so they describe specialization under specific conditions rather than an independent verdict.

How to give Codex a good task

For an agent, the task description isn't a loose request but the actual brief: from it, Codex decides what to read, what to change, how to verify the result with tests, and what to hand back to you. The more precise the description, the better the outcome — which is why writing clear tasks is the single most useful skill when working with Codex.

Compare two ways of asking for the same fix.

A weak task:

Fix the checkout.

A better task:

Diagnose why checkout requests return HTTP 500
when the discount code has expired.
Preserve the current response format for valid codes.
Add a regression test for the expired-code case.
Run the checkout test suite and summarize the cause
and the changed files.
Do not modify unrelated pricing logic.

The second version works because it pins down four things a good task almost always specifies:

• Scope — which files, modules or behavior are in play, and how far the change may reach. Without it, the agent may "fix" far more than you wanted.
• Expected result — the concrete behavior that should exist afterwards, stated as an outcome ("valid codes still return the old format"), not a vibe ("make checkout better").
• Verification — the tests or commands that decide success. An agent that can run a failing test and watch it turn green has an objective target; one told to "improve the code" does not.
• Constraints — what must not change. This is where you prevent collateral edits to unrelated logic, public interfaces or formatting.

A few habits make those four easier to hit:

• Give the agent a map, not a maze. Point it at the relevant module, endpoint or failing test instead of letting it search the whole repository blindly. Less guessing means fewer wrong turns.
• Make success machine-checkable. Tasks that end in a passing test, a clean build or a specific command output are the ones an agent can finish and you can trust. Purely aesthetic or subjective goals are the hardest to delegate.
• Keep tasks bounded, then chain them. One clear task ("add the regression test", then "refactor the handler") beats a single sprawling instruction. Small tasks are easier to review and to roll back if they go wrong.
• Put durable rules in AGENTS.md, not in every prompt. Build commands, test commands and coding conventions belong in the project's instructions, so you do not restate them each time and the agent applies them consistently.
• Decide your review bar in advance. Know what evidence you will accept — which tests must pass, what you will read by hand — before you look at the result, so the agent's confidence does not quietly become yours.

Two failure modes are worth naming, because they are the most common. The first is an open-ended goal with no test ("clean this up", "make it faster"): the agent has nothing to aim at and no way to prove it succeeded. The second is a task so broad it touches half the codebase; even a correct result becomes hard to review. When a request starts to feel like either, split it into smaller tasks with their own checks.

The pattern behind all of this is simple: the more precisely you describe the goal, the boundaries and the proof of success, the more of the work you can safely hand over — and the less time you spend untangling changes you never asked for.

Permissions, internet access and security

Cloud tasks run in isolated environments with controlled network access. Internet access may be disabled, restricted to approved domains, or enabled according to the environment's configuration and organizational policy (documentation on internet access). Restricting the network reduces supply-chain and data-exfiltration risks, but it can also stop the agent from downloading dependencies or consulting external services — a real trade-off between usefulness and safety.

On top of the sandbox, permission profiles decide which files and commands the agent may touch, and higher-risk actions can require human approval. None of this removes the need for review: generated code should be read, tested and, where appropriate, checked for provenance before it is merged.

Limits and unresolved questions

• Verification is not optional. Model output can be wrong or "plausible-looking but off." Tests help, but they do not replace human review.
• Security of generated code. Earlier studies of AI code-generation systems, including tools related to the original Codex generation, found that generated code could reproduce insecure patterns. Those results do not directly measure today's Codex agent, but they establish a general lesson: plausible-looking generated code still needs security review and testing (Wikipedia overview of the original model).
• Copyright. Code-generation systems can occasionally produce output that resembles material in their training data. The practical risk depends on factors such as prompt specificity, the popularity of the source and the length of the passage — which is why review, provenance checks and clear policies matter.
• Access and cost. Codex is available through eligible ChatGPT plans, with usage limits and model availability depending on the plan; some local and developer workflows can also use an API key, billed at API pricing. Heavy use may exhaust a plan's rate limit — after which a user can wait for the reset, switch to a lighter model where available, or buy additional usage if the account supports it.

From autocomplete to delegated engineering work

Codex's distinguishing feature is not one isolated capability, but the way local, cloud and account-connected workflows are presented as parts of a single product. That distinction is relative rather than permanent — competing agents such as Claude Code and the agentic modes in Cursor are rapidly adopting similar patterns.

Codex does not eliminate the need for software-engineering judgment. It changes where that judgment is applied. Less effort may go into mechanically producing every line, while more goes into defining the task, setting boundaries, designing verification and reviewing the result.

That is the meaningful shift from assistant to agent. The machine can take responsibility for a longer chain of actions, but the human remains responsible for deciding what should be done, what evidence counts as success, and whether the result is safe to accept.

Sources

• TechCrunch — "OpenAI launches Codex, an AI coding agent, in ChatGPT" — link
• InfoQ — "OpenAI Releases GPT-5-Codex" — link
• OpenAI — "Introducing Codex" — link
• OpenAI — model catalog (current models) — link
• OpenAI / ChatGPT — Codex cloud internet access — link
• OpenAI — Codex configuration (config.toml, profiles) — link
• OpenAI — Codex sandbox & permissions — link
• OpenAI — Codex skills (SKILL.md) — link
• GitHub — openai/codex repository (Codex CLI) — link
• Wikipedia — "OpenAI Codex (language model)", the original 2021 model — link