pi Architecture Overview

源码版本v0.73.1

badlogic/pi-mono is a TypeScript monorepo that ships five npm packages forming a full stack: unified LLM API → general Agent → coding assistant → terminal/web UI. This page gives you the map; every following page unpacks one layer.

The five packages

Package	npm name	Role
ai	@mariozechner/pi-ai	Unified LLM API, 9 built-in providers, auto model discovery
agent	@mariozechner/pi-agent-core	General Agent, double while loop + tool execution
coding-agent	@mariozechner/pi-coding-agent	Coding assistant CLI, read/bash/edit/write tools + session management
tui	@mariozechner/pi-tui	Terminal UI library, diff rendering + synchronized output
web-ui	@mariozechner/pi-web-ui	Web chat components, Lit Web Components

Source directory: packages/

Layering

One sentence per layer

• pi-ai: Unifies 9 LLM providers (Anthropic, OpenAI, Google, Bedrock, ...) into two functions, stream and streamSimple, dispatched by model.api through a registry. See Streaming facade stream.
• pi-agent-core: The Agent class holds state; runLoop is the outer loop handling interruptions and queueing, the inner loop handles tool calls. Streaming + tool loop. See Double while loop.
• pi-coding-agent: Wraps Agent in AgentSession, adding tools, system prompts, session persistence, and three run modes. See AgentSession orchestration layer.
• pi-tui: Diff rendering + DECSET 2026 synchronized output to avoid terminal flicker. See Diff-rendered TUI class.
• pi-web-ui: A Lit component owns its own Agent instance, wrapping streamSimple via createStreamFn to go through a CORS proxy. See AgentInterface session host.

Why layer it this way

Why not one big package? Because the consumers differ: web components can't depend on Node's fs, terminal UI shouldn't carry the web's IndexedDB, and the general Agent shouldn't know about "coding" as a concept. With layers, the web can grab pi-agent-core + pi-ai and run its own agent, skipping the coding-assistant toolset; the coding CLI can swap UI (tui or rpc mode) without touching orchestration logic. pi-ai is packaged on its own so any project can pick up the unified LLM API without buying into the agent concept.

Common misreadings

• "pi is a coding agent": Not quite. pi-coding-agent is the top-layer application; pi-ai and pi-agent-core underneath are general infrastructure and can be used standalone.
• "The UI layer is just rendering": Both the web and terminal UIs participate in streaming — the web swaps Agent.streamFn to inject a CORS proxy, the terminal subscribes to events to decide when to redraw.

Recommended reading order

Start with Streaming facade stream to see how LLMs are called, then Double while loop for the tool loop, then AgentSession orchestration layer for how the coding assistant is wired up. Pick pi-tui or pi-web-ui last, based on interest.