Skip to main content
BETA This feature is in beta and may change before general availability.

​
Overview

Use plan mode when you want to review an implementation approach before the agent changes your code. In plan mode, the agent reads and explores your codebase, asks clarifying questions, and writes an implementation plan for you to review. When the plan is ready, Poolside asks whether you want to switch back to build mode and implement it. You decide whether to move forward. Use build mode when you want the agent to start implementing right away. Build mode is the default mode, and it can read and modify source files as it works. Conversation history, workspace context, and instructions such as AGENTS.md apply across modes within a conversation.
ModeBest forChanges code
Build modeStart implementing right awayYes
Plan mode (beta)Review the approach before implementationNo

​
What you can do in plan mode

Use plan mode to let the agent investigate the work first and show you its proposed approach before implementation starts. The agent can also ask to switch into plan mode for large or ambiguous tasks. In plan mode, the agent can:
  • Read and explore your workspace
  • Analyze relevant files and dependencies
  • Ask clarifying questions
  • Produce a written implementation plan
Plan mode focuses on planning rather than modifying source files. Entering plan mode and saving the plan do not require the usual approval prompts for code changes in build mode. Poolside saves each plan as a Markdown file on disk. If you are working outside a sandbox, it stores the file in your local Poolside state directory. If you are working in a sandbox, it stores the file at .poolside/plans/ in your current workspace. The file remains available after the session ends. In pool code, the saved path is clickable, so you can open the plan directly in your editor. Each saved plan includes a short overview, an implementation approach with concrete steps and code snippets, and a brief testing strategy. If the agent asks to switch into plan mode, you can approve the request to enter plan mode or deny it to stay in your current mode. After you enter plan mode, the workflow is the same as when you enable it yourself. In the IDE, you see the Plan mode banner. When the plan is ready, Poolside asks to switch back to build mode. You can approve the switch to start implementing, or deny it to stay in plan mode and keep refining the plan.

​
When to use plan mode

Use plan mode when you want to think through a complex feature and discuss approaches with the agent before making changes. Plan mode is most useful when the cost of a wrong approach is high or when early decisions are hard to undo. Use plan mode for:
  • Complex refactors
  • Exploring the codebase before making changes
  • New features or multi-step changes that span multiple files
  • Discussing tradeoffs and iterating on an approach before implementation
For small, well-scoped changes, staying in build mode is usually faster. Poolside can also ask to switch into plan mode when it determines that a task is too large or ambiguous to start implementing without first exploring and planning.

​
Use plan mode

​
In the IDE

In Poolside Assistant, enter plan mode by typing /plan in the prompt input box or by clicking the  /  icon and selecting plan from the commands menu. Press Shift+Tab to toggle between build mode and plan mode. To leave plan mode, click the close button in the Plan mode banner or press Shift+Tab. For more information about IDE commands and shortcuts, see Commands. To customize the toggle shortcut, add a binding for poolside.togglePlanMode in your VS Code keybindings. For example: 
[
  {
    "command": "poolside.togglePlanMode",
    "key": "ctrl+alt+p",
    "mac": "cmd+alt+p",
    "when": "poolside.webviewFocus"
  }
]

​
In the CLI

In pool code, enter plan mode by typing /plan when you want to review a plan before the agent starts implementing. If you switch from build mode into plan mode, Poolside keeps track of the approval mode you were using in build mode, such as default for Always Ask or always-allow for Always Allow. You can also switch modes by typing /mode plan or pressing Shift+Tab to cycle through available modes. To leave plan mode, switch back to build mode when you are ready to implement by using Shift+Tab or /mode default. When you switch from plan mode back to build mode, Poolside restores the approval mode you were using before. For example, if you were using Always Allow, it returns to Always Allow after plan mode ends.

​
Review and continue from a plan

​
In the IDE

In Poolside Assistant, the chat panel displays a Plan mode banner so you can confirm that the agent is still planning rather than implementing. If you reopen a conversation that is still in plan mode, Poolside shows the Plan mode banner again. When the plan is ready, review it in the conversation before switching to build mode to implement it. Click Allow Once to switch to build mode, or click Deny to keep reviewing or discussing the plan. Clicking Deny keeps the agent in plan mode and does not cancel the task.

​
In the CLI

In pool code, when the plan is ready, approve the prompt to switch to build mode, or decline it to keep reviewing or discussing the plan. Declining keeps the agent in plan mode and does not cancel the task. If you resume the same session later, Poolside reuses the existing plan file for that conversation.