Skip to content

Docs: Clarify CLI modes and context length #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
agentcooper merged 2 commits into from
Aug 5, 2026
Merged

Docs: Clarify CLI modes and context length #37

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
19aaa63
docs: clarify CLI modes and context length
amypoolside Aug 4, 2026
7aa9b46
copilot edits
amypoolside Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 20 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ pool is [Poolside](https://poolside.ai)’s coding agent. It can run in several

- [Install](#install)
- [Quick start](#quick-start)
- [Modes](#modes)
- [Approval modes](#approval-modes)
- [Agent modes](#agent-modes)
- [Spec support](#spec-support)
- [Run as an ACP server (`pool acp`)](#run-as-an-acp-server-pool-acp)
- [Run as an ACP client (`pool --agent-server`)](#run-as-an-acp-client-pool---agent-server)
Expand Down Expand Up @@ -61,18 +62,23 @@ Run `pool -h` to see all available options.

Enter `?` or `/help` during a session to see all available commands and shortcuts.

## Modes
## Approval modes

By default, pool asks for approval before each tool call. Switch to Accept edits or Allow all when you want it to take actions without prompting.
By default, pool asks for approval before tool actions that are not already allowed. Switch to Accept edits or Allow all when you want it to take actions without prompting.

| Mode | ID | What it does |
| ------------- | -------------- | ------------------------------------------------------------------ |
| Always ask | `default` | Prompts for approval on first use of each tool type |
| Accept edits | `accept-edits` | Auto-approves workspace file reads and writes |
| Allow all | `always-allow` | Approves tool calls automatically |
| Plan | `plan` | Plans changes without modifying your codebase |
| Approval mode | ID | What it does |
| ------------- | -------------- | --------------------------------------------- |
| Always ask | `default` | Prompts for tool actions that are not already allowed |
| Accept edits | `accept-edits` | Auto-approves workspace file reads and writes |
| Allow all | `always-allow` | Approves tool calls automatically |

Press `Shift+Tab` to cycle through modes, or use `/mode <id>` to switch directly.
Press `Shift+Tab` to cycle through approval modes, or use `/mode <approval-mode>` to switch directly.

## Agent modes

Build and Plan control how pool works without changing approval behavior. In Plan mode, pool can inspect your codebase and prepare a plan without modifying source files.

After starting pool, use `/plan` or `/agent-mode plan` to enter Plan mode. Use `/agent-mode build` to return to Build mode. There is no Plan-mode startup flag.

## Spec support

Expand Down Expand Up @@ -105,7 +111,7 @@ To pass flags to the ACP server, add them to the args array, for example `["acp"
### ACP features

- Session persistence: `session/list` and `session/load`
- Session config options: mode, model, and thought level when supported. These can be persisted in `settings.yaml`
- Session config options: approval mode, agent mode, model, and thought level when supported. These can be persisted in `settings.yaml`
and are sent on startup using `session/set_config_option`
- Slash commands advertised to the client

Expand Down Expand Up @@ -205,7 +211,7 @@ POOLSIDE_STANDALONE_BASE_URL="http://127.0.0.1:8080" POOLSIDE_API_KEY="EMPTY" po
Optional environment variables you can pass:

- `POOLSIDE_STANDALONE_MODEL` to set the model
- `POOLSIDE_STANDALONE_CONTEXT_LENGTH` to set the context length
- `POOLSIDE_STANDALONE_CONTEXT_LENGTH` to override, in tokens, the context length `pool` uses to calculate automatic compaction thresholds

```bash
POOLSIDE_STANDALONE_BASE_URL="http://127.0.0.1:8080" \
Expand All @@ -215,6 +221,8 @@ POOLSIDE_STANDALONE_CONTEXT_LENGTH=200000 \
pool
```

Use a positive `POOLSIDE_STANDALONE_CONTEXT_LENGTH` value no greater than the model server's context window. The override does not change that window and applies only when the selected model appears in the provider's `/v1/models` response.

## MCP servers

`pool` can connect to [Model Context Protocol](https://modelcontextprotocol.io) servers to expose extra tools to the agent. Manage them with `pool mcp`:
Expand Down