Agent Architecture

Pi

Pi is a minimal, aggressively extensible agent harness with CLI/TUI, print/JSON, RPC, and SDK modes. It intentionally skips baked-in features like MCP, subagents, plan mode, and permission popups so users can build or install them as extensions, skills, prompts, and packages.

Source reviewed #23Checked 2026-07-06

Setup guide Source

Run type

CLI

Adapter

mcp-only

Source

OSS · earendil-works/pi

Stars

★ 102k

Archive Context

This page is one host entry inside the full architecture archive and keeps multi-surface products visible instead of collapsing them into a single run type.

42 host archive

Host page

Run cohort

CLI: 30

Archive route

/agents

Host Surface Perspectives

The host is the primary architecture boundary. Each runnable surface below separates what the host owns from what agent-connector can safely install for Pi.

1 surface entry

CLI

cli

Host entry: A terminal command owns the process, current working directory, stdin/stdout, shell environment, and project file discovery.
Host owns: The CLI host owns agent loop timing, approval prompts, tool execution, session files, and how hook or MCP subprocesses are launched.
Connector role: agent-connector can only write the host's documented CLI config, prompt, memory, hook, MCP, or package files and point them at the home binary. Current wired connector surfaces: Commands, Skills, Memory, Action affordances.
Implementation consequence: A CLI surface is byte-addressable and smoke-testable from a temporary HOME, but terminal UI behavior still belongs to the host process. No visible host-native gap is currently tracked for this surface.

Verified Architecture

Source-checked on 2026-07-06. These notes are intentionally separate from the generated surface matrix below.

Sequence #23

Source pass

Current source review findings are kept as the first architecture section so readers can separate external evidence from the generated local coverage model.

Pi is an agent harness with an interactive coding agent CLI, an agent runtime package, and a unified multi-provider LLM API.
The repository's package split separates the coding CLI, core runtime, model API, and terminal UI, which explains its mcp-only adapter posture.
Pi explicitly lacks a built-in permission boundary and recommends container or sandbox patterns, so safety claims should remain host-external.

Runtime boundary

The adapter target is the Pi CLI/TUI harness. Pi owns the minimal agent loop, provider API, TUI, session tree, print/JSON mode, RPC mode, SDK embedding, and extension runtime.

Pi positions itself as a minimal harness that adapts to user workflows.
It can run interactive, print/JSON, RPC, and SDK modes.

MCP registration

Pi explicitly says the core has no built-in MCP, and that users can build CLI tools with READMEs or build an extension that adds MCP support. This makes Pi a crucial counterexample in the coverage matrix.

MCP should not be counted as native Pi host support by default.
OMP can represent a package or extension surface that changes what Pi provides.

Hook bridge

Pi extensions are TypeScript modules with access to tools, commands, keyboard shortcuts, events, and the full TUI. That is the host's extension boundary and should be kept distinct from generic lifecycle hook support.

Dynamic context injection can be implemented by extensions before each turn.
Permission gates, path protection, sandboxing, and custom status bars are extension examples.

Content surfaces

Pi content includes AGENTS.md, SYSTEM.md, skills, prompt templates, themes, session trees, branchable/shareable history, extensions, packages, and dynamic context filters.

AGENTS.md loads from `~/.pi/agent/`, parent directories, and the current directory.
Skills use progressive disclosure and prompt templates expand through slash commands.

Marketplace and host-only affordances

The host-only affordance is minimalism plus customization. Pi packages bundle extensions, skills, prompts, and themes, installable from npm or git, which makes the package layer the marketplace story.

Pi intentionally leaves many features to packages or extensions.
Session sharing to gists and tree history are host collaboration features.

Host-specific shape

Pi deliberately has no MCP registration surface; its architecture centers on prompt commands, skills, memory, and generated command actions.

Form factor: CLI.
Native surfaces: Commands, Skills, Memory, Action affordances.
Wired surfaces: Commands, Skills, Memory, Action affordances.
Visible gaps: none.

Hooks

No user-installable lifecycle hook boundary is confirmed for this host.

MCP

No writable MCP registration surface is tracked for this host.

Memory

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace and affordances

Current install is a direct native-file write path; any package artifact is manual unless a driver is added.

Runtime handlers: Action affordances.
User-visible affordances: Users see managed commands + skills + actions + memory surfaces after install; runtime-only surfaces stay behind the host boundary..

Known Limits

Pi core explicitly does not include built-in MCP.
Subagents, plan mode, and permissions may exist through packages, not core host guarantees.
OMP should be documented as a separate package/profile row rather than plain Pi core.

Evidence checked

Pi website Pi repository

Architecture Diagram

Host-specific flow for the CLI surface.

mcp-only

1
Entry point: CLI
Terminal agent process reads user/project config and invokes the connector home binary for runtime callbacks.
2
Connector package
defineConnector package declares server, hooks, content, memory, and actions.
3
Adapter module: pi
mcp-only renderer at src/adapters/pi/index.ts.
4
Native host artifacts
Adapter writes content files + memory/rules + actions through this host's native file, package, or marketplace surface.
5
Runtime boundary
No lifecycle runtime bridge is wired; connector behavior remains limited to static host artifacts.
6
User-visible surface
Users see managed commands + skills + actions + memory surfaces after install; runtime-only surfaces stay behind the host boundary.
7
Coverage ceiling
4/4 native surfaces wired. No visible host-native gap in the current coverage matrix.

Component Diagram

Static parts of the Pi integration and which side owns each one.

Pi host
CLI surface owns the model loop, UI shell, config discovery, and native lifecycle for this integration.
agent-connector package
Normalizes connector declarations into MCP, hook, memory, content, and action payloads before delegating to a host adapter.
pi adapter
Implements the mcp-only translation layer in src/adapters/pi/index.ts.
Native artifacts
Adapter writes content files + memory/rules + actions through this host's native file, package, or marketplace surface.
Runtime bridge
No lifecycle runtime bridge is wired; connector behavior remains limited to static host artifacts.
User-visible surface
Users see managed commands + skills + actions + memory surfaces after install; runtime-only surfaces stay behind the host boundary.

Runtime Sequence Flow

Message order from install to runtime for the CLI surface.

1 · User / project
Choose host adapter
Install or update starts against Pi; the selected surface is CLI.
2 · agent-connector
Resolve connector declaration
The package reads connector metadata and routes it to the pi adapter instead of exposing a generic host contract.
3 · pi adapter
Render host-native shape
Adapter writes content files + memory/rules + actions through this host's native file, package, or marketplace surface.
4 · Pi
Host loads artifacts
No lifecycle runtime bridge is wired; connector behavior remains limited to static host artifacts.
5 · Agent runtime
Run through host boundary
Users see managed commands + skills + actions + memory surfaces after install; runtime-only surfaces stay behind the host boundary.
6 · Coverage matrix
Expose remaining ceiling
4/4 native surfaces wired. No visible host-native gap in the current coverage matrix.

Architecture Archive

The same five study axes are rendered for every host: runtime shape, hooks, MCP, memory, and host-only affordances.

Host-specific shape

Pi deliberately has no MCP registration surface; its architecture centers on prompt commands, skills, memory, and generated command actions.

Form factor: CLI.
Native surfaces: Commands, Skills, Memory, Action affordances.
Wired surfaces: Commands, Skills, Memory, Action affordances.
Visible gaps: none.

Hooks

No user-installable lifecycle hook boundary is confirmed for this host.

MCP

No writable MCP registration surface is tracked for this host.

Memory

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace and affordances

Current install is a direct native-file write path; any package artifact is manual unless a driver is added.

Runtime handlers: Action affordances.
User-visible affordances: Users see managed commands + skills + actions + memory surfaces after install; runtime-only surfaces stay behind the host boundary..

Special Feature Inventory

Host-specific capabilities separated from the generic surface matrix: lifecycle hooks, MCP registration, memory/rules, marketplace delivery, and UI or content affordances owned by the host.

Lifecycle hooks

Not confirmed

No user-installable lifecycle hook boundary is confirmed for this host.

MCP registration

Not confirmed

No writable MCP registration surface is tracked for this host.

Memory and rules

Wired

Managed memory text is written into the rules or memory file this host actually reads, with ownership markers for reversible uninstall.

Marketplace delivery

Direct files

Current install is a direct native-file write path; any package artifact is manual unless a driver is added.

Host-only affordances

3/3 wired

Wired host affordances: Commands, Skills, Action affordances. Host-native gaps: none. Not confirmed: Subagents, Statusline handler.

Source Review Notes

Latest source pass for host-specific architecture details. This is separate from generated adapter coverage and local drift guards.

Checked 2026-07-06Open review source

earendil-works/pi repository

Pi is an agent harness with an interactive coding agent CLI, an agent runtime package, and a unified multi-provider LLM API.
The repository's package split separates the coding CLI, core runtime, model API, and terminal UI, which explains its mcp-only adapter posture.
Pi explicitly lacks a built-in permission boundary and recommends container or sandbox patterns, so safety claims should remain host-external.

Evidence Map

Each host page ties public source evidence to the local adapter and drift guards that keep the rendered archive aligned with code.

Public source: earendil-works/pi

Primary public repository or product source used for current host status and source links.

external

Open source

Local adapter implementation

Defines the install/uninstall behavior, native config rendering, capability flags, and any runtime parse/format bridge for this host.

local

src/adapters/pi/index.ts

Platform metadata and host-native matrix

Records the form factor, public source target, ranking source, native host surfaces, and current agent-connector coverage cells.

local

site/src/platform-data.ts

Architecture drift guard

Asserts that every registered host has a page, diagram, host-specific brief, source link, form-factor band, and adapter-aligned surface data.

local

tests/docs/platform-drift.test.ts

Runtime Shape

The host accepts MCP registration, but has no confirmed hook bridge for agent-connector to call.

MCP registration: Not wired
Hook bridge: No confirmed hook surface

Connector Surfaces

Static content

Commands, Skills, Memory

Runtime handlers

Action affordances

Surface Matrix

Wired means agent-connector installs it now. Host native marks support we know about but have not wired yet.

SurfaceStatus

MCP server

Static content

No confirmed host-native surface.

N/A

Hooks

Static content

No confirmed host-native surface.

N/A

Commands

Static content

agent-connector installs this surface today.

Wired

Skills

Static content

agent-connector installs this surface today.

Wired

Subagents

Static content

No confirmed host-native surface.

N/A

Memory

Static content

agent-connector installs this surface today.

Wired

Statusline handler

Runtime handler

No confirmed host-native surface.

N/A

Action affordances

Runtime handler

agent-connector installs this surface today.

Wired