# poolsideai/pool architecture

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

- Interactive diagram: https://gitdiagram.com/poolsideai/pool
- Repository: https://github.com/poolsideai/pool

## Overview

1. **What this repo is**
   - `pool` is a Go-based coding agent CLI with three main operating modes: interactive terminal app, ACP server, and non-interactive `pool exec`.
   - The architecture is centered on an “agent runtime” that orchestrates model calls, tool execution, permissions, and session state.

2. **Top-level interaction layer**
   - The user-facing shell is a terminal UI built for interactive editing, commands, file search, and approval prompts.
   - The UI stack is strongly suggested by dependencies like Bubble Tea, Lip Gloss, Huh, Glamour, and clipboard/terminal helpers, so the app is not browser-based; it is a terminal-native experience.

3. **Agent orchestration core**
   - The core loop appears to manage chat/session state, decide when to call tools, and route results back into the conversation.
   - It supports multiple modes that change how aggressively it can act: ask-for-approval, accept-edits, allow-all, and plan-only.

4. **Tool execution boundary**
   - Tooling is a distinct subsystem from the model layer.
   - From the dependency set, the agent can likely run shell commands, manipulate files, open editors/browsers, and interact with a pseudo-terminal; these are treated as tool calls that may require user approval depending on policy.

5. **Permission and policy system**
   - Permissions are first-class and apply at both tool and path levels.
   - Rules can be scoped globally, per-project, or locally in gitignored config files, which creates a clear boundary between agent capability and user-approved workspace access.

6. **Configuration and persistence**
   - Runtime settings, credentials, agent-server defaults, and MCP server definitions are persisted under `~/.config/poolside` and optional project-local `.poolside/` files.
   - Session persistence is also an explicit feature, especially for ACP, where sessions can be listed and reloaded.

7. **Model/provider integration layer**
   - `pool` is provider-agnostic at the architecture level: it can use Poolside’s built-in service, OpenRouter, Ollama, or any OpenAI-compatible endpoint.
   - This implies a provider adapter layer that normalizes different APIs into a common agent interface, with model selection and auth handled separately from the rest of the app.

8. **Protocol adapters**
   - ACP support is a major boundary in the system: `pool acp` turns the app into a server for editors, while `pool --agent-server` makes it an ACP client driving another agent backend.
   - This makes protocol handling a separate integration layer from the core agent logic, rather than hard-wiring the app to one editor or one model service.

9. **MCP tool extensions**
   - MCP servers extend the agent’s toolset through stdio, HTTP, or SSE transports.
   - This is another pluggable boundary: external systems can contribute tools/data sources without changing the core agent, and can be scoped globally or per-project.

10. **Project-awareness and instructions**
   - The agent automatically consumes `AGENTS.md` and related project instructions, so repository-local guidance is part of the input pipeline.
   - That means the agent’s behavior is shaped by the workspace content before any model/tool action occurs.

11. **Operational modes and automation**
   - `pool exec` is the non-interactive entrypoint for scripts and CI, while the terminal mode is for human-in-the-loop sessions.
   - The architecture therefore supports both interactive and automated execution paths, sharing the same underlying agent/tool/config subsystems.

12. **External services and infrastructure footprint**
   - The repo integrates with vendor services like Poolside, OpenRouter, Ollama, OpenAI-compatible endpoints, ACP-compatible editors, and MCP servers.
   - Supporting dependencies for Git, PTY/shell execution, telemetry, and possibly sandbox/container handling indicate the app must coordinate local workspace operations with remote model calls and protocol-based tooling.

13. **Packaging and compliance**
   - The `third_party/` directory shows a deliberate vendoring/licensing boundary for many transitive dependencies.
   - This matters architecturally because the repo ships as a distributed CLI with a broad dependency surface, and license bookkeeping is part of the release process.

Main entry points: [`third_party`](https://github.com/poolsideai/pool/tree/main/third_party) (Third-party bundle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["User Interface"]
  node_node_cli["pool CLI<br/>entrypoint"]
  node_node_tui["Terminal UI<br/>tui"]
  node_node_exec["Exec mode<br/>batch runner"]
  node_node_acp_server["ACP server<br/>protocol server"]
end

subgraph group_group_core["Agent Core"]
  node_node_runtime{{"Agent runtime<br/>orchestrator"}}
  node_node_session[("Session state<br/>conversation state")]
  node_node_policy["Policy engine<br/>permissions"]
  node_node_workspace["Workspace context<br/>repo context"]
  node_node_tools["Tool router<br/>tool boundary"]
end

subgraph group_group_integrations["Integrations"]
  node_node_model["Model adapters<br/>provider adapters"]
  node_node_acp_client["ACP client<br/>protocol client"]
  node_node_mcp["MCP tools<br/>tool extensions"]
end

subgraph group_group_ops["Operations"]
  node_node_config["Config files<br/>settings"]
  node_node_persistence[("Session store<br/>persistence")]
  node_node_permissions["Permission scope<br/>workspace access"]
  node_node_third_party["Third-party bundle<br/>vendoring"]
end

node_node_cli -->|"interactive mode"| node_node_tui
node_node_cli -->|"exec mode"| node_node_exec
node_node_cli -->|"server mode"| node_node_acp_server
node_node_tui -->|"drives"| node_node_runtime
node_node_exec -->|"invokes"| node_node_runtime
node_node_acp_server -->|"routes to"| node_node_runtime
node_node_runtime -->|"calls"| node_node_model
node_node_runtime -->|"executes"| node_node_tools
node_node_runtime -->|"reads/writes"| node_node_session
node_node_runtime -->|"checks"| node_node_policy
node_node_runtime -->|"loads"| node_node_workspace
node_node_model -.->|"optional backend"| node_node_acp_client
node_node_tools -->|"extends with"| node_node_mcp
node_node_config -->|"selects provider"| node_node_model
node_node_config -->|"defines servers"| node_node_mcp
node_node_config -->|"stores rules"| node_node_permissions
node_node_persistence -->|"persists"| node_node_session
node_node_permissions -->|"guards"| node_node_tools
node_node_workspace -.->|"scopes access"| node_node_policy
node_node_third_party -.->|"vendored deps"| node_node_tui
node_node_third_party -.->|"vendored deps"| node_node_model

click node_node_third_party "https://github.com/poolsideai/pool/tree/main/third_party"

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_node_cli,node_node_tui,node_node_exec,node_node_acp_server toneBlue
class node_node_runtime,node_node_session,node_node_policy,node_node_workspace,node_node_tools toneAmber
class node_node_model,node_node_acp_client,node_node_mcp toneMint
class node_node_config,node_node_persistence,node_node_permissions,node_node_third_party toneRose
```

## Components

### User Interface

Terminal and command-driven entrypoints for interactive and automated use.

- **pool CLI**: entrypoint · Main command surface with interactive, server, and exec modes.
- **Terminal UI**: tui · Bubble Tea-style terminal experience for chat, commands, search, and approvals.
- **Exec mode**: batch runner · Non-interactive automation path for scripts and CI.
- **ACP server**: protocol server · Serves external editors and clients over ACP.

### Agent Core

Runtime orchestration, session handling, policies, and workspace context.

- **Agent runtime**: orchestrator · Coordinates model calls, tool execution, permissions, and session state.
- **Session state**: conversation state · Tracks chat history, tool results, and resumable sessions.
- **Policy engine**: permissions · Applies approval modes and path/tool restrictions.
- **Workspace context**: repo context · Loads project instructions and local repository guidance.
- **Tool router**: tool boundary · Dispatches shell, file, editor, browser, and PTY-style actions.

### Integrations

Model providers, protocol adapters, and pluggable tool extensions.

- **Model adapters**: provider adapters · Normalizes Poolside, OpenRouter, Ollama, and OpenAI-compatible backends.
- **ACP client**: protocol client · Drives another ACP-capable agent backend when configured.
- **MCP tools**: tool extensions · Extends the agent with external tools and data sources over stdio, HTTP, or SSE.

### Operations

Configuration, persistence, and release/compliance boundaries.

- **Config files**: settings · Global and project-local settings, credentials, and server definitions.
- **Session store**: persistence · Persists sessions and reloadable state across runs.
- **Permission scope**: workspace access · Manages global, project, and local path-scoped access rules.
- [Third-party bundle](https://github.com/poolsideai/pool/tree/main/third_party): vendoring · Vendored dependency and license boundary for distributed releases. · `third_party`

## Connections

- pool CLI → Terminal UI: interactive mode · Launches the terminal-native agent experience.
- pool CLI → Exec mode: exec mode · Runs the non-interactive automation path.
- pool CLI → ACP server: server mode · Exposes the agent as an ACP server.
- Terminal UI → Agent runtime: drives · Feeds user input and receives model/tool updates.
- Exec mode → Agent runtime: invokes · Uses the same orchestration core without the UI loop.
- ACP server → Agent runtime: routes to · Translates protocol requests into agent actions.
- Agent runtime → Model adapters: calls · Selects and queries a provider adapter.
- Agent runtime → Tool router: executes · Sends approved tool actions to the tool boundary.
- Agent runtime → Session state: reads/writes · Maintains conversation and resumable session state.
- Agent runtime → Policy engine: checks · Applies approval mode and access constraints before action.
- Agent runtime → Workspace context: loads · Imports repository instructions and workspace guidance.
- Model adapters → ACP client: optional backend · Can delegate through an ACP client backend.
- Tool router → MCP tools: extends with · Augments the toolset via external MCP servers.
- Config files → Model adapters: selects provider · Stores model, auth, and endpoint settings.
- Config files → MCP tools: defines servers · Persists global and project-local MCP definitions.
- Config files → Permission scope: stores rules · Holds scoped permission policy configuration.
- Session store → Session state: persists · Stores sessions for reload and continuation.
- Permission scope → Tool router: guards · Blocks or allows tool actions based on policy.
- Workspace context → Policy engine: scopes access · Project-local files influence what the agent may touch.
- Third-party bundle → Terminal UI: vendored deps · Packages the terminal UI dependency surface.
- Third-party bundle → Model adapters: vendored deps · Packages provider and protocol client dependencies.
