Documentation Index
Fetch the complete documentation index at: https://docs.poolside.ai/llms.txt
Use this file to discover all available pages before exploring further.
Run pool to open an interactive session. The agent can read your code, run commands, and write files. It asks for approval before taking action unless you switch to Allow all mode.
For one-shot tasks and scripts, use Automated mode instead.
Start a session
Open a session in your current directory:
Open a session in a specific directory:
Open the session picker to resume a previous session:
Resume a specific session by ID (a session ID is provided when you exit a session):
pool --resume <session-id>
pool with matching shell environment variables:
Write prompts
Type your prompt in the input area at the bottom and press Enter to send.
For multi-line prompts, press Shift+Enter or Alt+Enter to add a line without sending.
Use the up and down arrow keys to browse prompt history for the current directory.
Type ! to enter shell mode and run a command directly from the prompt input box.
Add context with @mentions
Type @ in the prompt to mention a file or directory. pool opens a picker so you can choose what to include.
Answer agent questions
If the agent needs clarification while it is working, it can open a question dialog instead of guessing.
To trigger this flow, tell the agent to ask when needed, for example Ask me a question if anything is ambiguous.
You can select one of the provided options or choose Type your own answer to enter a custom response. Press Esc to decline.
When the agent wants to run a command or write a file, it asks for approval:
- Allow once: Approve only that action
- Always allow: …: Save an approval rule for similar actions for the rest of the session
- Reject: Decline and let the agent work around it if possible
To approve all actions automatically, start the session with --mode always-allow, or switch to Allow all mode with /mode.
For persistent approval rules, path rules, and settings.yaml locations, see Tool permissions.
Modes
When you use Poolside’s built-in agent server, these modes are available:
| 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, then prompts for everything else |
| Allow all | always-allow | Approves tool actions automatically |
| Plan | plan | Plans changes without modifying your codebase |
Shift+Tab to cycle through modes, or use /mode to open the mode selector.
Keyboard shortcuts
| Key | What it does |
|---|
Shift+Tab | Cycle through modes |
Ctrl+M or Alt+M | Open the agent selector |
Esc | Interrupt the agent while it is running |
Esc+Esc | Rewind to the previous turn when idle |
Ctrl+C | Clear the input field when idle |
Ctrl+D+D | Exit when idle with empty input |
Ctrl+G | Toggle tool grouping in the conversation |
Page Up / Page Down | Scroll the conversation |
? while a session is open to see the full shortcut list.
Slash commands
Type / to open the command menu, or type a command directly.
These commands are built into the pool interface:
| Command | What it does |
|---|
/model | Open the agent selector for the current session |
/mode | Open the mode selector |
/clear | Clear conversation history and start a new chat |
/rewind | Roll back to a previous turn |
/feedback | Send feedback or report a bug for the current session |
/debug:dump | Write the raw agent-server message log to a local JSON file |
| Command | What it does |
|---|
/plan | Switch to plan mode |
/share | Get a link to the trajectory viewer for the current session |
/skills | Refresh and list available skills |
/usage | Show token usage and context window state |
/debug:clear-local-sessions | Delete all locally stored session history |
Change the agent
Press Ctrl+M or Alt+M, or use /model to change the agent for the current session or set a new default. The command is named /model because Agent Client Protocol refers to agents, as defined in Poolside, as models.
To start a session with a specific model:
pool --model poolside/laguna-m.1
Rewind a turn
Press Esc+Esc while idle or use /rewind to roll back the last turn. Rewind removes that exchange from the conversation history so the agent does not see it on the next prompt.
Sessions
pool saves sessions automatically. When you exit, pool prints the --resume command for that session so you can continue it later.
View the trajectory
When you use Poolside’s built-in agent server, use /share during a session to get a link to the web-based trajectory viewer.
After a session, browse trajectory files locally:
pool history trajectories --latest
Send feedback
Use /feedback to send feedback or report a bug from the current session.
To attach an earlier session, resume it first with pool -r, then run /feedback.
Use other agent servers
By default pool connects to Poolside’s built-in agent. You can also connect it to any other Agent Client Protocol (ACP)-compatible agent server using --agent-server:
# Claude Agent
pool --agent-server claude-agent-acp
# Codex
pool --agent-server codex-acp
# Gemini
pool --agent-server "gemini --acp"
pool reads agent server configuration from ~/.config/poolside/pool.json by default. If your environment uses a custom configuration directory, pool reads pool.json from the equivalent location there. To set a non-Poolside server as the default:
{
"agent_servers": {
"default": {
"command": "claude-agent-acp"
}
}
}
--:
Use reasoning control only with models behind OpenRouter or another provider that accepts the OpenRouter-style reasoning field. If the underlying model connects directly to the OpenAI Chat Completions API at https://api.openai.com/v1/chat/completions, requests that include the reasoning field fail because OpenAI rejects the field.For Claude 4.6 models through OpenRouter, effort settings other than none are ignored. OpenRouter uses adaptive thinking automatically for those requests.
