Lesson 2 of 5 · Coding Agents and CLIs

Codex

OpenAI's coding agent runs in three places, sandboxes every command by default, and reads AGENTS.md without being asked. Here is how it is put together, as of September 2026.

The plain-English version of Codex, what it is, what it costs, and who it is for, lives in Agents lesson 3. This lesson is the working parts: where Codex runs, how it decides what it may do, which files it reads, and where it differs from Claude Code in daily use. Every command, path, and setting below was checked against OpenAI's Codex docs and the CLI on the site owner's laptop (Codex CLI 0.153.0) on the day this was written.

Three surfaces, one agent

Codex is one agent with three front doors.

The CLI. A CLI is a command-line interface, a program you run by typing its name in a terminal. You run codex inside a project folder and talk to it there. It shows commands and diffs as they happen, and you can steer it mid-turn. This is the surface the rest of the lesson is about.
The IDE extension. An IDE is an editor with a project view, terminal, and debugger built in. The extension is listed in the VS Code marketplace as ChatGPT and works in VS Code, Cursor, and Windsurf. Xcode and JetBrains ship their own integrations. From the extension you can work locally or hand a longer task to the cloud.
Cloud tasks. At chatgpt.com/codex you give Codex a task and it runs in an isolated environment on OpenAI's machines. Several can run at once. When one finishes you read the summary and diff, ask for a follow-up, or open a pull request. A pull request is a proposed change to a repository that someone reviews before it lands.

The desktop app, which the Agents lesson covers, is a fourth door. Local and cloud messages draw from the same usage allowance, so the choice is about where you want to sit, not about spending.

Install and sign in

The install command on the CLI docs page, as of September 2026, is a shell script:

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

The same page lists npm and Homebrew as alternatives. Then cd into a project and run codex. The first launch offers "Sign in with ChatGPT," which opens a browser to your existing account. Later, codex login starts the same flow and codex login status shows which account is active. To pay per use through the API instead, the docs show piping a key in from the environment:

printenv OPENAI_API_KEY | codex login --with-api-key

Credentials land in ~/.codex/auth.json or your operating system's keychain, depending on a config setting. The docs say to treat that file like a password.

Five slash commands are worth learning on day one. /init writes an AGENTS.md for the project. /status shows the session's model, sandbox, and approval settings. /permissions changes what Codex may do. /model picks the model and reasoning effort. /review reads the current changes and reports problems.

Approvals and the sandbox

This is the part of Codex most unlike Claude Code, so it gets the most space. There are two separate controls, and the docs keep them apart.

The sandbox mode is a technical wall around every command the agent runs, enforced by the operating system rather than by the model's good behavior. Three values, by their documented names:

read-only: the agent can inspect files but cannot edit them or run commands without approval.
workspace-write: the agent can read, edit files inside the project folder, and run routine local commands inside that boundary. This is the default.
danger-full-access: no sandbox. The name is the warning.

The approval policy is when the agent stops to ask you. As of September 2026 the config reference lists two supported values: on-request, where the agent works inside the sandbox and asks when it needs to step outside it, and never, where it does not ask and a blocked command just fails back to the model. Two older names, untrusted and on-failure, are marked unsupported and deprecated, so a blog post that uses them is stale.

In the CLI, /permissions opens a picker with presets that set both controls at once: "Ask for approval" (workspace-write plus on-request, the default), "Approve for me" (eligible approvals go to an automatic reviewer instead of you), "Full access" (danger-full-access plus never), and a custom option that reads your config file. The same settings are launch flags: --sandbox takes a mode, --ask-for-approval takes a policy, --approve-for-me turns on the reviewer. The flag for no sandbox and no prompts is spelled out in full, --dangerously-bypass-approvals-and-sandbox, and its help text says it is intended solely for environments already sandboxed from the outside.

One default that surprises people: the docs state that the agent runs with network access turned off. Inside the sandbox, a command that downloads a package or calls an API either fails or, under on-request, comes back to you as a question. That one fact explains most of the approval prompts in a normal session.

The hard part, simply

The hard idea is that Codex's safety is a fence, not a promise. Claude Code's permission modes are rules the harness checks before each action: ask, allow, deny. Codex has that layer too, the approval policy, but underneath it every command is started inside an operating-system sandbox. On a Mac that is the Seatbelt policy system, run through sandbox-exec. On Linux it is bwrap plus seccomp. On Windows it is a native sandbox, or the Linux one inside WSL2. The model does not get to talk its way past any of those. Even if it were tricked by a file it read, the command it runs still cannot write outside the folder or reach the internet unless the sandbox mode allows it.

Think of a landscaping crew working a yard in Washington. A permission system is the homeowner saying "ask before you touch the sprinkler line." A sandbox is the sprinkler line being shut off at the valve before the crew arrives. The first depends on everyone remembering. The second works even when nobody does. You want both, and Codex ships with both on.

What it costs you: the fence interrupts ordinary work more often than a rule would. Ask Codex to validate a static site with a tool it has to download, and under the defaults it stops, because the download needs the network and the sandbox has none. Ask it to write a file one folder up from the project and it stops again. Each stop is correct. Each is also a few seconds of you reading a command and pressing a key, and on a task with ten small network calls the temptation is to reach for full access to make it quiet. The narrower fix: approve for the session when you recognize the command, or set sandbox_workspace_write.network_access to true in the config for the one project that needs it, and leave the fence standing everywhere else.

Tap through a shortened session where Codex adds a contact form to a static page for a Washington County landscaper. Watch for the one step where the sandbox stops it.

Codex adds a contact form

1. You typed

Add a contact form to index.html for Red Cliffs Landscaping. Fields: name, phone, email, message. Match the existing styles. Post it to /api/contact, which the hosting provider gives us.

Codex read AGENTS.md before this line arrived. Nothing to invoke; the file is picked up on its own.

1 of 14

Illustrative Codex CLI session, shortened and typed by hand to show the shape of a real one. Sandbox workspace-write, approval on-request. Tool call and approval wording is described generically because it changes between versions.

The files Codex reads

AGENTS.md. Codex reads instruction files natively, no pointer needed. The documented order: first the global file, ~/.codex/AGENTS.override.md if present, otherwise ~/.codex/AGENTS.md. Then it walks from the git root down to the folder you launched in, at most one file per directory, and concatenates them with blank lines between. The one closest to your working directory lands last in the prompt, which is how project rules override global ones. The walk stops at the project_doc_max_bytes cap, 32 KiB by default, and project_doc_fallback_filenames lets Codex find rules kept under another name. Claude Code lesson 4 shows how to share one AGENTS.md between the two tools, which is what this site runs on.

config.toml. Settings live in ~/.codex/config.toml. TOML is a plain text settings format: key = "value" lines under bracketed section headers. The keys you will actually set are model, model_reasoning_effort, approval_policy, and sandbox_mode. A repo can carry overrides in .codex/config.toml, but Codex loads those only after you mark the project trusted, the right instinct for a file that arrived with a git clone. Named profiles sit beside the main file as <name>.config.toml and load with --profile; any single key can be overridden for one launch with -c key=value. Precedence, highest first: flags, project file, profile, user file, built-in defaults.

Skills. A skill is a folder with a SKILL.md whose frontmatter has a name and a description, and whose body is the procedure. As of September 2026 the docs list four places Codex scans, highest priority first: .agents/skills in the working directory and each parent up to the repo root, ~/.agents/skills, /etc/codex/skills for machine-wide skills, then the ones bundled with Codex. Invoke one with /skills or by typing $ and the name, or let Codex pick one when the description fits. You may also see ~/.codex/skills on a machine set up earlier this year; run /skills to see what your version loads before you move anything.

MCP servers. MCP is the Model Context Protocol, a standard way to hand an agent a tool it did not ship with. In Codex they are [mcp_servers.name] tables in the same config.toml, and the CLI, IDE extension, and desktop app all read them. A local server needs a command; a remote one needs a url and, for a token, the name of the environment variable that holds it. You rarely write the table by hand:

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list

The first line writes the table. The second lists every server Codex knows about. Notice the token pattern: you name the environment variable, you never put the value in the file, because the config file is not secret.

What a ChatGPT plan includes

Codex is not a separate purchase. As of September 2026 OpenAI's pricing page lists it on every tier from Free through Enterprise. Free and Go are framed as enough for quick or lightweight tasks, Plus as access across web, CLI, IDE extension, and iOS, Pro as a multiple of Plus usage, and Business and Enterprise add larger cloud machines, admin controls, and single sign-on. The limit on any plan is a message allowance per five-hour window that depends on the model and the size of the task, with weekly limits possible on top. The multiples and dollar figures move often enough that this lesson links rather than quotes: learn.chatgpt.com/docs/pricing. If you already pay for ChatGPT, you already have Codex; try it before you spend anything else.

Where it differs from Claude Code in practice

Observations from using both on the same laptop, dated September 2026 and checked against each vendor's docs that day. They will age.

Sandbox model. Codex starts every command inside an OS-level sandbox by default and layers approvals on top. Claude Code starts from a permission system, six modes from manual through bypass, with an OS sandbox you turn on with /sandbox; Claude Code lesson 2 covers it. Codex is safer with the defaults left alone, and interrupts more often for network and out-of-folder work.
Cloud tasks. Codex's cloud is built around handing off a task and coming back to a diff and a pull request, several in parallel, and the IDE extension has a delegate-to-cloud path built in. Claude Code's web surface at claude.ai/code works on the same idea, but on the Codex side the cloud is the more central part of the product.
Editor integration. Both ship a VS Code extension. Codex's also installs into Cursor and Windsurf from the same listing, and OpenAI points Xcode and JetBrains users at those editors' own integrations. Claude Code ships its own JetBrains extension. If you live in JetBrains, that is a real difference; in VS Code it is not.
AGENTS.md read natively. Codex reads AGENTS.md with no setup. Claude Code reads CLAUDE.md and needs a one-line import to pick up AGENTS.md. Codex is the tool you can hand a contractor without explaining the rules file; Claude Code is the one where you add the pointer once and forget it.

Not on the list: which one writes better code. That changes with each model release, and any answer written in September would be wrong by the time you read it. The site owner runs Claude Code as the main tool and Codex for a second opinion on the same diff. Lesson 5 turns that into a decision table.

Try this yourself

You need a laptop, a ChatGPT account on any plan, and a folder that already has an AGENTS.md. If you finished Claude Code lesson 4 you have one. If not, write three rules you actually want followed into a file with that name.

Install with the script above, then confirm it: codex --version.
Run codex login, choose Sign in with ChatGPT, finish in the browser, then codex login status.
cd into the folder with the AGENTS.md and run codex. Leave the permissions on the default. Type this:

Before doing anything else: summarize the rules you loaded from AGENTS.md as a numbered list. Tell me which files you read them from, in the order you read them. Do not edit anything.

You should get your three rules back, plus anything in ~/.codex/AGENTS.md if you have one, global first. Then run /status and read the sandbox and approval lines. That is your baseline: what Codex knows and what it may do, before you ask it to change a file. If a rule is missing, check that the file sits at the git root or between the root and the folder you launched in; the documented walk goes down, not sideways.

Next lesson3. Cursor

Last updated September 17, 2026