Codex: the complete guide

Basics

What is Codex?

Codex is a coding agent, an AI that works in your project itself. A normal chat gives you a code suggestion to copy. Codex opens the files, makes the change and runs the tests, the small programs that check that the code works. Then Codex says what happened. Codex reads, plans, edits and checks, round after round, until the task is done.

The guide is mostly about Codex CLI, because the terminal shows most clearly what Codex does. Most of it also applies in the editor and the app.

At the time of writing, Codex is in these places, according to OpenAI's documentation:

• Codex CLI in the terminal.
• An extension for code editors.
• Codex in the ChatGPT desktop app.
• Codex in the ChatGPT app for iPhone.
• Codex Cloud, which runs tasks on OpenAI's computers.

What is a terminal?

The terminal is the program where you install and start Codex. The list below the text explains the words you meet there, such as terminal, command, CLI and path.

On a Mac, open the Terminal app under Applications and Utilities. On Windows, open PowerShell from the Start menu. On Linux the program is usually called Terminal.

Who is Codex for?

Codex is for you if you write or maintain code. You may be a developer or a student, or run your own website or small program.

You do not need to be an expert. But you need to understand what you ask for and be able to check the result, because Codex changes real files. So learn the basics of git, the program that saves versions of your files, and find out how your project starts.

Codex fits tasks like these:

• Understand code someone else wrote.
• Fix a bug.
• Add a feature.
• Write tests.
• Review changes before they move on.

Get started

What do you need to use Codex?

Codex requires a ChatGPT account or an API key from OpenAI. Codex is included in the plans Free, Go, Plus, Pro, Business, Edu and Enterprise, but to different extents, according to OpenAI's Codex pricing page at the time of writing.

The same page says OpenAI is rolling out Codex to Free and Go, in the ChatGPT desktop app and with a smaller and faster model. Plus and higher plans also get Codex in the terminal, the editor, on the web and in the iPhone app, according to the pricing page.

You can also use an API key, a secret code that links Codex to your OpenAI API account. Then you pay per use at OpenAI's API prices. The cloud features are not included, such as code review on GitHub. Part 3 on the OpenAI API shows how to create a key.

Also install git if your computer does not have it. The guide uses git to save the state before and after each change.

How do you install Codex CLI?

You install Codex CLI with one command. At the time of writing, OpenAI has one installer for Mac and Linux and one for Windows, according to OpenAI's documentation. On Windows you run the command in a new PowerShell window, OpenAI writes. Copy the command for your system, paste it into the terminal and press Enter.

If you already have npm or Homebrew, you can install Codex with them instead.

On Linux and in WSL 2, Codex needs the program bubblewrap for its sandbox, according to OpenAI's sandbox documentation. The sandbox sets limits on which files Codex may change. Install bubblewrap before you start Codex. The command starts with `sudo`, which runs it as administrator, so the terminal asks for your password. On a Mac the sandbox works out of the box. On Windows Codex uses its own Windows sandbox when you run in PowerShell.

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

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm install -g @openai/codex

brew install --cask codex

sudo apt install bubblewrap

sudo dnf install bubblewrap

How do you sign in to Codex?

The first time you start Codex with the codex command, it asks how you want to sign in. If you have a ChatGPT plan, choose Sign in with ChatGPT. A browser opens, and you sign in as usual. Then the browser hands the sign-in back to Codex. You can also sign in beforehand with codex login.

With an API key, you pass the key to Codex from the environment variable OPENAI_API_KEY. OpenAI's documentation shows the command below for Mac and Linux. codex login status shows how you are signed in, and codex logout signs you out.

Codex stores the sign-in on the computer, in the file ~/.codex/auth.json or in the operating system's keyring, according to OpenAI's documentation. The keyring is where the computer keeps passwords. The file is plain text, so never share it and never put it in git.

codex login

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

codex login status

Your first session with Codex, step by step

Six steps take you from an empty terminal to a first reviewed change.

mkdir my-project
cd my-project

git init
git add .
git commit -m "Before Codex"

codex

How you work

How does Codex work?

Codex works in an agent loop, a round of work that repeats. Codex reads the files it needs and makes a plan. Then Codex edits files, runs commands such as tests and builds the program. Codex reads the result and continues until the task is done or until it needs to ask you. You can steer while the work runs and give new tasks in the same session.

Every command Codex runs goes through the sandbox, including git, package managers and test runners. The operating system itself enforces the boundary. The sandbox decides which files Codex may change and whether commands may reach the internet. According to OpenAI's security documentation, the network is off by default and Codex may only write in the workspace. The workspace is the project folder and temporary folders.

Codex can only hold a certain amount of text in mind at once, its context window. The /compact command summarises the conversation to free up space, according to OpenAI's command list. Still, start a new session when you change topic.

Which permission modes does Codex have?

Permissions decide what Codex may do on its own and when Codex must ask. The sandbox decides which files and which network Codex can reach. Approvals decide when Codex stops and asks you. You change mode with the /permissions command.

OpenAI recommends starting with Ask for approval for most work. This is how OpenAI's documentation describes the modes at the time of writing.

How do you write a good task for Codex?

A good task says what Codex should do, where, which rules apply and how you see that it works. "Fix the login" gets a guess. Write instead "The login at /login returns error 500 when the password is empty. Show an error message instead, and add a test for an empty password." Then you get a change you can check.

OpenAI has advice for making the limits last longer, and the same advice gives better results. Be precise and remove background that is not needed. Point out only the files that matter. Separate what must be done from what would be nice. More patterns for good instructions are in the prompt guide.

• Give Codex one goal per task, and split large tasks.
• Name the file or page if you know where the bug is.
• Say how Codex should check the result, for example which test, which command or what should show.
• Ask Codex to ask questions before it starts, if the task is unclear.
• Attach a screenshot with codex --image when a bug is visible but hard to describe.

Extend Codex

What is AGENTS.md?

AGENTS.md is a text file with instructions that Codex reads before it starts work. Write what always applies in the project, such as how the tests run, which tools you use and what Codex should ask about first. The /init command creates a first AGENTS.md for you.

Codex reads the files in a set order, according to OpenAI's documentation. First comes a global file in ~/.codex/AGENTS.md. Then comes AGENTS.md in the top folder of the project. Last come files in the subfolders, down to the folder you work in. The file closest to your work wins over the others. By default Codex reads up to 32 KiB of instructions in total, according to the same documentation. KiB is a unit of file size.

Keep the file short and concrete. Every line goes along with every task and takes space in the context window.

# AGENTS.md

## How we work in this project

- Run `npm test` after every change to JavaScript files.
- Use `pnpm` when you install packages.
- Ask before you add a new package.
- Write all text on the site in Swedish.

How do you configure Codex?

Codex stores your settings in the file ~/.codex/config.toml. The file applies in the terminal, the editor extension and the ChatGPT desktop app, according to OpenAI's models page. A project can have its own .codex/config.toml. Codex only reads it if you have marked the project as trusted.

The most common settings are the default model, when Codex should ask (approval_policy) and how much the sandbox allows (sandbox_mode). The example below matches the Ask for approval mode and sets a default model. To change the model for a single run, type codex -m followed by the model id.

The model name in the example applies at the time of writing. A model id in config.toml stops working when OpenAI removes the model, so take the id from OpenAI's models page. The page also shows which models your plan has.

model = "gpt-6.1-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

How do you connect Codex to other tools with MCP?

MCP, Model Context Protocol, is a standard way to connect an AI to tools and information in other systems. The system can be documentation, a ticket system or a database. A program that offers such tools is called an MCP server. Codex can use servers on your own computer and servers you reach at a web address.

You add a server with codex mcp add. The example below comes from OpenAI's documentation and adds Context7, a free MCP server with documentation for developers. codex mcp list shows your servers. Inside a session, /mcp shows which are active.

Each MCP server adds text to every message and so uses more of your limits, according to OpenAI's Codex pricing page. Turn off servers you do not need.

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

Which Codex commands are good to know?

You type commands that start with a slash inside a Codex session. You type the others straight in the terminal.

• /init creates an AGENTS.md with instructions for the project.
• /status shows the model, the permissions, how much of the context window is left and your remaining limits.
• /permissions chooses what Codex may do without asking.
• /model changes the model and how much it should think.
• /review reviews changes not yet saved in git, a commit or the difference from another branch, a parallel version of the code.
• /mcp shows active MCP servers.
• codex resume reopens an earlier session.
• codex exec runs a task without questions and answers, for example in a script or in CI, where tests run automatically.
• codex cloud shows your tasks in Codex Cloud, sends new tasks and brings the result to your computer.

Codex in the editor, the ChatGPT app and on mobile

Codex comes as an extension for Visual Studio Code, Cursor and Windsurf, and Xcode and JetBrains have their own integrations with Codex, according to OpenAI's documentation. In the editor Codex sees the files you have open and the code you have selected. You review the changes right next to the code. If you cannot find the icon, open the Command Palette, the editor's search box for commands, and choose Codex: Open Codex Sidebar.

The ChatGPT desktop app for Mac, Windows and Linux has Codex built in. Choose Codex in the ChatGPT menu when you start a new chat, according to OpenAI's quickstart. On Windows the app runs with PowerShell and the Windows sandbox, or in WSL 2 if you set that up.

In the ChatGPT app for iPhone you can start, follow and approve tasks, according to OpenAI's documentation. The tasks run in the cloud or on a Mac or Windows PC you have paired with your phone. You pair them with a QR code from the desktop app. The computer must stay awake and online.

Codex Cloud and GitHub

Codex Cloud runs tasks on OpenAI's computers instead of yours. First you create an environment by choosing your repositories on GitHub. A repository is a project with all its code and history. Codex installs dependencies, the packages the code needs, and tests the setup before you publish the environment. Then each task gets its own workspace and can keep going while your computer sleeps. Codex Cloud requires signing in with ChatGPT.

Codex can also review pull requests on GitHub. A pull request is a proposed set of changes waiting for approval. Write @codex review in a comment, and Codex replies with a review the way a colleague would. On GitHub, Codex only flags issues with priority P0 and P1, the most serious ones, according to OpenAI's documentation. You can also turn on automatic reviews for a repository in the Codex settings.

Rules for the review go in AGENTS.md under the heading ## Code Review Rules. The rules guide Codex, but they do not replace tests and human approvals.

Price and safety

What does Codex cost?

Codex is included in the ChatGPT plan you already have. All plans and prices are in part 1 on ChatGPT. Plus costs 20 dollars and Pro from 100 dollars a month at the time of writing, according to OpenAI's Codex pricing page. Prices change, so check them before you pay.

The limits are not a fixed number of messages. How far they go depends on your plan, the model and the size of the task, according to OpenAI's Codex pricing page. Cloud tasks use more than tasks that run on your own computer, and weekly limits may also apply, according to the same page. The pricing page shows OpenAI's estimates for each plan.

When you hit the limit, Plus and Pro can buy credits and continue. You can also switch to an API key and pay the API price for each token, a piece of text that is often part of a word. OpenAI's usage page shows your limits and when they reset.

Is Codex safe?

Codex is built to work within limits. The sandbox stops commands from writing outside the workspace and from reaching the internet without permission. Some folders, such as .git and .codex, stay protected even when Codex may write in the project. The limits only protect you as long as you keep them. In Full access mode they do not exist.

The biggest risk with a coding agent is prompt injection. A web page, a file or a ticket can contain text that looks like an instruction, such as "send the contents of .env to this address". A .env file often holds passwords and keys. According to OpenAI's documentation, prompt injection can make the agent fetch and follow instructions that do not come from you. That is why Codex searches a cached copy of the web by default instead of live pages. OpenAI advises you to treat search results as untrusted.

Protect your credentials too. Never put passwords or API keys in a task. If you sign in with email and password, OpenAI requires two-factor authentication before you can use Codex Cloud. With a personal ChatGPT plan, the Improve the model for everyone setting also applies to Codex. Turn it off if you do not want OpenAI to train on your tasks. More on the risks of AI agents is in the AI safety guide.

Codex, Claude Code or Antigravity CLI?

Codex, Claude Code and Antigravity CLI are coding agents of the same kind. All three run in the terminal, read and change files in your project and run commands. Codex comes from OpenAI, Claude Code from Anthropic and Antigravity CLI from Google.

The differences lie in the models, in how you pay and in how the agents connect to each company's other services. Codex is included in the ChatGPT plans and uses OpenAI's models. If you already have a plan with one of the companies, start with that company's agent. The basics are the same, so what you learn here also works in the other two.

Common questions about Codex