Pi's source is compact enough to trace, but the code becomes much easier to read once three ideas are clear: the tool-call protocol, the package boundaries, and the difference between durable session state and model context.
Orientation
1. Pi's design argument
Read Mario Zechner's Pi overview.
The overview covers Pi's product choices in one pass: multi-provider model support, normalized events, four built-in tools, a small prompt, trusted extensions, and the features left outside the core product.
2. Source and documentation
Browse earendil-works/pi and
open the current documentation.
Start with packages/ai, packages/agent, packages/coding-agent, and
packages/tui. Follow one request through provider conversion, streaming, the
agent loop, tool results, and session persistence.
3. Source study notes
Read the Pi source study notes.
The notes trace the core mechanisms against a pinned Pi snapshot: event-stream Promises, canonical completion, nested loop control, steering and follow-ups, tool validation, append-only branching, compaction, extensions, tmux, and the security boundary. Five integrated exercises test the interactions.
Tool-call protocol
4. Anthropic's tool-use contract
Focus on the assistant tool request, the paired result id, and the next model request. Pi normalizes several provider encodings around this same semantic contract.
Sessions, compaction, and extensions
5. Session file format
Read the session-format documentation.
The JSONL entries form a tree through id and parentId. The selected leaf
determines the active path while every branch remains durable.
6. Compaction and branch summarization
Read the compaction documentation.
Trace the summary entry, firstKeptEntryId, safe cut points, retained raw
suffix, repeated compaction, and token trigger. Compaction changes future model
context while the raw session remains available.
7. Extensions and security
Read the extension documentation and the security boundary.
Extensions are trusted TypeScript in the Pi process. They can register tools, intercept calls, alter context, add UI, and persist state. OS containment owns filesystem, process, network, and credential isolation.
Product philosophy
8. CLI tools, MCP, and on-demand context
Read the design essay and the accompanying benchmark.
Pi favors a small built-in tool surface, command-line programs, documentation loaded when needed, and optional extensions. The benchmark helps separate protocol effects from descriptions, ergonomics, model familiarity, and task design.
How to study the path
For each mechanism:
- Write the expected message or state sequence.
- Read one small source slice and correct that trace.
- Add one failure, such as response truncation, invalid tool arguments, cancellation, an orphaned tool result, or compaction at an unsafe boundary.
- Name the component that owns each decision.
- Check the resulting durable history and the next model context separately.
The source study notes provide the shared vocabulary and the integrated traces. The external readings supply design rationale, API contracts, and current documentation.