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. This is the shortest lesson in the chapter, because getting Codex onto your machine genuinely is a one-liner — but there’s a framing worth setting on the first run, because it changes how you’ll think about the tool for the rest of the week.

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.

One agent, several front doors

Here’s 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 and into automation in a much later chapter. 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.