# badlogic/pi-mono architecture

> Architecture diagram of the GitHub repository badlogic/pi-mono, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/badlogic/pi-mono
- Repository: https://github.com/badlogic/pi-mono

## Overview

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: [`packages/coding-agent/src/main.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/main.ts) (Main), [`packages/agent/src/agent-loop.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/agent-loop.ts) (Agent loop), [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) (Sessions), [`packages/coding-agent/src/modes/interactive/interactive-mode.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts) (Interactive mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared runtime"]
  node_ai_entry["AI core<br/>package entry<br/>[index.ts]"]
  node_ai_providers["Providers<br/>adapters"]
  node_ai_auth["Auth<br/>[oauth.ts]"]
  node_agent_loop["Agent loop<br/>orchestration engine<br/>[agent-loop.ts]"]
  node_agent_proxy["Proxy<br/>host bridge<br/>[proxy.ts]"]
end

subgraph group_coding["Coding agent"]
  node_coding_main["Main<br/>cli entry<br/>[main.ts]"]
  node_model_resolver["Model resolver<br/>model selection<br/>[model-resolver.ts]"]
  node_session_mgr[("Sessions<br/>persistence<br/>[session-manager.ts]")]
  node_tools_core["Tools<br/>local actions<br/>[index.ts]"]
  node_ext_loader["Extensions<br/>plugin system<br/>[loader.ts]"]
  node_prompt_skills["Prompts & skills<br/>content resources"]
  node_compaction["Compaction<br/>context reduction<br/>[compaction.ts]"]
end

subgraph group_presentation["Presentation"]
  node_interactive_mode["Interactive mode<br/>tui runtime"]
  node_print_mode["Print mode<br/>non-interactive<br/>[print-mode.ts]"]
  node_rpc_mode["RPC mode<br/>remote control<br/>[rpc-mode.ts]"]
  node_tui["TUI<br/>terminal UI<br/>[tui.ts]"]
  node_web_ui["Web UI<br/>browser UI<br/>[ChatPanel.ts]"]
  node_web_storage[("Web storage<br/>indexeddb state<br/>[store.ts]")]
  node_web_sandbox["Sandbox<br/>isolated runtime"]
end

subgraph group_external["External boundary"]
  node_llm_services{{"LLM providers<br/>external service"}}
  node_local_system{{"Local system<br/>filesystem/shell"}}
end

node_ai_providers -->|"requests"| node_llm_services
node_ai_auth -->|"auth"| node_llm_services
node_agent_loop -->|"stream/model"| node_ai_entry
node_agent_loop -->|"tool calls"| node_tools_core
node_agent_loop -->|"host actions"| node_agent_proxy
node_coding_main -->|"selects"| node_model_resolver
node_coding_main -->|"opens"| node_session_mgr
node_coding_main -->|"interactive"| node_interactive_mode
node_coding_main -->|"batch"| node_print_mode
node_coding_main -->|"rpc"| node_rpc_mode
node_model_resolver -->|"provider config"| node_ai_entry
node_session_mgr -->|"summarizes"| node_compaction
node_session_mgr -->|"context"| node_prompt_skills
node_ext_loader -->|"injects"| node_prompt_skills
node_ext_loader -->|"adds tools"| node_tools_core
node_interactive_mode -->|"renders"| node_tui
node_rpc_mode -->|"client API"| node_web_ui
node_web_ui -->|"persists"| node_web_storage
node_web_ui -->|"isolates"| node_web_sandbox
node_tools_core -->|"executes"| node_local_system
node_ai_entry -->|"streams"| node_agent_loop
node_interactive_mode -->|"session ui"| node_session_mgr
node_print_mode -->|"run once"| node_agent_loop

click node_ai_entry "https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/index.ts"
click node_ai_providers "https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/providers/register-builtins.ts"
click node_ai_auth "https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/oauth.ts"
click node_agent_loop "https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/agent-loop.ts"
click node_agent_proxy "https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/proxy.ts"
click node_coding_main "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/main.ts"
click node_model_resolver "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/model-resolver.ts"
click node_session_mgr "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts"
click node_tools_core "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/tools/index.ts"
click node_ext_loader "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/extensions/loader.ts"
click node_prompt_skills "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/prompt-templates.ts"
click node_compaction "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/compaction.ts"
click node_interactive_mode "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts"
click node_print_mode "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/modes/print-mode.ts"
click node_rpc_mode "https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/modes/rpc/rpc-mode.ts"
click node_tui "https://github.com/badlogic/pi-mono/blob/main/packages/tui/src/tui.ts"
click node_web_ui "https://github.com/badlogic/pi-mono/blob/main/packages/web-ui/src/ChatPanel.ts"
click node_web_storage "https://github.com/badlogic/pi-mono/blob/main/packages/web-ui/src/storage/store.ts"
click node_web_sandbox "https://github.com/badlogic/pi-mono/blob/main/packages/web-ui/src/components/sandbox/SandboxRuntimeProvider.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ai_entry,node_ai_providers,node_ai_auth,node_agent_loop,node_agent_proxy toneBlue
class node_coding_main,node_model_resolver,node_session_mgr,node_tools_core,node_ext_loader,node_prompt_skills,node_compaction toneAmber
class node_interactive_mode,node_print_mode,node_rpc_mode,node_tui,node_web_ui,node_web_storage,node_web_sandbox toneMint
class node_llm_services,node_local_system toneRose
```

## Components

### Shared runtime

Provider and agent orchestration layers used by the product.

- [AI core](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/index.ts): package entry · Unified model/provider abstraction and stream handling. · `packages/ai/src/index.ts`
- [Providers](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/providers/register-builtins.ts): adapters · Built-in provider registrations and request/response transforms. · `packages/ai/src/providers/register-builtins.ts`
- [Auth](https://github.com/badlogic/pi-mono/blob/main/packages/ai/src/oauth.ts): oauth/key resolution · API key and OAuth resolution for provider requests. · `packages/ai/src/oauth.ts`
- [Agent loop](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/agent-loop.ts): orchestration engine · Reusable model/tool interaction loop and state mediation. · `packages/agent/src/agent-loop.ts`
- [Proxy](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/proxy.ts): host bridge · 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](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/main.ts): cli entry · Top-level wiring for the coding agent application. · `packages/coding-agent/src/main.ts`
- [Model resolver](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/model-resolver.ts): model selection · Resolves provider/model choices and scoped defaults. · `packages/coding-agent/src/core/model-resolver.ts`
- [Sessions](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts): persistence · Session lifecycle, storage layout, branching, and resume logic. · `packages/coding-agent/src/core/session-manager.ts`
- [Tools](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/tools/index.ts): local actions · File, shell, search, and mutation tools executed by the agent. · `packages/coding-agent/src/core/tools/index.ts`
- [Extensions](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/extensions/loader.ts): plugin system · Loads and runs custom extensions around the agent runtime. · `packages/coding-agent/src/core/extensions/loader.ts`
- [Prompts & skills](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/prompt-templates.ts): content resources · Prompt templates, skills, and system-prompt assembly. · `packages/coding-agent/src/core/prompt-templates.ts`
- [Compaction](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/compaction/compaction.ts): context reduction · Summarizes and trims long-running sessions. · `packages/coding-agent/src/core/compaction/compaction.ts`

### Presentation

Terminal and browser-facing UI layers.

- [Interactive mode](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts): tui runtime · Terminal-driven interactive experience for the agent. · `packages/coding-agent/src/modes/interactive/interactive-mode.ts`
- [Print mode](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/modes/print-mode.ts): non-interactive · Batch/one-shot execution surface. · `packages/coding-agent/src/modes/print-mode.ts`
- [RPC mode](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/modes/rpc/rpc-mode.ts): remote control · JSONL/RPC surface for external process control. · `packages/coding-agent/src/modes/rpc/rpc-mode.ts`
- [TUI](https://github.com/badlogic/pi-mono/blob/main/packages/tui/src/tui.ts): terminal UI · Terminal rendering and input toolkit used by the CLI. · `packages/tui/src/tui.ts`
- [Web UI](https://github.com/badlogic/pi-mono/blob/main/packages/web-ui/src/ChatPanel.ts): browser UI · Browser chat/agent interface with local storage and sandboxed rendering. · `packages/web-ui/src/ChatPanel.ts`
- [Web storage](https://github.com/badlogic/pi-mono/blob/main/packages/web-ui/src/storage/store.ts): indexeddb state · Browser persistence for sessions, settings, keys, and providers. · `packages/web-ui/src/storage/store.ts`
- [Sandbox](https://github.com/badlogic/pi-mono/blob/main/packages/web-ui/src/components/sandbox/SandboxRuntimeProvider.ts): isolated runtime · 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**: external service · OpenAI-style, Anthropic, Google, Bedrock, Mistral, Cloudflare, GitHub Copilot.
- **Local system**: filesystem/shell · Filesystem, shell, and other host-side side effects.

## Connections

- 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.
