Getting started · Codex
A layman's guide to Codex setup.
Everything you need installed, in order, with the reason for each one. Budget an hour the first time. You will not need it again.
You are installing three things.
Codex is OpenAI's coding agent. It reads your repository, edits files and runs commands, and it comes in three shapes that share one account: a terminal tool, an extension inside your editor, and a cloud version in ChatGPT. This guide sets up the first two, because those are the ones that work on the code sitting on your own machine.
Check this before you start
Codex is included with ChatGPT plans, and how much you get is not the same on each one. OpenAI's pricing page currently states that Codex is included in the Free, Go, Plus, Pro, Business, Edu and Enterprise plans, that local and cloud work share a five hour window, and that weekly limits can apply on top. There is also an API key route, where you pay per token at API pricing.
Those numbers move, and this page is not the place to trust them from. Read OpenAI's own pricing page (opens in a new tab) before you plan around a limit.
Why we tell beginners to install VS Code first.
The Codex CLI runs in a terminal, and a terminal is the part that puts people off. VS Code has one built in, so you get a place to type commands without meeting a separate black window first. Everything below goes in that panel.
It also gives you somewhere to put the agent afterwards. Codex ships an extension for VS Code and the editors built on it, so once the CLI works you can run the same agent beside your files, where it can see what you have open. Same account, same project, two ways in.
The install, in order.
Install Visual Studio Code
Download it from code.visualstudio.com (opens in a new tab), open the file, and drag it into Applications on a Mac or run the installer on Windows. It is free and made by Microsoft. Open it once so it finishes setting itself up.
Then open its terminal: the menu is View, then Terminal. A panel appears at the bottom with a blinking cursor. That panel is where every command below goes.
Give your computer the basic build tools
On a Mac, one command installs the standard developer tools, including Git, which is how code is downloaded and versioned. A dialog will pop up; click Install and wait. It is a large download.
$ xcode-select --install
Then install Homebrew, which is how you install almost everything else on a Mac from the terminal. Paste this whole line in one go.
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
On Windows, install Git from git-scm.com (opens in a new tab) and take the defaults. You do not need Homebrew; step 3 has a Windows command of its own.
Install the Codex CLI
There are several routes and they all end at the same program. Pick the one that matches your machine. On a Mac, if you did step 2, use Homebrew.
$ brew install --cask codex
On a Mac or Linux without Homebrew, OpenAI publishes a standalone installer.
$ curl -fsSL https://chatgpt.com/codex/install.sh | sh
On Windows, the same installer has a PowerShell form.
$ powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
If you already have Node installed and would rather use npm, that works too. Nothing else on this page needs Node, so do not install it just for this.
$ npm install -g @openai/codex
Sign in
Move into a project folder and start it. The first run asks how you want to sign in; choose Sign in with ChatGPT and it opens a browser to finish.
$ codex
If you would rather pay per token than use your plan's allowance, the API key route is offered on the same screen. It bills at API pricing and does not include the cloud features.
Add the VS Code extension
In VS Code, open Extensions in the left sidebar and search for openai.chatgpt, which is the extension's marketplace identifier. Install it, then find the Codex icon in the sidebar, or open the Command Palette and run Codex: Open Codex Sidebar.
It signs in with the same account you just used, and it can see the file you have open and the lines you have selected, which the terminal cannot. The same extension covers Cursor and Windsurf. Codex also has separate native integrations for JetBrains IDEs and Xcode.
AGENTS.md, the file that makes Codex yours.
This is the part that matters most and takes the least time. Codex reads a plain Markdown file called AGENTS.md from your repository before it does anything, and treats it as standing instructions. Build steps, test commands, conventions, the things you would otherwise retype at the start of every session.
It is not an OpenAI format. agents.md (opens in a new tab) describes it as "a README for agents", says it is used by over 60,000 open source projects, lists twenty five tools that read it including Cursor, GitHub Copilot, Gemini CLI, Zed and Windsurf, and states that it is now stewarded by the Agentic AI Foundation under the Linux Foundation. One file, most of the agents.
~/.codex/AGENTS.md, read before anything in the project.project_doc_max_bytes, 32 KiB by default. A long file is not a free lunch.~/.codex/config.toml for you, .codex/config.toml for a project. That is configuration; AGENTS.md is instruction.Our systems ship CLAUDE.md, so Codex will not read them yet
Every system in our catalog keeps its standing rules in CLAUDE.md, which
Codex does not look for. We checked the published RFI system while writing this page
and it has no AGENTS.md in it. Clone one, point Codex at it, and the
agent will work without the rules that are the whole point of the repository.
Until we ship both, the fix takes one line at the root of the clone. The rules are Markdown either way, so the same file serves both agents.
$ ln -s CLAUDE.md AGENTS.md
On Windows, or if a symlink causes trouble, copy the file instead. This is a gap in our systems, and it is on us to close.
The five things to know before your first session.
codex from inside the project folder. It reads the repository it is standing in, which is also how it finds AGENTS.md./status during a session shows your remaining limits, which is better than discovering them mid task.When something goes wrong.
/status tells you where you are; the limit banner lists what your plan offers.One habit worth forming immediately
Put the thing you keep re-explaining into AGENTS.md the second time you explain it. Not the third. That file is the difference between an agent that guesses your conventions and one that already knows them, and it costs a sentence each time.
What we checked, and what we did not
Every command and path on this page was read from OpenAI's own documentation and the openai/codex (opens in a new tab) repository, and the install commands appear in both. The AGENTS.md behaviour, the 32 KiB cap and the plan list come from OpenAI's documentation alone.
Nobody here has run Codex. This guide is assembled from primary sources, which is weaker than having used the thing, and worth saying plainly. Tools move faster than pages about them; if a command here fails, the repository above is right and we are stale.