pi Architecture Overview

Top-to-bottom layered architecture, ~920 TypeScript files · 7 npm packages

CLI Entry

cli.ts → main.ts (916)

~31KB

Agent Runtime

agent.ts + agent-loop.ts + harness/agent-harness.ts

~50KB

Session & Compaction

session-manager.ts + compaction.ts

~112KB

Models & Providers

ai/models.ts + providers/all.ts

~60KB

Wire Protocols (Lazy)

ai/api/* (anthropic/openai/codex/bedrock/google/mistral)

~160KB

Auth & OAuth

ai/auth/* + auth/oauth/*

~85KB

Built-in Tools

core/tools/{read,bash,edit,write,find,grep,ls}.ts

~40KB

Extension System

core/extensions/{types,runner,loader}.ts

~135KB

Interactive TUI

interactive-mode.ts + components/

205KB+

pi-tui Engine

tui/tui.ts + editor.ts + keys.ts

~190KB

RPC & Server

rpc-mode.ts + server/*

~66KB

SQLite Backend

storage/sqlite-node/*

~50KB

Data Flow

User Input
  │
  ▼
Agent.prompt()                       ← packages/agent/src/agent.ts
  │
  ├─ AgentState build                ← systemPrompt + tools + messages + thinkingLevel
  │
  ├─ agentLoop() AsyncGenerator      ← agent-loop.ts
  │    ├─ streamFn()                  ← pi-ai lazyStream → Provider.stream()
  │    │    ├─ resolveProviderAuth()   (env | credential-store | OAuth)
  │    │    └─ partial-JSON parse → tool calls
  │    ├─ execute tools (parallel | sequential)   ← beforeToolCall / afterToolCall
  │    └─ persist to Session          (JSONL tree | SQLite)
  │
  └─ yield AgentEvent                ← stream out
       ├─ AgentSession (orchestration, 3,327 lines)
       └─ InteractiveMode → pi-tui (diff rendering)

Code Statistics

~920

TypeScript Files

npm Packages

40+

LLM Providers

205KB

Largest File

Want the full source?

This project only extracts core files for teaching. To read pi's complete source, build and run it locally, visit the repository:

earendil-works/pi

Supports npm install --ignore-scripts + build; ./pi-test.sh runs pi straight from source.

Official Docs

Want to systematically read pi's docs? pi.dev provides the full manual, SDK examples, and extension guides.

pi.dev/docs/latest