Introducing a new way to review your PRs.

Read the announcement

earendil-works / pi

AI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI

View on GitHub

13 documents · Updated Nov 19, 2026

overview

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 shipped pi CLI/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/p2 and apps/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/p2 that 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

5. Routing table

  • packages/coding-agent/** -> docs/coding-agent.md

  • any change to the pi CLI, 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