The core

Yesterday ended on an honest count: one passed, one failed. The date fix to parse_date is committed in stash/extract.py (stash is the course’s running example, a small FastAPI feed reader), tests/test_extract.py went green, and then the full suite told you the rest of the truth - tests/test_feeds.py::test_fetch_feed_parses_entries still fails, because fetch_feed parses zero entries out of the Atom feed the test hands it. You deferred that failure on purpose. It’s the worked example for this chapter, and fixing it will take more than one attempt - which makes it the right job to learn on.

First, sit with what the getting-started chapter actually asked of you. You trusted a change to code you didn’t write, made by a process you only watched from the outside. It read some files - which ones, exactly, and how much of them? It edited something - the whole function, or one line? You read the diff after the fact, and that discipline mattered.

But every question about why it made those calls, you answered from its narration, not from the machinery. That trust paid off once. You don’t want to be running on faith for the next one, and after this chapter you won’t have to.

Here’s the whole reason Pi is worth learning specifically, not just filed under “a terminal agent”: how much of your context window an agent’s own machinery spends before you’ve typed a single word is an accounting few agents lay out for you in one place - and Pi’s is small enough to read to the end. Out of the box, on a repo with no instruction files where Pi looks and nothing added, the fixed cost of running Pi is four tool descriptions and one short system prompt. That’s the entire base bill. Read them, and you’ve read everything Pi itself charges you just for showing up; anything you add later - repo instructions, a registered tool - joins that bill visibly, and this chapter shows you where to look. That fixed overhead is the context principle in its smallest form: everything the machinery puts in the window before you decide anything.

This chapter is about doing exactly that, then turning it loose on the feeds defect. Four moves, each one removing a layer of “just trust me”:

• The four tools, exactly - read, write, edit, and bash do precisely what their names say and nothing more, and the exact rules matter more than they sound like they should. Learn the four tools
• The loop, one level deeper - there’s no step limit, and you have two different ways to talk to a run that’s already underway. The feeds fix runs here, twice through the edit-test cycle. Go inside the loop
• See the context - the thing every other agent asks you to take on faith: what’s actually sitting in the model’s window right now, and what the system prompt actually says. See the context
• The tiny prompt, and why - compact by design, and the argument for why that’s not a corner cut. Read the tiny prompt

By the end the feeds test is green and something better is true: you can point at every tool call that got it there, quote the rule each one obeyed, and print the prompt and the window the whole run was executed against. That’s the standard of evidence the rest of this course is built on.