Setting Up Codex

Time to get Codex running on your own computer. We'll install the Codex CLI, sign in, open it in a project folder and give it a first task that can't break a thing. Then we'll look at how Codex asks permission and where the AGENTS.md file fits in.

If you followed the Claude Code installation lesson, a lot of this is gonna feel familiar.

What You'll Need#

• A terminal. The same one you used for Claude Code.
• A ChatGPT Plus plan or higher (or an OpenAI API key, more on that below). The Codex CLI this lesson installs isn't included in the Free or Go plans.
• A project folder to practice in. Ideally one that's tracked by Git, which you'll learn all about in the GitHub module. A small practice project is perfect.

Step 1. Install the Codex CLI#

OpenAI's official README gives one main install command for each kind of computer.

Step 1a. On Mac or Linux#

Open your terminal and run this.

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

Step 1b. On Windows#

Open PowerShell and run this.

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

Other Ways to Install#

If you already use a package manager, these work too.

# With npm (needs Node.js, like in the Claude Code lesson)
npm install -g @openai/codex
 
# With Homebrew on a Mac
brew install --cask codex

You only need ONE of these. If you're not sure, go with the main installer.

Step 2. Sign In#

First, move into your project folder. If your project lives in a folder called my-project, it looks like this.

cd my-project

Now fire up Codex.

codex

The first time you run it, Codex asks how you want to sign in. Choose Sign in with ChatGPT. A browser window pops open, you log in to your ChatGPT account, and the browser hands your login back to Codex. Donezo.

If you ever need to sign in again on purpose, run codex login. To check which account you're on, run codex login status.

Step 3. Look Around Before You Ask for Anything#

When Codex starts up, it shows a lil welcome box with the model it's using and the folder it's working in. Below that you'll see a short list of commands you can type. They're called slash commands because they start with /.

Here are the ones worth knowing on day one.

Type /status now. It's an easy way to make sure Codex is pointed at the right folder before you ask it to do anything.

Step 4. Give Codex a Safe First Prompt#

Make your first prompt a question. Questions only read files, so nothing on your computer gets touched. OpenAI's own quickstart suggests this one.

Tell me about this project

Codex reads through your folder and explains what the project is, how it's organized and which files matter. Read the answer and see if it lines up with what you know about the project.

Once that feels comfortable, try a teeny, low-risk change.

Add a short comment at the top of the main file explaining what it does

When Codex finishes, type /diff to see exactly what it changed. Like it? Keep it. Don't like it? Ask Codex to undo it, or use Git to throw the change away.

How Codex Asks Permission#

Codex keeps you safe with two layers working together.

1. The sandbox decides what Codex is technically able to do. It's a fence enforced by your computer's operating system.
2. The approval policy decides when Codex has to stop and ask you before acting.

The Default Setup#

When you start Codex in a folder tracked by Git, it recommends a setup OpenAI calls Auto. In Auto, Codex can read files, edit files and run commands inside your project folder on its own. It has to ask you before it edits anything outside the project folder or uses the internet. Internet access for commands is off by default.

In a folder that isn't tracked by Git, Codex recommends read-only instead, so it can look but can't change anything. Depending on your setup, Codex may also start read-only until you tell it you trust the folder.

Changing What Codex Can Do#

Type /permissions whenever you want to switch. These are the two you'll use most as a beginner.

• Auto. Codex works freely inside your project and asks before going outside it.
• Read Only. Codex can look around and answer questions, but it can't edit. Great for exploring a project or planning.

You can also pick these when you start Codex.

# Read-only, asks before stepping outside the sandbox
codex --sandbox read-only --ask-for-approval on-request
 
# The Auto setup, spelled out
codex --sandbox workspace-write --ask-for-approval on-request

Where AGENTS.md Fits In#

Remember CLAUDE.md from the Claude Code lessons? That's the file Claude Code reads at the start of every session so it knows your project's rules. Codex has the same idea, and its file is called AGENTS.md.

Codex reads AGENTS.md files before it does any work. You can put them in a few places.

• Your project folder. An AGENTS.md at the top of your project holds that project's rules. This is the one you'll use most.
• Your Codex home folder. A file at ~/.codex/AGENTS.md holds personal preferences that apply to every project.
• Subfolders. A big project can have extra AGENTS.md files deeper in, for rules that only apply to one part. Codex reads the ones between the top of your project and the folder you started it in, and when rules disagree, the file closest to that folder wins.

The easiest way to start one is to run /init inside Codex. It creates an AGENTS.md starter you can edit. A simple one might look like this.

# AGENTS.md
 
## Project rules
- This is a small website built with plain HTML and CSS.
- Run `npm test` after changing any JavaScript file.
- Ask before adding new packages.

Codex combines these files up to a size limit (32 KiB by default), so keep them short and focused, same as a good CLAUDE.md.

Troubleshooting Common Problems#

"command not found: codex"#

Close your terminal completely and open a new one. Still nothing? Run the install command again and keep an eye out for error messages.

The browser didn't open to sign in#

Run codex login to start the sign-in again. Make sure you're logging in to the same ChatGPT account that has your plan.

Codex won't edit anything#

Type /status to see your current permissions. If you're in Read Only, use /permissions to switch to Auto. If your folder isn't tracked by Git, Codex may be recommending read-only on purpose.

TL;DR#

• Install the Codex CLI with the official installer for your computer, then run codex
• Sign in with your ChatGPT account through the browser (an API key works too)
• Start with a question like "Tell me about this project" before asking for changes
• The sandbox and the approval policy work as a team, and Auto lets Codex edit inside your project while asking before it goes outside
• AGENTS.md is Codex's version of CLAUDE.md, and /init makes one for you

What's Next?#

You've now got both Claude Code and Codex installed. Next lesson we'll put them side by side and talk about when you might reach for each one...