The Codex CLI course

You point OpenAI’s Codex CLI at a repo you did not write, and it is immediately more capable than you are at reading it and less trustworthy than the newest person on your team. Both halves of that have the same cause. Every new session starts cold, knowing nothing about your codebase except what is written down where Codex reads by default - and even what is written down informs; it never enforces.

Within a session, Codex remembers what it read and what you decided together. Close the window and that is gone. The rules file it auto-loads at every session start tells it what the code should do - and the code can ship bugs that file already forbids, which is the exact tension this course works from its first page to its last.

That tension does not go away. Every chapter here picks off one part of it, and every fix charges you something. There is no free move. Learning which price to pay, for which job, is the whole skill.

The running example is budgetcli, a small self-hosted personal-finance API you have just inherited, with your own money in it (166 lines of Python and about 230 lines including tests, config, rules, and README, with a pytest suite and an AGENTS.md at the root). The authoring fixture is not published with the site; every chapter restates the facts it needs so you can adapt the exercise to a disposable repo.

Four principles for every move

This course teaches one framework and uses it everywhere. When you decide what the agent should know, what it may touch, how hard it should think, or what happens when nobody is watching, you are trading among four principles:

• Capability - what the agent can figure out and accomplish with its model and tools. Which model answers, how much reasoning effort a task earns, what can be delegated.
• Context - what information is available when the agent decides, and how good, fresh, and trustworthy it is. The rules it loads, the skills it can call, what the window holds, what a reset throws away.
• Control - what guides execution, enforces boundaries, or allows intervention. Approval policies, sandboxes, profiles, hooks: the wall versus the checkpoint versus the wish.
• Cost - what completing the task consumes: money and tokens, elapsed time, your attention, and rework when it goes wrong.

Context is the organizing theme - the cold-start gap in the opening paragraph is a context gap - and the other three name the levers you pull to close it. More of any one is not automatically better: a bigger window supplies capacity, not understanding; a tighter fence can block the action you needed. The chapters apply these principles where they matter and skip them where they don’t; installation is just installation.

The curriculum

Ten chapters, in reading order. Each one names the part of the gap it attacks and hands you the bill.

1 · Getting started Install, authenticate, and trace one turn of the loop end to end - then ship a reviewed fix, and catch in review a money-rule violation that was sitting there before you arrived.

2 · Sessions & context The window is the only thing the agent carries, and it fills. Resume, fork, branch off, compact, and see exactly what you are throwing away each time.

3 · Approvals & sandbox You have to let it act before it fully knows. Codex splits that into two dials instead of one slider, so you can stop being interrupted without widening the blast radius.

4 · Rules (AGENTS.md) The repo already ships an AGENTS.md, and the code violates it anyway. Audit the real file against the real code, learn what guidance earns, what it costs, and what it can never do.

5 · Models & effort Match the model and the reasoning effort to the task's shape, and watch where deeper thinking stops buying anything. Ends in a table that says which dial for which shape of job.

6 · Subagents The search pollutes the window that has to hold the answer. Push it into a separate, inspectable thread, fan it across worktrees, and pay the coordination cost honestly.

7 · Skills A procedure is knowledge the agent cannot rediscover from the code. Package the bank-import routine as a SKILL.md that fires on recognition instead of waiting for narration.

8 · Extending Codex Two arguments: reach the agent does not have, over MCP, and the fact that nothing else in the loop can actually say no - which is what hooks are for.

9 · Automation The same loop with nobody at the keyboard - approval prompts never fire, disallowed actions just fail. Run headless, wire it into CI, and learn which stage you cannot walk back.

10 · Daily workflow Stack the course's moves into daily reflexes - profiles switched by task shape, briefs that cannot be misread, recovery when a run drifts - and close with an honest synthesis of the whole arc.

What is verified here

Two honesty notes, stated once so the chapters do not repeat them. First: every claim about how Codex behaves was checked against OpenAI’s documentation or published source as of October 2026, and where the two disagreed with each other, the page you are on says so.

Second: every terminal-style transcript in this course is a labeled reconstruction written to show the shape of a run - no real Codex session was recorded to build it. The companion repo is real and small (about 230 lines) and runs on your own machine; it is not published, and there are no per-lesson tags.

How to read it

The chapters form a chain, and reading in order is worth real comprehension - each lesson restates the facts it needs, but the argument accumulates. Drop into a single lesson from a search and it still works on its own.

There is no template stamped on the lessons. Some need a long worked trace, some need one command and a warning, some need a digression into why the tool behaves the way it does. The shape follows the material.

If you want the spec-level view of each primitive rather than the muscle memory, that is Foundations. And if you work across other agents, the Claude Code and OpenCode courses are this one’s siblings: same spine, different tool.

Start where the gap is widest, which is at the beginning. Chapter 1: your first hour with Codex.