Understand one turn of the Codex loop

Before you ask Codex to change code, it helps to see how a single turn works on a question that cannot break anything. Every task - a one-line fix or a multi-file refactor - runs through the same four-beat loop: read, propose, approve, apply. This lesson defines those beats and walks one read-only turn in budgetcli.

Starting facts for this page: budgetcli is the course’s illustrative small FastAPI personal-finance API, with pytest, an AGENTS.md at the repo root, and CSV import in app/importers/csv.py. The authoring fixture is not published with the site, so use a course-host copy if one is provided or adapt the prompts to a disposable repo you own. To run Codex yourself you need it installed and authenticated; reading this lesson needs neither. A common cold-clone failure is ISO dates in test data hitting a day-first strptime format - you will fix that in the next lesson. Here you only ask what the service does and where dates are parsed.

Make your first turn a question, not a command

Each new session starts without memory of prior chats. Codex rebuilds context by reading files (plus whatever instructions load by default, including AGENTS.md when present). A read-only question shows that behavior without touching disk.

The block below is an illustrative reconstruction, not a captured run - accurate about the shape of a turn, not a transcript of one session:

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

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

  budgetcli is a small FastAPI personal-finance API with endpoints
  for transactions, balance, and CSV import. Import lives in
  app/importers/csv.py: parse_csv reads each row and parses date
  and amount into Transaction models. Dates use a fixed "%d/%m/%Y"
  format while sample data in tests uses ISO (2024-03-15) - that
  mismatch raises ValueError on import.

You see which files it opened and a concise map of the service and the date mismatch. It reads first, then answers.

Pricing one read (teaching assumptions)

This course sometimes estimates context size with two rules of thumb - not claims about Codex’s tokenizer:

• 10 tokens per line for Python code
• 4 characters per token for prose and Markdown
• Reasoning about window pressure assumes a 200,000-token context as a round teaching number; substitute your model’s real limit when you have it

Applied here: README.md is short Markdown; csv.py is short Python. Call the read on the order of a few hundred estimated tokens - small against 200k, not zero. Close the terminal and open a new session tomorrow and those same files may be read again unless something durable (docs, tests, rules) carries the fact forward. Context is rented per session until you write it down where the agent loads by default - a theme the sessions chapter develops.

The four beats under every task

Strip away the wording and every Codex turn has the same shape - the four-beat loop other lessons call by name:

1. Read - gather context: open the files and tool results relevant to the request instead of guessing from the prompt alone.
2. Propose - state intent. For a question that is the answer; for a task it is a plan and the edits or commands it wants to run.
3. Approve - the checkpoint between intent and side effects. Where it sits depends on trust and settings. An untrusted folder may start read-only; the common Auto preset pairs a workspace-write sandbox with on-request approvals so in-workspace edits and ordinary commands like pytest flow while boundary crossings (network, writes outside the workspace) pause for y/n.
4. Apply - execute the edit or command, then check work (often by running tests).

When a task goes well, all four beats happen in order. When one goes wrong, a beat was usually skipped - proposed without enough read, or applied without a review you meant to do. Later chapters tune individual beats: rules and skills change what is available at read; models change effort before propose; approvals and sandbox sit on approve.

If something fails later in the track, ask which beat broke before hunting for a feature name.

Watch approve and apply without risking your repo

The interactive trace below walks a generic bug-fix loop (decide, tool, result) with a deliberate double verify. Step through it and count how often verify runs before “done.”

Generic labels in the widget: gather matches read; each act is an edit you would review 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. In this illustrative run, the model starts by reproducing the failure so it has evidence to investigate.

If verify ran twice, the first failure fed back into more gathering - a failed check is signal, not necessarily a broken agent. On code you did not write (or that holds real data), Auto means many in-workspace actions need no prompt; your review of the diff is often the real gate.

Limits of watching one loop

Seeing the shape does not prove a proposal is correct. Codex may read only two files here while a harder bug needs six; the loop does not tell you whether enough was read. A later chapter covers when search and context growth become their own problem.

You know where dates are parsed and how one read-only turn behaved. Next, hand Codex the real bug and close all four beats with a diff you trust - first change.