Interactive mode - Poolside

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. Your login choice, such as standalone Poolside or a Poolside deployment, determines which service pool connects to, not which CLI mode you use. If you run pool in your terminal, you are using interactive mode.

Start a session

Open a session in your current directory:

pool

Open a session in a specific directory:

pool -C <project-path>

Require a configured sandbox for the Poolside agent server:

pool --sandbox required

Use --sandbox disabled only when you want to run without a configured sandbox. Open the session picker to resume a previous session from the current directory:

pool -r

Open the agent server picker to choose a configured ACP-compatible agent server for the session:

pool -s

Resume a specific session by ID (a session ID is provided when you exit a session):

pool --resume <session-id>

For MCP server input variables, start pool with matching shell environment variables:

KEY=VALUE pool

Write prompts

Type your prompt in the input area at the bottom and press Enter to send. To find the newline shortcut for your terminal, press ? with an empty input field. Common shortcuts are:

macOS and Linux: Shift+Enter when your terminal supports key disambiguation, or Alt+Enter as a fallback
Windows: Shift+Enter when supported by your terminal, or Ctrl+Enter as a fallback. Use Alt+Enter when connected over SSH.

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. You can select text in the conversation output using your terminal’s selection controls.

Add context

Type @ in the prompt to mention a file or directory. pool opens a picker so you can choose what to include. To add an image from your clipboard, paste it into the prompt input box with Ctrl+V.

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.

Notifications

pool can send notifications when a turn ends, when an approval prompt needs your response, or when the agent asks a question. Notifications appear only when the pool session is not focused. When you run pool in cmux, pool can also show notifications and status icons.

Approve tool actions

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
Accept edits for this session: For file write approvals, switch to Accept edits mode 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 the Poolside 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

Press Shift+Tab to cycle through modes, or use /mode to open the mode selector.

Keyboard shortcuts

CLI shortcuts use the key names shown by your terminal. On macOS, use Ctrl for CLI shortcuts such as Ctrl+M, Ctrl+C, and Ctrl+V. Command shortcuts are handled by your terminal application, not by pool.

Key	What it does
`Enter`	Send the prompt
`Shift+Enter`, `Alt+Enter`, or `Ctrl+Enter`	Insert a new line, depending on your operating system and terminal
`Up` / `Down`	Browse prompt history when the cursor is at the start or end of the prompt
`/`	Show available slash commands
`?`	Show all keyboard shortcuts when the input field is empty
`Shift+Tab`	Cycle through modes
`Ctrl+M` or `Alt+M`	Open the agent selector
`Esc`	Interrupt the agent while it is running
`Esc`, then `Esc`	Rewind to the previous turn when idle
`Ctrl+C`, then `Ctrl+C`	Exit when idle. The first press clears the input field.
`Ctrl+D`, then `Ctrl+D`	Exit when idle with an empty input field
`Ctrl+G`	Toggle tool grouping in the conversation
`Ctrl+V`	Paste clipboard text or attach a clipboard image
`Page Up` / `Page Down`	Scroll the conversation

Press ? with an empty input field to see the shortcut list for your terminal.

Where	Key	What it does
Slash command menu	`Up` / `Down`	Move through commands
Slash command menu	`Tab`	Complete the selected command or run a command that opens immediately
Slash command menu	`Enter`	Complete the selected command, or send the prompt if no command is selected
Slash command menu	`Esc`	Close the command menu
File picker	`Up` / `Down`	Move through files and directories
File picker	`Tab` or `Enter`	Add the selected file or directory mention
File picker	`Esc`	Close the file picker
Session picker	Type text	Filter sessions
Session picker	`Up` / `Down` or `Ctrl+P` / `Ctrl+N`	Move through sessions
Session picker	`Enter`	Resume the selected session
Session picker	`Tab`	Switch between current-directory sessions and sessions from all directories
Session picker	`Esc`	Start a new session
Session picker	`Ctrl+C`	Cancel and exit the picker

Slash commands

Type / to open the command menu, or type a command directly. The commands you see can include terminal UI commands and commands from the connected agent server. Non-Poolside ACP servers can expose a different set of server-provided slash commands. 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
`/new` or `/clear`	Clear conversation history and start a new chat
`/copy`	Copy the last assistant response to the clipboard
`/rewind`	Roll back to a previous turn
`/rename`	Rename the current session
`/feedback`	Open a feedback draft and optionally attach logs
`/quit` or `/exit`	Exit the session
`/debug:dump`	Write the raw agent-server message log to a local JSON file

When you use the Poolside agent server, these additional commands are available:

Command	What it does
`/plan`	Switch to plan mode
`/compact`	Compact conversation context. Add guidance after the command to tell the agent what to preserve, such as `/compact preserve tool call errors`.
`/share`	Get a link to the trajectory viewer for the current session
`/mcp`	Show MCP servers, connection status, and tools for the current session
`/sandbox`	Show local sandbox configuration
`/sandbox-apply-to-host`	Review pending sandbox filesystem changes and apply them to the host workspace when available
`/skills`	Refresh and list available skills
`/usage`	Show token usage and context window state

You can also ask pool about its own commands, capabilities, and current behavior. The Poolside agent server uses a built-in introspection skill to answer questions about itself.

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, then 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. Use /rename to rename the current session. The session picker opened by pool -r shows renamed sessions from the current directory by default. Press Tab in the picker to switch between current-directory sessions and sessions from all directories.

MCP servers

Use /mcp to see MCP servers, connection status, and tools for the current session.

View the trajectory

When you use the Poolside 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 open a feedback draft for the current session. You can choose whether to attach logs. To attach an earlier session, resume it first with pool -r, then run /feedback.

Use other agent servers

By default, pool connects to the Poolside agent server. 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"

To choose from configured agent servers interactively, run pool -s. 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"
    }
  }
}

​Start a session

​Write prompts

​Add context

​Answer agent questions

​Notifications

​Approve tool actions

​Modes

​Keyboard shortcuts

​Picker and menu shortcuts

​Slash commands

​Change the agent

​Rewind a turn

​Sessions

​MCP servers

​View the trajectory

​Send feedback

​Use other agent servers

​Related resources