Codex: OpenAI's Coding Agent

Codex is OpenAI's coding agent — the GitHub Copilot maker's answer to "what if the model could not just suggest code, but actually read your repo, edit files, run commands, and keep going until the task is done?" If you have used Claude Code, the shape will feel familiar: you describe an outcome, the agent works the loop, and you review the result. The differences are in the surfaces it lives in, the file it reads for instructions, and the knobs it gives you to control how much it is allowed to touch.

This guide is your orientation map. By the end you will know what Codex actually is, the three places it runs, how to install and sign in, where its configuration lives, and how its concepts line up against the agents you may already know.

What Codex is

OpenAI describes Codex as "OpenAI's coding agent for software development." That phrase is doing real work. It is an agent, not an autocomplete: it gathers context, takes actions, observes the results, and iterates — the same read-act-observe loop that defines every coding agent. It writes code, explains unfamiliar codebases, reviews diffs, debugs failures, and automates repetitive development chores.

Codex is bundled with paid ChatGPT plans — Plus, Pro, Business, Edu, and Enterprise — so for most people there is no separate purchase. The same agent is reachable through several front doors, which is where most of the initial confusion comes from. Let us clear that up first.

The surfaces: one agent, several doors

Codex is not a single program. It is one agent exposed through a family of surfaces, each tuned to a different moment in your workflow. The official docs describe four entry points, and they all drive the same underlying agent:

• CLI — a "lightweight coding agent that runs in your terminal." This is the surface this constellation focuses on. You run codex in a project directory and work in a conversational loop, with slash commands and command-line flags for control.
• IDE extension — Codex inside your editor (such as VS Code), with slash commands and editor-native affordances like seeing edits land directly in open files.
• Cloud / web — Codex running in a sandboxed cloud container with optional internet access. You hand it a task, it works asynchronously in an isolated environment, and you review the result — useful for longer jobs you do not want tying up your laptop.
• App — a desktop application with a project sidebar, a list of threads, and review tooling, for people who prefer a dedicated window over a terminal or editor panel.

The key mental model: these are doors into the same agent, not four different products. A task started conversationally in the CLI and a task handed off to the cloud are the same kind of work, run in different places. You pick the surface that fits the moment — terminal for quick interactive work, cloud for long-running jobs, IDE when you want edits in your editor.

Configuration lives in ~/.codex/config.toml

Codex keeps its settings in a TOML file at ~/.codex/config.toml (a project-scoped .codex/config.toml can override it for a single repo). This is where you set durable preferences so you are not passing the same flags every session. The official config reference documents the full key list; a handful matter most when starting out.

The model key picks which model the agent runs on — for example model = "gpt-5.5", the model OpenAI lists as the latest at the time of writing. The model_reasoning_effort key trades speed for depth on supported models, accepting values from "minimal" through "low", "medium", "high", and "xhigh".

The two safety-critical keys are approval_policy and sandbox_mode, and they work together. sandbox_mode decides what the agent is capable of touching; approval_policy decides when it must stop and ask you first.

AGENTS.md: the instructions Codex reads

Codex looks for an AGENTS.md file in your project and treats it as standing instructions for the agent — your build and test commands, conventions, and the gotchas it could never infer from the code alone. It is the same idea CLAUDE.md fills for Claude Code: a plain markdown file that hands the agent your project's knowledge before you type a word. AGENTS.md is an open, cross-tool convention rather than a Codex-only invention, so the same file can guide multiple agents. The mechanics — what to put in it, how to keep it short enough that the agent actually follows it — are worth a guide of their own; see the AGENTS.md guide in this constellation.

Scripting Codex with exec

For automation, the CLI offers a non-interactive mode: the codex exec command runs a single task without the conversational loop, so you can script repeatable workflows — a pre-commit refactor, a CI step, a scheduled cleanup. Interactive codex is for exploration; codex exec is for putting a known task on rails. Codex also speaks the Model Context Protocol (MCP), so it can connect to external tools and data sources the same way other modern agents do.

Inside the IDE extension

The editor surface ships as a single extension published under openai.chatgpt [V] — install that and the same agent you drive from the terminal lives in your editor's sidebar. It is not VS Code-only: the official IDE docs list VS Code (and VS Code Insiders), Cursor, Windsurf, and JetBrains IDEs (Rider, IntelliJ, PyCharm, WebStorm) [V]. Edits land directly in your open files so you review diffs where you already read code, and you can kick off a cloud task from the editor without leaving it.

Inside the extension you pick how much rope the agent gets with three approval modes — Chat, Agent, and Agent (Full Access) — switching between them by how much autonomy you want Codex to have [V]: Chat prompts with editor context, Agent delegates tasks with bounded autonomy, and Agent (Full Access) hands over the widest latitude. [P] These map onto the same approval_policy / sandbox_mode thinking the CLI exposes, just presented as a mode picker instead of TOML keys — useful to remember when an action you expected to run silently instead stops to ask, or vice-versa.

The desktop app and the cloud

The desktop app (macOS and Windows) is a standalone download you install and sign into [V] — it is not a subcommand of the CLI, so there is no codex app to type. Its whole reason to exist is running threads in parallel: project threads sit side by side and each one is kept isolated with built-in Git worktree support [V], so two tasks editing the same repo never trip over each other's changes. A project sidebar, an active-thread view, and a review pane let you follow plans and sources, then inspect diffs, stage files, commit, and push without leaving the window [V]. [P] Reach for it when you want several independent changes in flight on one repo at once — the worktree isolation is what makes that safe.

Codex cloud moves the work off your machine entirely. Submit a task and Codex creates a container and checks out your repo at the selected branch or commit [V], then works asynchronously while your laptop stays free. During the agent phase internet access is off by default — you can opt into limited or unrestricted access when a task genuinely needs it [V] — and all outbound traffic flows through an HTTP/HTTPS proxy for abuse prevention [V]. You can start a cloud task from three places: the web (connect your GitHub account at Codex), the IDE extension (kick off a cloud task from your editor), or @codex on GitHub — tag it on an issue or pull request to spin up a task [V].