CodeVetter · Repo Unpack · System map
earendil-works/pi
npm-workspaces monorepo (packages/*, plus packages/session-backends/* and extension examples) built in dependency order by the root build script: chord → tui → telemetry → ai → durable → agent → session-backends/sqlite-node → protocol → client → server → coding-agent. The shippable product is packages/coding-agent whose bin `pi` runs dist/bundle/cli.js (bundled from src/cli.ts → src/main.ts) on Node >=22.19, with an alternative Bun-compiled binary path. The agent runtime lives in pi-agent-core, provider access in pi-ai, terminal rendering in pi-tui (with C native modules per platform), and an experimental RPC/session-server stack in protocol/client/server/durable. State lives in ~/.pi/agent (auth.json, settings.json, models.json, sessions/, themes/, prompts/, bin/).
- Root package.json defines workspaces covering packages/*, packages/session-backends/*, and several coding-agent extension examples; the `build` script chains package builds in explicit dependency order ending at coding-agent.
- CLI entrypoint is packages/coding-agent/src/cli.ts, a 6-line shim that calls setupCli() then main(process.argv.slice(2)); the published bin `pi` points at dist/bundle/cli.js produced by scripts/build-coding-agent-bundle.mjs via the `build` script.
- main() in packages/coding-agent/src/main.ts is the single dispatcher: auth subcommands, package commands (install/remove/update/list), config command, then parseArgs, migrations, SessionManager creation, AgentSessionRuntime creation, and finally mode dispatch to runRpcMode, InteractiveMode, or runPrintMode.
- resolveAppMode selects between four run modes — rpc, json, print, interactive — from --mode/--print flags and stdin/stdout TTY detection; piped stdin forces print mode.
- packages/agent (pi-agent-core) exposes the Agent class and the lower-level agentLoop/runAgentLoop functions plus a harness/ subtree (pico3 session runtime, lane scheduler, session backends) that powers the experimental server packages.
- packages/ai (pi-ai) registers 41 built-in LLM providers in builtinProviders() (anthropic, openai, openai-codex, google, google-vertex, amazon-bedrock, github-copilot, openrouter, deepseek, groq, mistral, xai, zai, kimi-coding, moonshotai, minimax, cerebras, fireworks, together, huggingface, nvidia, baseten, meta, opencode, vercel-ai-gateway, cloudflare variants, qwen/xiaomi token plans, ant-ling, radius) backed by the generated MODELS catalog.
- Sessions are append-only JSONL trees under ~/.pi/agent/sessions/<encoded-cwd>/ named <timestamp>_<sessionId>.jsonl; the current on-disk format is CURRENT_SESSION_VERSION = 3.
- User state roots at getAgentDir() = $PI_CODING_AGENT_DIR or ~/.pi/agent, which holds auth.json, settings.json, models.json, sessions/, themes/, prompts/, tools/, bin/, and the debug log; PI_CODING_AGENT_SESSION_DIR can redirect sessions.
- packages/tui is a standalone terminal UI library (differential rendering, editor component, overlays, markdown/latex) with platform-specific native modules under packages/tui/native/{darwin,linux,win32} plus clipboard.h/napi.h — the source of the repo's C files.
- The experimental distributed stack: pi-protocol defines a version-handshaken, CBOR-framed envelope protocol (4-byte big-endian length prefix) over byte transports; pi-server hosts routed server/Session services; pi-client is the transport-neutral client; pi-durable provides durable record contracts with an in-memory storage reference.
- chord is a standalone application-composition runtime (facets, typed services, replicated state, RPC boundary) that intentionally depends on no other Pi workspace package; durable's Pico runtime and agent's harness/ build on its concepts.
- session-backends/sqlite-node provides SqliteSessionRepo, a node:sqlite-backed Session repository for pi-agent-core's harness session abstraction — one .sqlite file per Session under a directory.
- Build/test toolchain: tsgo (@typescript/native-preview) for typecheck/emit, biome 2.3.5 for lint+format (tabs, width 3, line 120), vitest for most packages, node:test for packages/tui and scripts/*.test.mjs, esbuild for bundling.
- A separate RPC entrypoint (src/rpc-entry.ts, exported as ./rpc-entry) sets process.title to `pi-rpc`, configures the HTTP dispatcher, and calls main(['--mode', 'rpc', ...]) — used for embedding the agent as a child process.
- Release artifacts are standalone binaries per platform built by scripts/build-binaries.sh and the `build:binary` script which runs `bun build --compile` over src/bun/cli.ts; GitHub workflow build-binaries.yml automates this.