Knowledge Base updated: 2026-11-19
Knowledge Base Index
1. Orientation
This repository is the Pi monorepo: a TypeScript/Node workspace for AI agent runtimes, a coding-agent CLI, durable task/session infrastructure, terminal UI, protocol integrations, and private product apps. The highest-level flow is a user or app invoking Pi, which routes through the coding-agent/agent core, calls model providers and tools, and may persist durable runtime state.
Main parts:
packages/coding-agent— the shippedpiCLI/RPC coding-agent runtime.packages/agent— reusable agent orchestration core.packages/durable— durable conversations, tasks, documents, tools, storage, and workers.packages/ai,packages/schema,packages/mcp— provider/model, shared schema, and MCP integration layers.packages/codemode,packages/tui,packages/env,packages/chord— editing workflows, terminal UI, remote execution, and Chord APIs.apps/p2andapps/p3— private product applications built on the shared packages.
Critical state lives primarily in durable runtime storage backends under packages/durable/**, app-specific data and plugin state under apps/p2/** and apps/p3/**, and generated/package metadata in package manifests and catalog assets such as packages/ai/catalog/**.
2. Architecture diagrams
flowchart TD
subgraph Apps
P2[apps/p2]
P3[apps/p3]
end
subgraph UserSurfaces
CLI[packages/coding-agent]
TUI[packages/tui]
end
subgraph AgentRuntime
Agent[packages/agent]
Durable[packages/durable]
Codemode[packages/codemode]
Env[packages/env]
end
subgraph ProtocolsAndTypes
AI[packages/ai]
Schema[packages/schema]
MCP[packages/mcp]
Chord[packages/chord]
end
P2 --> Durable
P2 --> AI
P2 --> TUI
P3 --> Chord
P3 --> Schema
CLI --> Agent
CLI --> TUI
CLI --> Codemode
CLI --> MCP
Agent --> AI
Agent --> Schema
Durable --> Env
Durable --> Codemode
Durable --> Schema
MCP --> Schema
sequenceDiagram
participant User
participant PiCLI as packages/coding-agent
participant Agent as packages/agent
participant AI as packages/ai
participant MCP as packages/mcp
participant Tools as codemode/env/durable tools
User->>PiCLI: start CLI or RPC session
PiCLI->>Agent: create/run agent turn
Agent->>AI: select model/provider and send messages
Agent->>MCP: discover or invoke external tools
Agent->>Tools: read/edit/execute/persist work
Tools-->>Agent: tool results
AI-->>Agent: model response
Agent-->>PiCLI: updated session output
PiCLI-->>User: terminal/RPC response
flowchart LR
Request[durable request/task] --> Runtime[packages/durable runtime]
Runtime --> Scheduler[scheduler/workers]
Runtime --> Tools[tools and tool-search]
Runtime --> Storage[storage backends]
Runtime --> Env[packages/env remote execution]
Runtime --> Images[image helpers]
Runtime --> Codemode[packages/codemode integration]
3. Glossary
- Pi — the repo’s AI assistant/coding-agent product and CLI surface, centered on
packages/coding-agent. - p2 — private app under
apps/p2that composes Pi packages with plugins, hosts, and voice/server surfaces. - p3 — private “one Pi per person” app/server and CLI under
apps/p3. - Durable — the repo’s persistent conversation/task/document runtime in
packages/durable. - Chord — shared package/API surface under
packages/chord, consumed by apps such as p2 and p3.
4. Codebase-wide invariants
- The repo is an npm workspace monorepo rooted at package.json, with first-class workspaces under
packages/*andapps/*. - Workspace packages use ESM package metadata: representative manifests such as packages/…/package.json, packages/…/package.json, apps/…/package.json, and apps/…/package.json all declare
"type": "module". - Build/check/test orchestration is centralized in root package.json scripts, with package-level scripts in each workspace manifest such as packages/…/package.json and packages/…/package.json.
- Core package source and tests are colocated per workspace using patterns like
packages/*/src/**andpackages/*/test/**; app code follows the same pattern inapps/p2/src/**,apps/p2/test/**,apps/p3/src/**, andapps/p3/test/**.
5. Routing table
-
packages/coding-agent/**-> docs/coding-agent.md -
any change to the
piCLI, RPC entrypoint, coding-agent session management, interactive modes, bundled coding-agent assets, coding-agent extension examples, or coding-agent schemas -> docs/coding-agent.md -
packages/agent/**-> docs/agent-core.md -
any change to reusable agent orchestration, transport abstraction, attachment handling, agent state, or core LLM/tool turn management -> docs/agent-core.md
-
packages/durable/**-> docs/durable-runtime.md -
any change to durable conversations, durable tasks, durable documents, runtime workers, scheduler behavior, durable tool search/tools, storage backends, image helpers, or durable testing helpers -> docs/durable-runtime.md
-
packages/ai/**-> docs/ai-models.md -
any change to model/provider abstractions, model catalog data, catalog generation/hydration scripts, or AI package tests -> docs/ai-models.md
-
packages/codemode/**-> docs/codemode.md -
any change to codemode APIs, examples, tests, or code-editing workflow integration points -> docs/codemode.md
-
packages/mcp/**-> docs/mcp.md -
any change to Model Context Protocol client/server/protocol integration or MCP package tests -> docs/mcp.md
-
packages/schema/**-> docs/schema.md -
any change to shared schemas, validation/type surfaces, schema exports, or schema package tests -> docs/schema.md
-
packages/tui/**-> docs/tui.md -
any change to terminal UI TypeScript code, native TUI targets, TUI packaging, or TUI tests -> docs/tui.md
-
packages/chord/**-> docs/chord.md -
any change to Chord APIs, tutorials/examples, package docs, or Chord tests -> docs/chord.md
-
packages/env/**-> docs/env.md -
any change to remote execution environment clients, SSH/deployment behavior, Rust daemon code, or env package tests -> docs/env.md
-
apps/p2/**-> docs/p2-app.md -
any change to p2 hosts, plugins, public assets, voice server, scripts, migrations, or tests -> docs/p2-app.md
-
apps/p3/**-> docs/p3-app.md -
any change to p3 server/CLI behavior, API exports, plugins, kit modules, release/build scripts, benches, or tests -> docs/p3-app.md