Install Codex and see the surfaces it runs on

You need the codex command on your machine before any lesson that drives the agent from a repo. The install itself is short; the useful part is knowing what you installed: one agent that can run in the terminal, in an editor, or headless, with shared configuration.

Already have Codex? Run codex --version. A version string means you can skip to authenticate or the loop.

Getting the binary

The Codex CLI installs from npm as a global package:

npm install -g @openai/codex

Caution

If npm install -g fails with an EACCES permissions error, do not reach for sudo. Point npm’s global prefix at a directory you own, or use the Homebrew cask below instead - a sudo-installed global package causes stranger problems later than the one it solves.

On macOS there is also a Homebrew cask (not a formula):

brew install --cask codex

A standalone installer script exists if you prefer not to use npm. All paths land the same thing: a codex command on your PATH. Platform lists and current install lines change with releases; use the official CLI docs as the source of truth for your OS.

Verify the shell can find it:

> codex --version

A version string means you are done. command not found usually means the binary is outside your PATH - npm config get prefix shows where npm put global bins; add that directory’s bin to your shell config if needed.

One agent, several front doors

What you installed is the agent, not merely a terminal chat tool. The same Codex, with the same configuration and project view, also appears as an IDE integration and as a headless command you can script. This chapter uses the CLI because the loop is visible there: reads, proposals, and diffs are not hidden behind a panel.

Configuration is per agent, not per surface. How sign-in works, which files load at session start, and how approvals behave later all follow you from the CLI into the editor and into automation chapters.

Launch it inside the repo

Codex scopes work to the directory you start it in. cd to the project root (for budgetcli, the course’s running example, a small self-hosted personal-finance API in Python and FastAPI: the folder that contains AGENTS.md and app/), then start the agent there:

> cd ~/work/budgetcli
> codex

From the root, the agent can reach importers, tests, and rules without you pasting paths. Starting in a subdirectory quietly limits what it sees first.

On first contact with an unfamiliar folder, Codex may treat the workspace as read-only until you confirm trust. That is intentional. The loop lesson explains what changes once the directory is trusted and how the default Auto posture behaves.

Next step: sign in so the agent can reach a model - authenticate.