Codex — OpenAI’s Coding Agent

Codex is OpenAI’s agentic coding tool — the same idea as Claude Code, from the other lab. You describe a task in plain English; Codex reads the repo, plans, then edits files and runs commands, checking its own work as it goes. It shows up in three places — a terminal CLI, a cloud workspace that runs tasks for you in the background, and inside your IDE — all backed by OpenAI’s coding-tuned models. It’s the OpenAI-track counterpart to Claude Code and to Copilot’s Agent Mode.

What Codex is

☺ Like you’re 10: Codex is one helper that shows up through three different doors: a little window you type into, a workshop out back where it does big chores while you’re gone, and a buddy sitting right beside you in your editor. Same helper — you just pick the door that fits the job.

“Codex” isn’t a single app — it’s OpenAI’s agentic coder that you reach through several surfaces, each backed by OpenAI’s coding-optimized models (the GPT-5–class / codex family; treat the exact model name as “true at time of writing,” since the lineup moves fast). Whichever door you use, the engine is the same agent loop: understand the request, plan, act, observe, repeat — the loop from Agentic AI, wired into your files, shell, and tools.

You install the CLI once (for example, npm i -g @openai/codex) and run codex in a project; the cloud surface lives in ChatGPT and on the web; the IDE extension installs from your editor’s marketplace. They share the same account, the same models, and the same project configuration — pick the surface, keep the agent. For the provider-neutral “what is an agent” idea, see Agentic AI; for the OpenAI account and app it sits inside, see ChatGPT.

The agent loop in action

☺ Like you’re 10: Codex works like you do on a hard puzzle: make a plan, try a piece, look to see if it fits, and if it doesn’t, look at what went wrong and try a different piece. It keeps going around that circle until the picture is right — you’re not doing it, it is.

Codex’s power isn’t one clever edit — it’s the loop. Instead of spitting out a code snippet and stopping, it takes actions, watches what happens, and uses that result to decide its next move. A single request can spin the loop many times before it reports back:

1. Plan. Read the relevant files, figure out which ones must change and in what order, and outline the approach.
2. Edit. Make the changes across the codebase — often several files at once so the project stays consistent.
3. Run. Execute the code: run the test suite, a linter, a build, or the app itself.
4. Observe. Read the output — a failing test, a stack trace, a type error — as real feedback, not decoration.
5. Iterate. Use what it observed to fix the next thing, and loop again until the checks pass.

This is why running code matters so much: a coding agent that can’t execute is guessing, while one that reads its own test failures is grounded in what actually happened — the same reason grounding beats guessing in Retrieval & RAG. Give Codex a clear finish line it can check itself against — “make the failing tests pass,” “get the build green” — and the loop has a signal to converge on.

Local vs cloud: sync and async work

☺ Like you’re 10: Sometimes you want your helper right next to you so you can watch every step and jump in — that’s local. Other times you hand over a whole chore and go play, and it does the work in its own room and shows you when it’s done — that’s the cloud. You can even hand out several chores at once and let them all get done in parallel.

Codex runs in two modes, and the difference is where the work happens and how much you watch. This mirrors the split on the Copilot track between chatting in your editor and handing a job to the cloud agent:

The cloud mode is the interesting leap: because each task gets its own container seeded with your repo, you can fire off several at once — “add tests to this module,” “bump this dependency and fix the fallout,” “draft the migration” — and come back to a stack of proposed diffs. Nothing lands in your real branch until you review and merge. That’s the same delegate-and-review shape as Claude’s longer-running handoffs; the depth here — containers, parallel tasks, PR output — is OpenAI’s.

IDE and GitHub integration

☺ Like you’re 10: Codex plugs into the tools you already use — your editor and the place your team keeps its code — so it can leave its changes as neat “here’s what I changed” notes that a teammate can look over before they become real.

Codex is built to fit an existing workflow rather than replace it. Two integrations do most of the heavy lifting:

• IDE extension. Inside VS Code (and compatible editors) Codex sees your open files, selection, and diffs, and applies its edits as reviewable changes right in the editor. You can start a task locally and hand the same task off to the cloud without losing context.
• GitHub integration. Connect a repository and Codex can open its work as a pull request — the universal review surface. A cloud task produces a branch and a PR with the diff, description, and the commands it ran, so review, CI, and merge happen exactly where your team already works. You can even kick off or steer tasks by mentioning Codex on an issue or PR.

The through-line is that Codex outputs into human-review channels — an editor diff or a GitHub PR — never straight to main. That keeps a person in the merge decision even when the agent did the typing, which is exactly the posture the safety section builds on. (Copilot’s track lands the same way: its cloud agent also returns a PR you review.)

Configuring Codex for your repo

☺ Like you’re 10: Every project has its own “house rules” — how to build it, how to test it, what to never touch. Instead of repeating those rules every time, you write them in a note that Codex reads first, so it plays by your house’s rules from the start.

Out of the box Codex is capable but generic. You make it yours by giving it always-on project context — the OpenAI counterpart to Claude’s CLAUDE.md and to Copilot’s repo instructions from Customizing. Codex reads a Markdown instructions file (conventionally AGENTS.md) at the repo root, and this convention is deliberately shared across agentic coding tools so one file can guide several of them:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Test:    `pnpm test`      # must be green before you finish
- Lint:    `pnpm lint --fix`

## Conventions
- TypeScript, strict mode. No `any`.
- Prefer small, focused pull requests.

## Never
- Don’t edit files under `generated/` — they’re built, not hand-written.
- Don’t commit secrets or touch `.env`.

Like Claude’s file, this is hierarchical: a repo-root file sets project-wide rules, and more specific files deeper in the tree refine them for a subfolder, with the closest one winning. Put the load-bearing rules — how to test, what never to touch — near the top, because they’re the ones that keep the loop honest. The payoff is the same idea you met in Customizing and in a Claude Project’s instructions: write the rules once, and every run reads them.

Safety and review: approvals, sandboxing, the human gate

☺ Like you’re 10: A powerful helper needs guardrails. Codex works in a fenced-off play area so it can’t wander off and touch things it shouldn’t, and it asks permission before doing anything risky — like a careful helper who checks with you before using the stove. And a grown-up always looks at the finished work before it counts.

An agent that edits files and runs commands is powerful — and powerful means it needs guardrails. Codex builds in three layers, and understanding them is the difference between a helpful teammate and a foot-gun. This is the coding-agent face of the AI Security lesson.

• Approvals. By default Codex asks before doing something consequential — running a shell command, editing outside the workspace, reaching the network. You choose the posture: prompt on everything (tightest), auto-approve within the workspace but ask to leave it, or full-auto for trusted, well-scoped jobs. Loosen the leash as trust grows, not before.
• Sandboxing. Codex runs in a restricted environment — file access scoped to the working directory and network access off or limited by default. Cloud tasks go further: each runs in its own isolated container that can’t see your other work. The sandbox is what makes a wrong move contained instead of catastrophic.
• The human gate. The most important control is the cheapest: a person reviews the diff before it merges. Codex is built to output into review channels — an editor diff, a GitHub PR — precisely so the merge decision stays human, even in full-auto mode.

Codex vs Claude Code vs Copilot agent

☺ Like you’re 10: Three different labs each built a very similar robot coder. They mostly do the same thing, so the real question isn’t “which is smartest” — it’s which one fits the tools your team already uses and the way you like to work.

These three are the same kind of tool — an agentic coder with a plan → edit → run → iterate loop, an instructions file, a local and a cloud mode, approvals, and PR output. The differences are mostly ecosystem and defaults, not category. Pick by what you already use:

Because the shapes are so similar, the skill transfers: learn to write a good instructions file, scope a task tightly, and review a diff carefully with one of them, and you can drive all three. Choose on model preference, how deep your ecosystem lock-in already runs (GitHub vs ChatGPT vs Claude), and which cloud/async story fits your team — not on a feature checklist that’ll be stale next month. For the concepts underneath every one of them, the Agentic AI and Building Agents lessons are the provider-neutral home base; the wider tool map lives in Ecosystem.