Codex in Your Terminal

Codex is OpenAI’s coding agent that runs in your terminal, in your actual project folder, on your actual files. Not a chat window you copy out of — it reads the repo, writes to it, runs commands, and you approve or reject what it does.

This page is unusual for this class: it tells you the how. Not because the how matters, but because a broken install is a bad place to practice figuring things out. Getting it running is twenty minutes. What you do with it afterwards is the rest of the year.

Before you start

#Know which machine you’re setting up, and stop if the answer is “the school one.”

Codex itself has almost no prerequisites. It’s a single compiled program — no Node, no Python, no npm install, no admin password. The installer needs curl and tar, which both systems already have.

What you do need is Git and a copy of your repo on the machine, and that’s the part people get stuck on. Assignment 01 lived in a Codespace, so your code is on GitHub, not on your laptop. Codex reads the folder you launch it in — point it at an empty one and it has nothing to work with. Both paths below clone the repo first, deliberately.

Mac

#Codex installed, signed in, and answering questions about your own repo.

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

Windows

#WSL2 installed, then Codex inside it — signed in and reading your repo.

OpenAI’s supported setup on Windows is through WSL2, and that’s what you should use. WSL is a real Linux system running inside Windows: same terminal, same commands, same everything as the Mac instructions above, on the machine you already own.

You need Windows 11, or Windows 10 build 19041 or newer. Winver in the Start menu tells you. The good news is the Ubuntu that WSL installs already includes Git and curl, so there’s no equivalent of the Mac’s command-line-tools step.

If that didn’t work — the other routes

There is no single correct installer. There are four, they all end with the same program on your machine, and if one is blocked or broken you switch. Try them in this order.

School network

#Know whether the network is the problem before you blame the instructions.

This is a real possibility and worth checking first, because a filtered network produces errors that look like broken instructions. Codex needs to reach:

Test it in ten seconds, before installing anything:

curl -I https://chatgpt.com
curl -I https://auth.openai.com

Any response at all — even 403 or 404 — means you got through; that’s the server talking. No response, a timeout, or a certificate error means the network stopped you. After installing, codex doctor checks the same ground and reports it in English.

The workaround is a Codespace, and it’s a genuinely interesting one. In a Codespace the agent isn’t running on the school network at all — it runs in Microsoft’s data centre, and that machine talks to OpenAI. The only thing crossing the school firewall is your browser talking to github.com. If GitHub is allowed and ChatGPT isn’t, that gap is the whole reason to work there. Which is also the answer to “why do we use Codespaces in this class” — see the bottom of this page.

Failing that: install it at home, or on a phone hotspot. Once it’s installed and signed in, it still needs network to run — the model isn’t on your laptop.

Both: is it actually working?

Not “did it install.” Working.

Codex ships with a self-check. Run it from inside your repo:

codex doctor

It reports on your install, whether it can find Git, whether you’re authenticated, and whether it can reach the network — with a ✓, ⚠ or ✗ on each. Read the failures; they’re written in plain English and they tell you which of the steps above didn’t take.

Then the part doctor can’t check for you:

Later on, codex update pulls down new versions — worth knowing, because this tool changes fast enough that a guide written today will be slightly wrong by the time you read it. Including this one.

When it breaks

Run codex doctor first — it names most of these for you.

I’m setting up the OpenAI Codex CLI on [Mac / Windows 11 with WSL2]. Here is exactly what I
ran and exactly what came back:
[paste the command and the full error text, not a summary of it]
Don’t give me a list of five things to try. Tell me what this specific error means, what the
most likely single cause is, how I can confirm that’s the cause before changing anything, and
then the fix. If you’re guessing, say you’re guessing.

Understand it when you can answer

Installing something is not knowledge. These are.

done when Codex is installed on your own machine, signed in with your plan, and it has explained your repo back to you correctly — and you rejected at least one thing it wanted to do, on purpose, because you read it.

On a Codespace instead

No paid plan, or a locked-down laptop? A Codespace is Linux, so the Mac commands work as-is — run the curl installer in the Codespace terminal.

The sign-in is where it gets interesting, and it’s the same trap as the Assignment 01 extra: the normal login hands credentials back to a browser on localhost, and localhost inside a container is not your laptop. So the link you’re given goes nowhere.

There are two ways out. One is to forward the port so the container’s localhost reaches your browser. The other is a flag on codex login built for exactly this situation — machines with no browser of their own. codex login --help lists it. Which one you use is up to you; working out why the default fails is the part worth having.

The other thing to know: a new Codespace is a new machine, so your login is gone again. Figuring out where credentials live and how to stop re-doing this is the follow-up.

What this is for

The tool isn’t the point. Being able to hand work to something that will do it without you watching is the point, and that only works if you can say what you want and tell whether you got it.

Which is the same three boxes as always — Goal, Scaffold, Evaluate. A terminal agent makes the cost of skipping them obvious and immediate: vague goal, and it builds the wrong thing in four seconds instead of four days. No Evaluate, and it announces it’s finished and you have nothing to argue with.

Read this entire repository before answering anything.
Then tell me, in plain English: what this project is, how it’s structured, and the three
things about it that would most confuse someone seeing it for the first time.
Then — don’t fix them — tell me what you’d change and why, and which of your suggestions you’re
least confident about.