%%{init: {'theme':'base', 'themeVariables': {'fontSize':'15px','lineColor':'#343a40','textColor':'#212529','clusterBkg':'#ffffff','clusterBorder':'#868e96','edgeLabelBackground':'#ffffff'}}}%%
flowchart LR
U["You<br/>(terminal)"] --> PI
subgraph CLIENT["pi (the agent)"]
PI["agent loop<br/>context · sessions"]
TOOLS["tools:<br/>read · write · edit · bash"]
PI -->|invokes| TOOLS
end
subgraph SERVER["model server (localhost)"]
SRV["OpenAI-compatible endpoint<br/>LM Studio :1234 · MLX :8080"]
LLM[/"LLM weights<br/>qwen3-coder · gpt-oss"/]
SRV -->|run inference| LLM
end
PI ==>|"POST /v1/chat/completions<br/>messages + tool defs"| SRV
SRV ==>|"reply: text or tool_call"| PI
TOOLS -->|read / write| FS[("your files")]
classDef client fill:#e7f0ff,stroke:#1c4fd6,stroke-width:1.5px,color:#0b1f4d;
classDef server fill:#d3f9d8,stroke:#2f9e44,stroke-width:1.5px,color:#0b3d1b;
classDef user fill:#fff3bf,stroke:#f08c00,stroke-width:1.5px,color:#5c3a00;
classDef store fill:#f1f3f5,stroke:#868e96,stroke-width:1.5px,color:#212529;
class U user;
class PI,TOOLS client;
class SRV,LLM server;
class FS store;
style CLIENT fill:#f8faff,stroke:#1c4fd6,color:#0b1f4d;
style SERVER fill:#f3fff6,stroke:#2f9e44,color:#0b3d1b;
1 Introduction to PI
You can explain what pi is, why its author built it, and the mental model behind it, enough to know why the later chapters do what they do.
1.1 What pi is
pi is a small command-line AI (artificial intelligence) coding agent, written by Mario Zechner (known online as badlogic, the creator of libGDX). You run it in your terminal, tell it what you want in plain language, and it reads your files, writes and edits code, and runs shell commands to get the job done. In that sense it belongs to the same family as tools like Claude Code or Codex.
What sets pi apart is what it leaves out. pi is built around a single conviction: a modern coding agent does not need to be large to be good. It ships with only four tools (read, write, edit, and bash) and a system prompt under a thousand tokens (Zechner 2025). There is no built-in plan mode, no to-do system, no sub-agents, no MCP (Model Context Protocol) layer, no permission popups. Anything extra is an opt-in extension.
1.2 Why it exists: a world of slop
The motivation is captured in the title of the author’s talk, “Building pi in a World of Slop” (Zechner 2026), and stated plainly in his write-up: existing agents had grown bloated: “Claude Code has turned into a spaceship with 80% of functionality I have no use for” (Zechner 2025). Zechner wanted four things those tools made hard:
- Control over exactly what the model sees in its context.
- Observability: a clean, inspectable record of every interaction.
- Portability across providers, including self-hosted and local models.
- Minimalism: a predictable tool you can reason about end to end.
The bet behind the minimalism is interesting in its own right: today’s frontier models have been so heavily trained on coding-agent behaviour that they already “know” what read, write, edit, and bash are for. Spelling everything out in a giant system prompt buys little and costs context. Strip it back, and a capable model fills the gap (Zechner 2025).
1.3 Why this matters for local models
That portability is exactly what this book exploits. Because pi’s model layer (pi-ai) speaks to any OpenAI-compatible endpoint, and because LM Studio and the MLX server expose such an endpoint for models running on your own Mac, you can swap Claude for a local model by editing one configuration file (Chapter 4). The agent loop, the tools, and the workflow stay identical; only the model’s address changes from a cloud URL (uniform resource locator) to a local one, whether LM Studio’s http://localhost:1234 or the MLX server’s :8080 (Chapter 2).
Running locally has real consequences. Your prompts and source never leave the machine; there is no per-token bill; you can work offline. The trade-off is that an open model on your laptop is generally less capable than a frontier cloud model, and you pay in memory and latency instead of dollars, themes we make concrete in Chapter 2 and Chapter 8.
The broader research context is rich: autonomous agents that resolve real software-engineering tasks end to end (Jimenez et al. 2024; Zhang et al. 2024), surveys that map the large-language-model (LLM) landscape for code and for agents (Hou et al. 2024; Wang et al. 2024), the tool-use and reason-then-act mechanisms that make an agent loop possible at all (Schick et al. 2023; Yao et al. 2023), and the code-generation evaluations used to benchmark these systems (Chen et al. 2021), all collected in the References.
1.4 How pi, the model server, and the model fit together
It helps to separate three things that are easy to conflate. pi is the agent: the program in your terminal that runs the loop, holds the conversation and the four tools, and decides what to do with the model’s replies. It contains no model of its own. A model server (LM Studio or the MLX server) is a long-running process that loads a model’s weights into memory and answers inference requests over the Hypertext Transfer Protocol (HTTP). The model, or LLM, is the set of trained weights the server loads, for example qwen3-coder-30b-a3b-instruct or gpt-oss-20b. One server can hold several models and serves whichever a request names.
The seam between pi and the server is a single stable contract: the OpenAI Chat Completions HTTP API (application programming interface). pi’s model layer (pi-ai) sends a POST to …/v1/chat/completions carrying the conversation and the tool definitions; the server runs the named model and returns the assistant’s reply, which is either text or a request to call one of pi’s tools. Because that contract holds whether the endpoint is LM Studio’s http://localhost:1234/v1, the MLX server’s :8080/v1, or a cloud provider, pi neither knows nor cares which model produced an answer. Changing the model means editing a name in models.json; changing the backend means editing a URL. Nothing in the agent loop moves. Not every model or server implements the tool-calling part of this protocol (Chapter 8), but the request and response shape is the same regardless.
A concrete exchange makes the cycle tangible. Suppose models.json points pi at LM Studio, which is serving a Qwen coder model:
{
"providers": {
"lmstudio": {
"baseUrl": "http://localhost:1234/v1",
"api": "openai-completions",
"apiKey": "lmstudio",
"models": [{ "id": "qwen3-coder-30b-a3b-instruct" }]
}
}
}When you ask pi to “create hello.txt containing Hi”, pi turns the request into a POST to http://localhost:1234/v1/chat/completions whose JSON (JavaScript Object Notation) body carries the conversation and the tool definitions (abbreviated here):
{
"model": "qwen3-coder-30b-a3b-instruct",
"messages": [
{"role": "system", "content": "You are pi, a coding agent…"},
{"role": "user", "content": "create hello.txt containing Hi"}
],
"tools": [
{"type": "function", "function": {"name": "write", "description": "Write a file"}},
{"type": "function", "function": {"name": "bash", "description": "Run a shell command"}}
]
}LM Studio runs the model, which replies not with prose but with a request to use a tool:
{
"choices": [{
"finish_reason": "tool_calls",
"message": {
"role": "assistant",
"tool_calls": [{
"type": "function",
"function": {
"name": "write",
"arguments": "{\"path\": \"hello.txt\", \"content\": \"Hi\"}"
}
}]
}
}]
}pi, not the model, executes that write call on your filesystem, appends the outcome to the conversation, and POSTs again. The model now sees that the file exists and replies with plain text such as “Created hello.txt.”, which carries no tool call, so pi ends the turn. Those two steps are the whole agent loop: the server and the model only ever propose actions, while pi is what actually touches your machine.
1.5 The mental model
Hold these five ideas and the rest of the book follows:
- Harness, not magic. pi is a loop: send the model the conversation and the tool definitions; the model replies with text or a tool call; pi runs the tool and feeds the result back; repeat.
- Four tools. Everything the agent does is
read,write,edit, orbash(Chapter 5). - Context files.
AGENTS.mdadds project rules;SYSTEM.mdreplaces the system prompt (Chapter 6). - Sessions. Every run is saved as a branchable tree you can resume and export (Chapter 6).
- Pluggable models. The model is just a configured endpoint, local or cloud (Chapter 4).
1.6 Where pi runs
pi can run as an interactive terminal user interface (UI), as a one-shot non-interactive command (-p, great for scripts), or as a headless remote-procedure-call (RPC) process that another program drives over stdin/stdout, the closest thing to a “pi server” (Chapter 7).
- In your own words, list one advantage and one disadvantage of pi’s four-tools-only design compared with a feature-rich agent.
- Watch the first ten minutes of “Building pi in a World of Slop” and note one design decision you agree with and one you would question.
- Before reading on, predict which parts of a cloud agent’s workflow would change when you switch to a local model, then check your prediction against Chapter 8.
- Using Figure 1.1, trace the two-step
hello.txtexchange and mark the single arrow where pi, not the model, changes a file on disk. Which layer would you swap to run the same task ongpt-oss-20binstead ofqwen3-coder-30b-a3b-instruct?
- An advantage is predictability and a small, inspectable surface: with only
read,write,edit, andbashplus a sub-thousand-token system prompt, you can reason about exactly what the model sees and does, and you spend almost no context on tool descriptions. A disadvantage is that anything beyond those four tools (plan mode, a to-do system, sub-agents, MCP integrations, permission popups) is not built in and must be added as an opt-in extension, so a feature-rich agent gives you more out of the box. - Open-ended, so several answers are valid. A representative answer: I agree with the bet that frontier models already “know” what
read,write,edit, andbashare for, so a giant system prompt buys little; this keeps context lean. I would question whether dropping permission popups and a built-in plan mode is safe for beginners, sincebashcan run arbitrary commands and a confirmation step would reduce risk. - Prediction check: very little of the workflow changes. The agent loop, the four tools, sessions, and context files stay identical; only the model’s address moves from a cloud URL to a local one in the configuration. What does change in practice is capability, memory and latency cost instead of a per-token bill, and the chance that a given local model or server does not fully implement tool-calling, the failure modes covered in Chapter 8.
- Step one:
POST /v1/chat/completionscarries the conversation and tool defs to the server; the server runs the model and returns awritetool_call. pi (not the model) executes that call, which is theTOOLS --> FS ("your files")arrow in Figure 1.1, the only point where a file on disk actually changes. Step two: pi POSTs again, the model now sees the file exists and replies with plain text and no tool call, so pi ends the turn. To run the same task ongpt-oss-20b, you swap only the model: change the model name inmodels.json. The server (LM Studio) and the agent stay the same.