How badlogic/pi-mono works
1. Overall structure
This is a TypeScript monorepo organized around one core product, the Pi coding agent, plus shared libraries underneath it. The package layering is roughly: AI provider integration at the bottom, agent runtime above that, then coding-agent application logic, with separate UI libraries for terminal and browser frontends.
2. packages/ai: provider and model abstraction layer
pi-ai is the lowest-level runtime package. It normalizes access to multiple LLM backends and hides provider-specific differences for streaming, tool calls, auth, headers, model lists, and request/response transformation. It includes adapters for OpenAI-style APIs, Anthropic, Google/Vertex, Azure OpenAI, Bedrock, Mistral, Cloudflare, GitHub Copilot, and a faux/test provider. OAuth and API-key resolution live here because provider auth materially affects how requests are formed.
3. packages/agent: generic agent loop
pi-agent-core is the reusable agent engine. Its job is to run the model/tool interaction loop, manage state, and mediate between the model stream and tool execution. The presence of agent-loop.ts, proxy.ts, and tests around retry, streaming, and e2e behavior suggests this package is the orchestration boundary between LLM responses and host application actions.
4. packages/coding-agent: full CLI application
pi-coding-agent is the main user-facing product. It wires together model selection, session management, prompts, tools, shell execution, compaction, skills, extensions, and rendering. Its src/main.ts, CLI argument parsing, and multiple modes show it is the top-level application that turns the shared runtime into an interactive coding assistant.
5. Primary runtime flow in the coding agent
The core flow is: user input and context files are collected, prompt templates and skills are assembled, the selected model is resolved, the agent loop calls the model through pi-ai, and tool calls are executed locally. Results are fed back into the session, persisted, and rendered either in the terminal or via RPC/web interfaces. This makes the boundary between “model conversation” and “local system side effects” a key architectural seam.
6. Tooling and local system boundary
Tool execution is a major subsystem in coding-agent: bash, read/write/edit, grep/find/ls, diff/edit variants, file mutation queuing, path handling, and truncation/render helpers. There is explicit guard logic around output and destructive actions, which means the agent is not just chat-driven; it is a controlled automation system with a strong local filesystem/shell boundary.
7. Session management, persistence, and migration
Sessions are first-class. The app contains a session manager, storage layout, tree traversal, labels, build-context logic, migrations, and pickers/search UI. This indicates sessions are not ephemeral chats; they are structured artifacts that can be resumed, branched, compacted, renamed, migrated, and exported. The session layer is a distinct persistence boundary between runtime state and UI.
8. Interactive, print, and RPC modes
The coding agent supports multiple execution surfaces: an interactive terminal mode, a print/non-interactive mode, and an RPC mode. The RPC layer (modes/rpc) suggests the agent can be embedded or controlled by another process, while interactive mode owns the TUI-driven user experience. This separation is important for diagramming because it shows the same core runtime can be driven by different frontends.
9. Extensions, skills, prompts, and custom providers
The repo has a plugin-like extension system with loader/runner/wrapper components, plus many examples that inject tools, UI elements, lifecycle hooks, and custom providers. Skills and prompt templates are loaded as content resources, and the .pi directory contains shipped prompt files and extensions. Architecturally, this is a customization layer that sits alongside the core runtime rather than inside it.
10. packages/tui: terminal rendering library
pi-tui is a standalone terminal UI toolkit with differential rendering, input editing, autocomplete, select lists, markdown, terminal image support, keybinding handling, and low-level terminal abstractions. It is the presentation foundation for the CLI app, keeping rendering and input mechanics separate from agent logic.
11. packages/web-ui: browser UI and sandboxed presentation
pi-web-ui provides a browser-based chat/agent interface with message lists, streaming containers, model/provider dialogs, settings, session storage, and sandboxed runtime providers for artifacts, console output, and file downloads. It uses IndexedDB-backed storage and browser components, so its architecture is centered on local persistence plus isolated rendering/sandboxing rather than shell execution.
12. External services and auth
The main external dependencies are LLM providers and their auth flows: API keys, OAuth, provider-specific headers, and model discovery. Bedrock, OpenAI-compatible APIs, Anthropic, Google, GitHub Copilot, Azure, Mistral, and Cloudflare are all first-class integration points, so provider selection and authentication are central architectural concerns.
13. Tooling, CI, and release infrastructure
The repo is built and tested as a monorepo with npm, Biome, Vitest, and TypeScript build configs. GitHub Actions handle CI, binary builds, contributor gating, and PR/issue automation. There are also scripts for binaries, release, session transcript analysis, profiling, and version syncing, which supports a productized CLI/distribution pipeline.
14. How to draw the diagram
A useful diagram would show four layers: providers/models (pi-ai) feeding agent orchestration (pi-agent-core), feeding the coding-agent application with tools/sessions/extensions, and then branching into presentation via pi-tui and pi-web-ui. The most important arrows are: user input → prompt/session assembly → model stream → tool execution → session persistence → UI rendering.
Main entry points: main.ts Main · agent-loop.ts Agent loop · session-manager.ts Sessions · interactive-mode.ts Interactive mode
Components 21
Shared runtime
Provider and agent orchestration layers used by the product.
- AI core · Unified model/provider abstraction and stream handling.
packages/ai/src/index.ts - Providers · Built-in provider registrations and request/response transforms.
packages/ai/src/providers/register-builtins.ts - Auth · API key and OAuth resolution for provider requests.
packages/ai/src/oauth.ts - Agent loop · Reusable model/tool interaction loop and state mediation.
packages/agent/src/agent-loop.ts - Proxy · Boundary for host application actions and tool-facing proxying.
packages/agent/src/proxy.ts
Coding agent
CLI application, local tools, sessions, and runtime modes.
- Main · Top-level wiring for the coding agent application.
packages/coding-agent/src/main.ts - Model resolver · Resolves provider/model choices and scoped defaults.
packages/coding-agent/src/core/model-resolver.ts - Sessions · Session lifecycle, storage layout, branching, and resume logic.
packages/coding-agent/src/core/session-manager.ts - Tools · File, shell, search, and mutation tools executed by the agent.
packages/coding-agent/src/core/tools/index.ts - Extensions · Loads and runs custom extensions around the agent runtime.
packages/coding-agent/src/core/extensions/loader.ts - Prompts & skills · Prompt templates, skills, and system-prompt assembly.
packages/coding-agent/src/core/prompt-templates.ts - Compaction · Summarizes and trims long-running sessions.
packages/coding-agent/src/core/compaction/compaction.ts
Presentation
Terminal and browser-facing UI layers.
- Interactive mode · Terminal-driven interactive experience for the agent.
packages/coding-agent/src/modes/interactive/interactive-mode.ts - Print mode · Batch/one-shot execution surface.
packages/coding-agent/src/modes/print-mode.ts - RPC mode · JSONL/RPC surface for external process control.
packages/coding-agent/src/modes/rpc/rpc-mode.ts - TUI · Terminal rendering and input toolkit used by the CLI.
packages/tui/src/tui.ts - Web UI · Browser chat/agent interface with local storage and sandboxed rendering.
packages/web-ui/src/ChatPanel.ts - Web storage · Browser persistence for sessions, settings, keys, and providers.
packages/web-ui/src/storage/store.ts - Sandbox · Browser-side artifact, console, and download runtime providers.
packages/web-ui/src/components/sandbox/SandboxRuntimeProvider.ts
External boundary
Local system side effects and third-party LLM services.
- LLM providers · OpenAI-style, Anthropic, Google, Bedrock, Mistral, Cloudflare, GitHub Copilot.
- Local system · Filesystem, shell, and other host-side side effects.
Connections 23
- Providers → LLM providers: requests · Provider adapters normalize calls to external model services.
- Auth → LLM providers: auth · Resolves provider credentials and request headers.
- Agent loop → AI core: stream/model · The agent engine talks to the shared AI layer.
- Agent loop → Tools: tool calls · Model outputs are mediated into host tools.
- Agent loop → Proxy: host actions · Proxy boundary for application-side execution.
- Main → Model resolver: selects · Application startup resolves model configuration.
- Main → Sessions: opens · Sessions are loaded or created at startup.
- Main → Interactive mode: interactive · Default terminal-driven product mode.
- Main → Print mode: batch · Non-interactive execution path.
- Main → RPC mode: rpc · Embedded/control surface mode.
- Model resolver → AI core: provider config · Resolves the concrete model/provider interface.
- Sessions → Compaction: summarizes · Long sessions are compacted through a dedicated boundary.
- Sessions → Prompts & skills: context · Sessions are assembled with prompts and skills.
- Extensions → Prompts & skills: injects · Extensions can reshape prompts and skill availability.
- Extensions → Tools: adds tools · Plugins can contribute or override tools.
- Interactive mode → TUI: renders · Terminal UI components power the interactive experience.
- RPC mode → Web UI: client API · RPC enables an external/browser control surface.
- Web UI → Web storage: persists · Browser state is stored locally in IndexedDB-backed stores.
- Web UI → Sandbox: isolates · Artifacts and console output are routed through sandbox providers.
- Tools → Local system: executes · File mutation and shell tools operate on the host.
- AI core → Agent loop: streams · Model streams feed the agent orchestration loop.
- Interactive mode → Sessions: session ui · Interactive navigation and editing operate on sessions.
- Print mode → Agent loop: run once · Batch mode still uses the shared orchestration engine.