Skip to content

Pi: A small core with explicit ownership

Study Pi through its reusable loop, session tree, extensions and host responsibility.

Updated View as Markdown

Pi is a useful study of a small, extensible coding harness inside a broader agent toolkit. Its coding application deliberately leaves features such as built-in planning and subagents to customization rather than requiring one opinionated workflow.12 That shifts important design decisions to the person or application hosting it.

The study uses a pinned repository snapshot checked October 11, 2026. The documentation screenshot is an interface example, and the scenario below is original teaching material. Neither is a comparative benchmark.

Follow the layers, not just the terminal

The toolkit separates model access, an agent loop, terminal presentation and the coding application. Figure 1 emphasizes the session machinery and host responsibilities that make the CLI more than a text interface.

System anatomyA reusable loop, an authoritative session tree and an extensible host
Host applicationChoose the model, resources and tools
  • Interface

    Interactive terminal, SDK host or RPC client.

  • Resources

    Context files, skills, prompt templates and extensions.

  • Host permissions

    The operating-system authority of the launching process.

AgentSession and loopCoordinate one conversation
  • Session manager

    Select the active branch and reconstruct model context.

  • Agent loop

    Transform context, convert messages and call the provider.

  • Events and tools

    Record responses, execute tools and incorporate results.

Persistence and customizationKeep history distinct from active context
  • Entry tree

    JSONL entries retain branches and parent relationships.

  • Compaction

    Summaries change later requests; original entries remain.

  • Extensions

    In-process modules register behavior and manage their lifecycle.

Figure 1. Latent Light synthesis of inspected agent-loop code and Pi session, SDK and extension contracts.3456

In the inspected loop, context transformation precedes conversion to model-compatible messages. Tool results feed later requests, and queued steering and follow-up messages enter at different points. A host can therefore control what reaches a model without making the model itself responsible for session bookkeeping.3

The coding layer supplies the project resources and user workflow. Keeping the loop reusable makes it possible to embed the mechanism, but an embedded loop still needs an application to define tools, scope and a completion check.

A session is a tree; context is a selected path

Pi stores persistent sessions as JSONL entries with parent relationships. The active branch supplies history to the next model request. Moving through the tree does not erase the branch left behind; forking can make a separate session. Compaction inserts a summary for subsequent requests while retaining the original entries.4

This is a useful distinction for exploratory work. Two attempted fixes can remain related history without both being sent wholesale to the next request. However, choosing another conversation branch does not roll back files or external services. Our design lesson is to reconcile the environment whenever an alternative history is selected.

The SDK makes SessionManager authoritative for persisted context. Replacing a message array on an agent object is not equivalent to reconstructing the session through that manager. Runtime replacement also requires clients to rebind subscriptions to the new session.5 This is an ownership rule, not merely a storage format detail.

See the workflow resources in the interface

Figure 2 shows the documented terminal interface: loaded context, skills and extensions sit alongside a task transcript. These are different inputs to the system, even when they share one screen.

Pan on smaller screensOpen full size ↗

Figure 2. Pi interactive interface, reproduced from the repository documentation under MIT. The captured version and usage counters describe this screenshot, not a current release or performance comparison.7

The image shows an extension task reading documentation and inspecting files. It helps separate the user’s request, the harness resources and the visible trajectory. A transcript still needs an artifact check before the task can be considered complete.

Procedures and executable extensions are different

A skill supplies instructions and supporting resources. An extension is a TypeScript module executing inside Pi’s process. It can register tools, commands, providers, event handlers, state and UI behavior. The extension contract also includes lifecycle and cleanup expectations.6

That is powerful customization, with a concrete trust consequence: an extension has the process’s operating-system permissions. A module that improves tool routing is also executable code with access to that host. An instruction file and an in-process extension should not receive the same review treatment.

The repository explicitly says Pi does not include a built-in permission system that restricts filesystem, process, network or credential access. External containment is therefore a host responsibility.8 Project trust and resource loading are useful decisions, but they do not turn the process into an operating-system sandbox.

Choose an integration boundary

Interface Boundary What the host must understand
Interactive CLI User and terminal Task steering, visible tools and review
TypeScript SDK Same process Session ownership, subscriptions and extension lifecycle
RPC Child process JSONL framing, responses, events and continued output reading

The SDK gives direct access to the session objects. RPC runs a long-lived subprocess with commands, responses and events on standard streams. These interfaces use the same agent and session mechanisms, but differ in language coupling and process ownership.95 A subprocess boundary alone is not resource isolation.

An example: make an extension inspectable

Suppose a team wants a read-only repository review procedure with a custom summary command. The following is a proposed design exercise. It does not claim that installing one extension creates an enforced read-only environment.

First, define the output: findings with file locations, reasons and uncertainty. Package the procedure as instructions. Give the application an explicit allowed tool set, and enforce filesystem access outside the model when needed. Add an extension only for behavior that instructions cannot implement, such as a command or event integration.

Then inspect what happens when the session resumes or changes branch. Does the extension rebuild state from the right entries? Does it release listeners on replacement? Does the final review distinguish a missing file from an empty search result? These questions follow the session and lifecycle contracts; they are our proposed verification criteria.

What minimalism trades

Pi makes ownership visible: a small core can be easier to adapt, while the host must assemble policy, integrations and workflow conventions. That is a design tradeoff, not evidence that a smaller harness is always more reliable or cheaper. The broader toolkit and installed packages can add substantial behavior.

A useful comparison with Claude Code asks which workflow decisions are packaged. A comparison with DeepSeek Harness asks where customization attaches and how it is disposed. With Codex and OpenCode, examine the client/runtime boundary.

References

  1. Pi contributors. Coding application overview, minimal workflow and customization. Snapshot checked October 11, 2026. ↩

  2. Pi contributors. How Pi Works, loop, context, sessions and interfaces. Snapshot checked October 11, 2026. ↩

  3. Pi contributors. Agent loop implementation, runLoop, streamAssistantResponse, transformContext and convertToLlm. Inspected snapshot, October 11, 2026. ↩ ↩2

  4. Pi contributors. Sessions and Context, active branches, persistence and compaction. Snapshot checked October 11, 2026. ↩ ↩2

  5. Pi contributors. SDK, AgentSession and SessionManager ownership. Snapshot checked October 11, 2026. ↩ ↩2 ↩3

  6. Pi contributors. Extensions, in-process execution, registration and lifecycle. Snapshot checked October 11, 2026. ↩ ↩2

  7. Pi contributors. Interactive usage, documentation screenshot and visible interface. Image and documentation under the repository MIT license; checked October 11, 2026. ↩

  8. Mario Zechner and Earendil Works. Pi repository, package roles and Permissions & Containerization. Snapshot checked October 11, 2026. ↩

  9. Pi contributors. RPC Mode, subprocess JSONL transport and interface tradeoffs. Snapshot checked October 11, 2026. ↩

Navigation

Type to search…

↑↓ navigate↵ selectEsc close