Understand one turn of the Pi loop

You’re authenticated, sitting at a live prompt inside stash, the course’s running example, a small FastAPI feed reader (install and bring your own key get you here if you’re starting fresh), and the date bug behind your mis-sorted reading queue is right there. Hold off for two minutes anyway. If you’ve spent any time with Claude Code or Codex, you already have a mental model of “the agent loop” - read, propose a plan, wait for you to say yes, then apply. Four beats. Watch this lesson for the pause between “propose” and “apply”; it never comes. Pi’s loop has three beats, and the one it drops is the one you’re used to trusting.

Make your first turn a question

stash is new to Pi too - it knows nothing about the codebase it hasn’t read yet. A read-only question costs you nothing and shows you exactly how the loop behaves before you ever ask it to change something:

> what does this service do, and where do saved articles get their dates from?

  bash: rg -l "date" stash/
  → stash/extract.py
    stash/feeds.py
    stash/models.py

  read: stash/extract.py
  read: stash/feeds.py

  stash is a small FastAPI feed reader - you sync a feed, it fetches
  the XML, pulls out each entry's title, link, summary, and updated
  date, and stores the rows in SQLite. Dates flow through feeds.py
  into parse_date() in extract.py, which tries two strptime formats
  and returns None if neither matches - so a date carrying a
  timezone offset never parses at all. That's almost certainly
  where your queue-sorting bug lives.

Watch what one turn actually bought you. Pi didn’t guess from the prompt - it ran a real shell command to find files that mention dates, read the ones that looked most relevant, and came back with an answer and a lead on your bug. Gather context, then answer: that’s the loop, once, with nothing written and nothing run that could touch your data. It used the same tools it will use for the real fix.

The loop, stripped to its mechanism

Stated as plainly as it can be: the model responds, any tool calls it made get executed, the results go back into the conversation, and the model responds again. It repeats for as long as it keeps calling tools, and it stops the moment a response comes back with none. There’s no step counter and no built-in ceiling on repeats. A five-line fix might close in one round trip; a gnarlier bug might take a dozen tool calls before the model has enough to work with.

Compare that to the four-beat shape you may already know - read, propose, approve, apply. Pi’s loop has three of those beats, not four:

1. Gather - the model calls a tool (bash, read) to see what it needs to see.
2. Act - it calls a tool that changes something (write, edit, or a bash command that mutates state).
3. Verify - often another tool call, checking the result of the last act - and if verification fails, straight back to gather, not a dead end.

The missing beat is approve. Nothing in that list stops and waits for your yes. By default, Pi has no permission gate at all - every tool call it decides to make, including ones that write files or run arbitrary shell commands, executes immediately, without asking. Read, propose, approve, apply collapses into gather, act, verify, and the step you’re used to trusting before anything happens on disk simply isn’t there.

Predict the next demo before you run it: a small fix, traced one step at a time, should show exactly gather → act → verify → done, with no fifth step anywhere that waits on you. Here’s that same shape on a fix that has nothing to do with stash yet, so you can check the prediction cleanly before spending it on the real bug. (The stepper’s tool labels are generic - run:, read:, edit:, reply: - standing in for Pi’s bash, read, edit, and a plain response; the shape is the point, not the labels.)

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.

The stepper’s last note - every tool result staying in the window - is a real cost, and this lesson deliberately stops at naming it. What the accumulating window actually holds, and how to read it live down to the byte, is the observability lesson’s job, one chapter ahead. For now carry only the loop’s shape.

Pi is YOLO by default - there is no permission prompt

Out of the box, Pi does not ask before it writes a file or runs a shell command. Every tool call in the loop above - reads, writes, edits, arbitrary bash - executes the instant the model decides to make it. This is a deliberate design choice: Pi’s stance is that a confirm-before-run gate mostly slows you down without stopping much, and that if you want guardrails, you should build the specific ones you actually want rather than click through a generic one every time.

For this lesson that’s fine - you only ran a read-only question. It stops being fine the moment you hand Pi something that touches real data, which is exactly what the next lesson does. If you want real isolation before then rather than just discipline, run Pi inside a container or VM: Pi’s author calls the security measures in other coding agents mostly security theater, and Pi’s security docs name running Pi entirely inside a container, VM, or sandbox as usually the strongest practical option.

You’ll build a lighter, in-session version of that - a damage-control gate - a few modules from now. Until either exists on your machine, the only thing standing between a bad instruction and your filesystem is you reading what you’re about to ask for.

You’ve now watched the loop close once, cleanly, with nothing at stake, and you know its shape: gather, act, verify, repeat until it’s done. You also know the one beat it doesn’t have. Those are the two things to carry into the real fix - what it does when nobody stops it, and what it never does on its own, which is ask. Next: ship your first fix.