pool: Poolside's Terminal Coding Agent and Its ACP Modes
pool is Poolside’s coding agent that runs in your terminal or integrates with any ACP-compatible editor
At a glance
- What is it?
- pool ships as an interactive terminal agent, an ACP server for editors, an ACP client that drives other agents, and a non-interactive `pool exec` runner. The interesting part is not the TUI, it is the four modes and the approval model behind them.
- Who is it for?
- Adopt pool if you want one agent binary that can be a terminal TUI, an ACP server inside Zed or JetBrains, an ACP client driving someone else's agent, and a scriptable `pool exec` step, and if you are willing to read the permissions and hooks docs before trusting Auto mode. Do not adopt it if you need a fully auditable control plane, because the README states hooks fail open and are not a security boundary.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 28 days ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The four run modes are the actual product
Most terminal coding agents are one thing: a TUI that talks to a model. pool is packaged as four entry points around the same binary. Run `pool` and you get the interactive terminal application. Run `pool acp` and the same binary becomes an Agent Client Protocol server that an editor connects to. Run `pool --agent-server` and pool becomes an ACP client, driving some other ACP server instead of its own default agent. Run `pool exec` and it works non-interactively. The README is explicit that the default agent described throughout the document is the one that ships with pool, and that when you connect elsewhere with `--agent-server`, the available modes and agent-side features depend on that server. That single sentence reframes the whole tool. pool is not only an agent, it is also a client shell for agents that follow the same protocol. The target user is an engineer who already has an editor with ACP support, such as Zed, JetBrains or Xcode, and does not want a separate terminal workflow bolted onto it. The README lists those three by name and links an ACP client registry for the rest.
Approval modes decide what the agent may do without asking
There are four approval modes with stable IDs: `default` (Always ask), `accept-edits`, `auto`, and `always-allow`. The README describes `default` as prompting for tool actions that are not already allowed, `accept-edits` as auto-approving workspace file reads and writes, `always-allow` as approving tool calls automatically, and `auto` as classifying the remaining permission requests by risk. You cycle modes with `Shift+Tab` or switch directly with `/mode <approval-mode>`. Auto mode is the one with real machinery behind it. It uses Accept edits as a baseline, runs low-risk actions immediately, runs medium-risk actions with a notice, and opens the approval dialog for high-risk actions. The classifier model is configured in the personal settings file at `~/.config/poolside/settings.yaml` under the key `pool.auto_mode_classifier`, and can be overridden for a single invocation with the `POOL_AUTO_MODE_CLASSIFIER_MODEL` environment variable. The README notes that an explicitly empty value disables Auto mode for that invocation, which is a useful escape hatch for scripted runs where you do not want a classifier making calls. The README defers classifier inputs, failure behaviour and safety constraints to the permissions documentation rather than describing them inline, so the repository alone does not tell you what happens when the classifier itself errors.
Build mode, Plan mode, and the review gate on the way back
Agent modes are separate from approval modes, and the README is careful about that distinction: Build and Plan control how pool works without changing approval behaviour. In Plan mode the agent can inspect the codebase and prepare a plan without modifying source files. You enter it with `/plan` or `/agent-mode plan` after starting pool, and return with `/agent-mode build`. Two constraints stand out. There is no Plan-mode startup flag, so you cannot launch directly into Plan mode from the command line. And returning from Plan to Build always requires your review, including when the approval mode is Allow all. That second rule is the most opinionated decision in the material. Even in the mode that auto-approves everything, the transition out of planning is not auto-approved. If you are building automation on top of pool, that gate is the thing to design around, because it means a fully unattended Plan-to-Build handoff is not available through the documented interface.
Hooks cover six lifecycle events and fail open
Hooks let you run shell commands at six agent lifecycle events: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `PreCompact`, and `SessionStart`. According to the README they can inspect or rewrite tool calls and prompts, block matching actions, inject context, and ask the agent to continue at the end of a turn. They are configured under the top-level `hooks` key in `settings.yaml`. The README is unusually blunt about the security posture: hooks run automatically without an approval prompt, they fail open if they fail, time out, or return output that pool cannot parse, and they are not a security boundary. It directs you to permissions and sandboxes for enforced controls. Read that as a design statement rather than a caveat. If a hook is your only guard against a dangerous command, a timeout silently removes the guard. The hook system is for context injection and workflow shaping, and the documentation says so.
Subagents, shared workspace, and where parallel work breaks
The `general` subagent needs no configuration and lets the main agent delegate focused work with separate context. Beyond that you can configure named subagents that use custom instructions, another in-process Poolside agent, or a command-based ACP server. The limitation is stated plainly: subagents share the workspace, so parallel changes to the same files can conflict. There is no documented isolation layer between them in the README. Usage accounting is available through `/usage`, which reports parent, per-subagent and total consumption, and the README points to the subagents documentation for configuration, permissions and usage accounting details. The practical consequence is that delegation pays off when tasks touch disjoint files, and the shared workspace makes it a poor fit for two subagents editing the same module at once. Nothing in the supplied material suggests a merge or conflict-resolution mechanism.
Getting it running: install, update, and the config surface
Linux and macOS install with `curl -fsSL https://downloads.poolside.ai/pool/install.sh | sh`. Windows is marked preview and uses `irm https://downloads.poolside.ai/pool/install.ps1 | iex` in PowerShell. Updating is `pool update`, and the README notes pool also prompts at startup when a newer version is available, so an unattended machine will see that prompt rather than updating silently. The quick start is `cd your-project` then `pool`. `pool -h` lists all options. Inside a session you get slash commands with `/`, fuzzy file search with `@`, shell mode with `!`, rewind with double `esc`, and session management through `/resume`, `/delete` and `/rename`. Entering `?` or `/help` lists commands and shortcuts. Steering behaviour has terminal dependencies worth noting: entering another prompt while the agent works and pressing `Enter` steers the running turn, while `Ctrl+Enter` queues for the next turn only when your terminal supports key disambiguation. Shell input and slash commands wait until the current turn finishes. For editor integration, `pool acp` is registered in the ACP registry, and other editors point their ACP configuration at `pool acp`. The README also covers OpenRouter, Ollama, an OpenAI-compatible API, and MCP servers as connection options, with MCP listed among the open specs pool implements alongside AGENTS.md, Skills and ACP. pool reads relevant `AGENTS.md` files from the project automatically for context and instructions.
What the material does not settle
The repository metadata supplied here lists the primary language as unknown and the licence as unknown. That is not a documentation gap you can work around by reading harder, it is an absent fact, and it matters because the licence determines whether you can ship pool inside a commercial workflow at all. Confirm it from the repository before adopting. The same applies to the model story. The README documents that you can point pool at OpenRouter, Ollama, or an OpenAI-compatible API, and that Auto mode takes a classifier model id, but it does not state default model choices, pricing, or what happens to your code when a third-party endpoint is selected. Release cadence is visible from the tags: v1.0.14 on 2026-07-31, v1.0.15 on 2026-08-04, v1.0.16 on 2026-08-14. Three releases in roughly two weeks at the 1.0.x line suggests active patching, and it also means pinning a version is worth the effort if you depend on a specific approval or hook behaviour.
How this differs from a plain editor-integrated agent
The obvious comparison is an editor's built-in assistant, or a terminal agent that only speaks to its own backend. The difference here is protocol position. pool implements ACP in both directions: as a server that Zed, JetBrains or Xcode connect to, and as a client that connects to another ACP server via `--agent-server`. That second direction is the unusual one. A tool that can be a server is an integration target; a tool that can also be a client is a front end you can repoint. The README attaches a real consequence to that flexibility: when you connect to another ACP server, the available modes and agent-side features depend on that server, and if that server does not support steering, a mid-turn prompt simply waits for the next turn. So the same keystrokes produce different behaviour depending on what is behind the socket. If you want a stable, predictable agent surface, running pool's own default agent is the path with the fewest conditional behaviours documented.
Editorial conclusion
Adopt pool if you want one agent binary that can be a terminal TUI, an ACP server inside Zed or JetBrains, an ACP client driving someone else's agent, and a scriptable `pool exec` step, and if you are willing to read the permissions and hooks docs before trusting Auto mode. Do not adopt it if you need a fully auditable control plane, because the README states hooks fail open and are not a security boundary. Before installing, verify two things yourself: the licence, which is not stated in the repository metadata supplied here, and whether your editor's ACP client supports mid-turn steering and `/rename`, since both are listed as conditional on the connected agent server.
Community notes