Learning Path
21 progressive chapters, from the core loop to production engineering
Engine Core
5 chaptersAgent Loop
Heart of the conversation loop
“Every Agent is a loop: stream model → execute tool → feed back”
AgentHarness & Durable Session
Above the loop: orchestration & durability
“Result<T,E> never throws — turn snapshot vs harness config”
Compaction & Branch Summarization
Infinite work in a finite window
“Context always fills up — the cut-point decides what survives”
Session JSONL Tree
A session is a durable tree, not a log
“Branch in place — never copy a file”
Built-in Tools
Four default tools; the rest is extension territory
“Operations interfaces behind every tool; mutations serialized”
Unified LLM API
4 chaptersModels & Provider Abstraction
One stream interface, 40 providers
“Models route to their Provider; header merge has a priority chain”
Wire Protocols & Lazy SDKs
Each API speaks its own dialect
“lazyStream wraps async auth+SDK loading behind a synchronous stream”
Auth & OAuth
Provider-owned credentials & OAuth flows
“Stored credential beats env; failed refresh never silently falls back”
Streaming, Partial JSON & Retries
Tolerant streams & constrained sampling
“Errors are events, never thrown: stopReason 'error'/'aborted'”
Coding-Agent & Extensibility
6 chaptersCLI Modes & Dispatch
From bin entry to interactive/print/rpc/json modes
“main.ts dispatches the Mode; project trust gates before the prompt”
AgentSession Orchestration
The harness pi actually uses
“Event subscription + session persistence + model management in one”
System Prompt, Skills & Context Files
The system prompt is an assembly pipeline
“AGENTS.md walks up from cwd; skills follow agentskills.io”
The Extension System
Self-extensibility: one loader powers built-ins & users
“~40 lifecycle events; jiti + VIRTUAL_MODULES for the Bun binary”
Model Runtime, Provider Composition
Builtin catalog + extension providers
“composeModelProvider merges extension providers with built-ins”
Pi Packages & Model Catalog
pi install/update/list over npm: & git:
“min-release-age=2, exact pins, --ignore-scripts; never edit models.generated.ts”
Surfaces & UI
3 chaptersInteractive TUI
Six thousand lines to make the loop feel instant
“Enter→steer, Alt+Enter→follow-up; dialogs, themes, footer telemetry”
The pi-tui Engine
Differential rendering with zero dependencies
“Synchronized output for atomic frames; paste markers survive as atomic graphemes”
Settings, Trust, Telemetry & Output Guard
Project trust gate & TUI output integrity
“output-guard owns stdout so the model never corrupts the TUI”
Backend & Engineering
3 chaptersRPC Mode & pi-server
Beyond the terminal: JSONL RPC & a supervisor daemon
“One pi --mode rpc child per instance; length-delimited IPC over a Unix socket”
SQL Session Backend
JSONL tree, but queryable
“WAL + busy_timeout + FULL sync for concurrent agent processes”
Evals & Supply-Chain Hardening
Behavioral evals & a hardened monorepo
“Lockstep versioning; never edit models.generated.ts; lgtm gates”