Pi under the hood: a minimal harness built around session trees and primitives
How Pi keeps its core small while supporting extensions, skills, packages, and multiple interfaces, plus the unique design choice behind it and a lesson for harness builders.
Pi describes itself as a minimal agent harness. That is not marketing modesty; it is the core design decision. Instead of shipping every workflow as a built-in product feature, Pi focuses on a small runtime and gives users primitives they can compose: extensions, skills, prompt templates, themes, and packages.
The result is a harness that feels less like a fixed application and more like a programmable environment for coding agents. To understand why that works, you have to look at how Pi models sessions, turns, and interfaces.
A small core with the same engine everywhere
Pi can run interactively in a terminal UI, as a one-shot print/JSON command, as an RPC process, or as an in-process TypeScript SDK. These modes look different from the outside, but the project is explicit that they share the same agent and session mechanisms.
That is an important architectural constraint. It means features like tool execution, context assembly, compaction, and branching do not belong to “the TUI” or “the SDK”; they belong to the core runtime. Interfaces render and control the engine, but they do not become separate implementations of it.
This keeps the harness coherent as it grows: a behavior fixed in the session/agent layer benefits every mode.
How Pi models a conversation
Pi’s session model is one of its defining traits. A session is not just a linear transcript; it is a tree of entries. Each entry has an ID and a parent, and the active branch (the path ending at the current entry) is what supplies history for the next model request.
This gives Pi a durable structure for things agent users actually do:
- Continue from earlier points without losing the rest of the history.
- Branch when exploring alternatives.
- Fork or clone selected history into a new session.
- Compact by inserting summary entries that replace older messages in model context while keeping original entries in the session tree.
The session file format (JSONL) and this tree model make conversation state inspectable and replayable. Instead of treating history as ephemeral chat text, Pi treats it as data the runtime can navigate.
The turn loop and context assembly
A submitted message is added to the active branch. Pi builds a model request from the base system prompt, discovered context files, active branch history, available tools, skills metadata, and model settings. The provider streams a response that may include text and tool calls.
Pi records the response, executes each requested tool, records results, and starts another turn if more work is pending. Steering messages can enter after the current assistant turn, while follow-up messages wait until the agent has finished its pending work. Aborting stops the run and returns queued messages to the editor.
Context assembly follows the same philosophy as sessions: structured and layered. Full skill instructions load on demand, prompt templates expand editor input into user messages, and extensions can transform context or add instructions. The harness tries to give the model what it needs now, while keeping the core mechanism simple.
Extensions as programmable surfaces
Pi’s extension system is where its minimalism pays off. Extensions are TypeScript modules loaded into the Pi process that can register tools, commands, shortcuts, providers, event handlers, renderers, and UI elements. In practice, this means workflows that other harnesses ship as built-in modes (subagents, plan mode, permission gates, custom compaction behavior, custom editors, and more) can be implemented as extensions or packages.
That shifts the product boundary. Pi does not need to predict every developer workflow; it needs to provide stable hooks into the loop, context, tools, and interface. The ecosystem can then carry opinions.
The unique secret point: the session tree is the product core
The secret that makes Pi’s minimalism viable is that Pi treats the session tree as the durable center of the harness.
When conversation state is a navigable, persistent structure (not just a scrolling buffer), many capabilities become natural: branching, forking, replay, compaction summaries, multiple interfaces, and reproducible automation. The core can stay small because the runtime operates on a strong primitive: a tree of events/messages with a current pointer.
This is why Pi can support interactive, print, RPC, and SDK modes without fragmenting behavior. They are different doors into the same session engine. Minimal core does not mean minimal capability; it means the capability is organized around a few powerful abstractions.
Lesson for anyone building a harness
The transferable lesson from Pi is: invest in state primitives before you invest in features.
If your harness has a clear, durable model of conversation and execution state, you can add interfaces, extensions, and automation without duplicating logic. If state is implicit or UI-bound, every new mode becomes a partial rewrite.
For builders, that means:
- make session history structured and addressable,
- separate state transitions from presentation,
- define a small set of extension points that touch real lifecycle events,
- and let higher-level workflows compose from those primitives.
Pi shows that a harness can feel flexible not because it has everything built in, but because its core objects are good enough to build on.
Sources
Weekly series
Read the posts in order:
- Adding a blog to my personal site (without starting over) - 2026-11-11
- Why PostHog is one of the first tools I add to a new product - 2026-11-18
- Anatomy of a coding harness: what makes AI coding agents work - 2026-11-11
- Context management in coding harnesses: what gets sent, and why it matters - 2026-11-18
- Goose under the hood: an MCP-native harness with a protocol at the center - 2026-11-11
- Pi under the hood: a minimal harness built around session trees and primitives (this post) - 2026-11-18
- OpenCode under the hood: one loop, many models, real environment feedback - 2026-11-11
- DeepSeek Harness under the hood: everything is a plugin, and the log is the contract - 2026-11-18
Previous: Goose under the hood: an MCP-native harness with a protocol at the center Next: OpenCode under the hood: one loop, many models, real environment feedback