How poolsideai/pool works
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 Third-party bundle
Components 16
User Interface
Terminal and command-driven entrypoints for interactive and automated use.
- pool CLI · Main command surface with interactive, server, and exec modes.
- Terminal UI · Bubble Tea-style terminal experience for chat, commands, search, and approvals.
- Exec mode · Non-interactive automation path for scripts and CI.
- ACP server · Serves external editors and clients over ACP.
Agent Core
Runtime orchestration, session handling, policies, and workspace context.
- Agent runtime · Coordinates model calls, tool execution, permissions, and session state.
- Session state · Tracks chat history, tool results, and resumable sessions.
- Policy engine · Applies approval modes and path/tool restrictions.
- Workspace context · Loads project instructions and local repository guidance.
- Tool router · Dispatches shell, file, editor, browser, and PTY-style actions.
Integrations
Model providers, protocol adapters, and pluggable tool extensions.
- Model adapters · Normalizes Poolside, OpenRouter, Ollama, and OpenAI-compatible backends.
- ACP client · Drives another ACP-capable agent backend when configured.
- MCP tools · Extends the agent with external tools and data sources over stdio, HTTP, or SSE.
Operations
Configuration, persistence, and release/compliance boundaries.
- Config files · Global and project-local settings, credentials, and server definitions.
- Session store · Persists sessions and reloadable state across runs.
- Permission scope · Manages global, project, and local path-scoped access rules.
- Third-party bundle · Vendored dependency and license boundary for distributed releases.
third_party
Connections 21
- 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.