Understand one turn of the Codex loop

You’re authenticated and standing at a live prompt inside budgetcli, and your instinct is to throw the date bug at it right now. Hold that for two minutes. Every task you’ll ever give Codex - from this date fix to a multi-file refactor several chapters from now - runs through the same small loop, and the cheapest possible place to see that loop is on a question that can’t break anything. Watch it once here and the real change in the next lesson will feel like something you’ve already done. That’s the tension for this whole lesson, in one line: the loop is always running whether you watch it or not, and the only thing a rushed first turn buys you is not knowing what just happened.

Make your first turn a question, not a command

You’ve just inherited this repo. So has Codex - it knows nothing about budgetcli that it hasn’t read yet, and that’s true at the start of every session, not just this first one. A read-only question costs you almost nothing and shows you exactly how it gathers context before it’s ever allowed to write:

> what does this service do, and where does it parse dates out of imported CSVs?

  • Read README.md, src/budgetcli/importers/csv.py                (2 files)

  budgetcli is a FastAPI service for personal budgeting, about 41
  Python files and 6,200 lines - accounts, transactions, CSV import
  from three banks, and monthly reports. CSV import lives in
  src/budgetcli/importers/csv.py; that's where each row's date string
  is parsed into a date before the transaction is stored. All three
  banks are parsed with a single fixed date format, which won't hold
  once one of them writes dates differently than the other two.

Watch what that one turn bought you. Codex went and read files - you can see which ones - and came back with a map: what the service is, where the CSV importer lives, and even an early hunch about why dates might be going wrong. You’ve learned the lay of the land for your ticket, and you’ve learned something more useful - how this agent behaves when it needs context. It reads first, then answers.

That read wasn’t free, and it’s worth pricing once so the cost stops being invisible. README.md is 180 lines, csv.py is 210 - 390 lines together, or about 3,900 estimated tokens at 10 tokens per line, sitting in the window before a single character of code changed. That number isn’t large against a 200,000-token window. It’s also not zero, and it buys you nothing next session - close this terminal and reopen budgetcli tomorrow, and Codex reads those same 390 lines again, because nothing about this turn was saved anywhere it will look. Context is rented, not owned, until you decide to write it down somewhere the agent reads by default - which is exactly what a later chapter shows you how to do.

The four beats under every task

That single turn is the whole loop in miniature. Strip away the specifics and every Codex turn has the same shape:

1. Read - it gathers the context it needs, pulling in the specific files relevant to your request rather than guessing from the prompt alone.
2. Propose - it tells you what it intends to do. For a question that’s an answer; for a task it’s a concrete plan and the exact edits or commands it wants to run.
3. Approve - the checkpoint between the agent’s intent and your filesystem. Codex starts in its Auto posture: it reads, edits, and runs commands inside your working directory on its own, and stops for a y/n on the moves it judges consequential - anything reaching outside the project, onto the network, or otherwise hard to walk back. That pause is the leash: the one moment in the loop where nothing happens until you say so. How much it asks is a dial, and you’ll set it deliberately in the approvals chapter.
4. Apply - only after you approve does it actually write the edit or run the command - and then it checks its own work, typically by running whatever verifies the change.

Read, propose, approve, apply. When a task goes well it’s because all four beats happened in order; when one goes wrong it’s usually because a beat got skipped - it proposed without reading enough, or applied something you didn’t really look at. Learning to see those beats is most of what makes you good at driving the agent, and you just watched a clean instance of the first two on a question where a wrong answer couldn’t cost you anything.

Worth knowing now, because it tells you what the rest of this course is: there is no sixth beat coming. Every chapter from here tunes one of these four. Rules and skills change what the agent has when it reads. Models and reasoning effort change how hard it works before it proposes. Approvals, the sandbox and hooks all sit on approve, deciding what gets to happen without you. Subagents and headless runs change who is standing at the loop at all. When something goes wrong later in the week, the useful first question is never “which feature do I need” but “which of these four beats failed”, and that question only has four answers.

Four questions worth asking about any move

Those four beats describe how a turn happens. What you also need is a way to judge whether a given turn was worth it - and that’s a different, smaller set of questions, four of them, that you’ll keep asking for the rest of this course:

• Tokens - what did this move put in the window, or spend? You just measured one: about 3,900 estimated for the read-only question above.
• Turns - how many round trips did it take before the job was actually done? One, so far - you’ve only asked a question.
• Blast radius - what could this move touch if it turned out to be wrong? Nothing, this time - a read changes nothing on disk. That changes the moment Codex is allowed to write.
• Recurrence - does this pay off again next session, or do you pay for it again? You already know the answer for a plain question: no. Tomorrow, the window is empty and the read happens again.

Four questions, reused everywhere, never a fifth. Every later chapter is, underneath its own topic, an answer to one of these four for one particular kind of move. You now have the only ruler this course uses.

Watch the loop finish, without risking anything

You can watch the other two beats - approve and apply - close without spending any of your own budget on it. Here’s a bet before you start: this looks like a one-line fix, the kind that should take a single trip around read, act, verify. Step through the trace below and count how many times verify actually runs before the loop reaches “done.” If your instinct says once, you’re about to be wrong in an instructive way.

The labels below are the generic ones for the loop - gather is your read beat, and each act is an edit that in Codex you’d be seeing either at an approve prompt or in the diff afterward:

Step 1 / 8You hand over a task

Reset← BackNext →

you→gather context→act→verify↺→done

> The login test is failing on main. Fix it.

(prompt enters the window)

Your message lands in the context window. The model reads it and decides what it needs first - it can’t fix what it hasn’t seen, so the first move is almost never an edit.

Verify ran twice, not once. The first pass failed - a test fixture had a hard-coded timestamp that had quietly gone stale - and that failure didn’t end the loop, it fed straight back into gathering more context with better information. A failed verify is useful signal: the loop is working exactly as designed, one lap longer than the ticket looked like it needed.

The reason this matters on budgetcli specifically: this is your financial data, in code you didn’t write. The approve beat is not a formality you’ll want to rush past - when Codex does stop to ask, it’s the last thing standing between a confident-sounding wrong edit and your ledger. Lead with a write as your very first move and you’d be trusting a tool you’ve watched do nothing yet, on a codebase it hasn’t shown you it understands. Spend one read-only question first and that trust is earned instead of assumed.

What watching one loop does not tell you

Seeing the shape of a turn is not the same as knowing how much to trust a given one. The four beats can all happen, in order, and the read at the front can still be shallow - Codex only opened two files just now; a harder bug might need six, and nothing about the loop’s shape tells you whether it opened enough. That judgment call is yours every time, and a later chapter is entirely about the failure mode where the search itself gets too big and starts crowding out the answer it was supposed to produce. Knowing the loop’s shape makes the agent legible. It doesn’t make every proposal correct - that’s still your job at the approve beat.

You now know where the date parsing lives and how the agent behaves when it works - which is exactly what you need to hand it the actual bug and watch all four beats close on a real fix, this time with something real riding on the approve beat. Next: ship your first reviewed change.