Install Codex and see the surfaces it runs on

You’ve cloned budgetcli, you’ve spotted a date bug in the CSV importer, and you have no agent yet. Here’s the tension for this lesson, stated once so you can stop worrying about it: installing Codex costs you one command and thirty seconds. Understanding what you just installed costs you two minutes more - and skipping those two minutes is how people spend the next few chapters thinking they’re learning three separate tools instead of one.

Already have Codex on this machine from an earlier project? Run codex --version in any terminal. A version string back means you’re already past this lesson - skip ahead to authenticate.

Getting the binary

The Codex CLI installs from npm as a global package:

npm install -g @openai/codex

On macOS there’s also a Homebrew cask (brew install --cask codex), and a standalone installer script if you’d rather not go through npm at all. They all land the same thing: a codex command on your PATH that you can run from any directory, and codex --version to confirm it’s there. Because the exact commands and supported platforms shift over time, treat the official CLI docs as the source of truth for the current install line on your OS. The command changes with the release notes; the shape of what you’re installing doesn’t.

One agent, several front doors

The framing to set now: the thing you just installed is the agent - but the CLI is only one of the surfaces it runs behind. The same Codex, with the same configuration and the same view of your project, also shows up as an IDE integration and as a headless command you can script. For this chapter you’ll work entirely in the CLI, because the terminal is where the loop is most visible and nothing is hidden behind a panel. But it’s worth knowing from the start that you’re not learning a terminal tool that happens to have an editor mode - you’re learning one agent whose behavior carries across every place it appears.

That matters for a practical reason: every habit and setting you pick up at the CLI this week - how it asks before it writes, what files it reads, the rules you’ll teach it later - follows you into the editor in the last lesson of this chapter and into scripted automation many chapters from now. You configure the agent once; the surface is just where you happen to be standing.

Launch it inside the repo

Like most project-scoped tools, Codex reasons about the directory you start it in. So you don’t launch it from your home folder and then point it somewhere - you cd into the inherited project first and start it there:

> cd ~/work/budgetcli
> codex

Launch from the repo root and the agent can reach the importer, the tests, and the config without you hand-feeding paths; launch from a subdirectory and you’ve quietly fenced it into that corner. For this chapter you want the root, so it can find the CSV-parsing code on its own when you describe the bug.

The agent is installed and running inside budgetcli. But on a fresh machine it doesn’t yet know who you are - and the way you choose to sign in has a consequence worth understanding before you click through it. Next: authenticate.