Skip to content

docs: plan mode doumentation #6657

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.

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

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions docs/docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@
"pages": [
"features/agent/quick-start",
"features/agent/how-it-works",
"features/agent/plan-mode",
"features/agent/model-setup",
"features/agent/how-to-customize",
"features/agent/context-selection"
Expand Down
45 changes: 30 additions & 15 deletions docs/features/agent/how-it-works.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,22 +17,37 @@ The following handshake describes how Agent uses tools:
6. The model responds, potentially with another tool call and step 2 begins again

<Info>
In [Chat mode](/features/chat/quick-start), tools are **not** included in the
request to the model.
Tool availability varies by mode:
- **Chat mode**: No tools included
- **Plan mode**: Only read-only tools included
- **Agent mode**: All tools included
</Info>

## Built-in tools

Continue includes several built-in tools which provide the model access to IDE functionality:

- **Read file** (`read_file`): read the contents of a file within the project
- **Read currently open file** (`read_currently_open_file`): read the contents of the currently open file
- **Create new file** (`create_new_file`): Create a new file within the project, with path and contents specified by the model
- **Exact search** (`exact_search`): perform a `ripgrep` search within the project
- **Glob search** (`file_glob_search`): perform a glob search on files in the project. Currently limits to 100 output and warns the Agent if limit reached.
- **Run terminal command** (`run_terminal_command`): run a terminal command from the workspace root
- **Search web** (`search_web`): Perform a web search to get top results
- **View diff** (`view_diff`): View the current working git diff
- **View repo map** (`view_repo_map`): request a copy of the repository map—same as the [Repo Map Context Provider](/customize/custom-providers#repository-map)
- **View subdirectory** (`view_subdirectory`): request a copy of a repo map for a specific directory within the project
- **Create Rule Block** (`create_rule_block`): creates a new rule block in `.continue/rules` based on the contents of the conversation
Continue includes several built-in tools which provide the model access to IDE functionality.

### Plan mode tools (read-only)

In Plan mode, only these read-only tools are available:
- **Read file** (`read_file`)
- **Read currently open file** (`read_currently_open_file`)
- **List directory** (`ls`)
- **Glob search** (`glob_search`)
- **Grep search** (`grep_search`)
- **Fetch URL content** (`fetch_url_content`)
- **Search web** (`search_web`)
- **View diff** (`view_diff`)
- **View repo map** (`view_repo_map`)
- **View subdirectory** (`view_subdirectory`)
- **Codebase tool** (`codebase_tool`)

### Agent mode tools (all tools)

In Agent mode, all tools are available including the read-only tools above plus:

- **Create new file** (`create_new_file`): Create a new file within the project
- **Edit file** (`edit_file`): Make changes to existing files
- **Run terminal command** (`run_terminal_command`): Run commands from the workspace root
- **Create Rule Block** (`create_rule_block`): Create a new rule block in `.continue/rules`
- All other write/execute tools for modifying the codebase
49 changes: 49 additions & 0 deletions docs/features/agent/plan-mode.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: "Plan Mode"
description: "Explore and understand code safely with read-only tools"
---

## What is Plan mode?

Plan mode is a restricted environment that provides read-only access to your codebase. It's designed for safe exploration, understanding code, and planning changes without making any modifications.

![Plan mode in action](/images/plan-mode.gif)

### Key features

- **Read-only tools**: Access files, search, and analyze without risk
- **Safe exploration**: Perfect for understanding unfamiliar codebases
- **Planning focus**: Develop implementation strategies before execution
- **MCP support**: Works with all MCP tools alongside built-in read-only tools

### How it works

Plan mode filters the available tools to only include read-only operations. This means you can:
- Read any file in your project
- Search through code with grep and glob patterns
- View repository structure and diffs
- Fetch web content for additional context
- Use all MCP tools

But you cannot:
- Create, edit, or delete files
- Run terminal commands
- Make any system changes

### Getting started

Select "Plan" from the mode selector below the chat input, or use `Cmd/Ctrl + .` to cycle through modes.

![Plan mode selector](/images/plan-mode-selector.png)

For detailed information about tools and usage, see the [Agent documentation](/features/agent/how-it-works), which covers both Agent and Plan modes.

### Common workflow

1. **Start in Plan mode** to explore and understand
2. **Develop your approach** with the model's help
3. **Switch to Agent mode** when ready to implement

<Tip>
Plan mode shares the same interface and context features as Chat and Agent modes. You can use `@` context providers and highlight code just like in other modes.
</Tip>
25 changes: 23 additions & 2 deletions docs/features/agent/quick-start.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,39 @@ title: "Quick Start"

Agent equips the Chat model with the tools needed to handle a wide range of coding tasks, allowing the model to make decisions and save you the work of manually finding context and performing actions.

### When to use each mode

- **Plan mode**: Use when you want to explore code, understand systems, or plan changes without making modifications. Perfect for:
- Understanding unfamiliar codebases
- Planning complex refactors
- Debugging and investigation
- Creating implementation strategies

- **Agent mode**: Use when you're ready to make changes. Ideal for:
- Implementing features
- Fixing bugs
- Running tests and commands
- Executing plans developed in Plan mode

### Use Agent

You can switch to `Agent` in the mode selector below the chat input box.
You can switch to `Agent` in the mode selector below the chat input box. The mode selector offers three options:
- **Chat**: No tools available, pure conversation
- **Plan**: Read-only tools for safe exploration and planning
- **Agent**: All tools available for making changes

![How to select agent mode](/images/mode-select-agent.png)

<Info>
If Agent is disabled with a `Not Supported` message, the selected model or
If Agent or Plan is disabled with a `Not Supported` message, the selected model or
provider doesn't support tools, or Continue doesn't yet support tools with it.
See [Model Blocks](/customization/models) for more information.
</Info>

<Tip>
Use the keyboard shortcut `Cmd/Ctrl + .` to quickly cycle between modes.
</Tip>

### Chat with Agent

Agent lives within the same interface as [Chat](/features/chat/how-it-works), so the same [input](/features/chat/quick-start#1-start-a-conversation) is used to send messages and you can still use the same manual methods of providing context, such as [`@` context providers](/features/chat/quick-start#3-use--for-additional-context) or adding [highlighted code from the editor](/features/chat/quick-start#2-include-code-context).
Expand Down
112 changes: 112 additions & 0 deletions docs/features/plan/how-it-works.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
---
title: "How Plan Works"
description: "Plan mode provides a restricted environment with read-only tools, enabling safe exploration and planning without making changes to your codebase."
---

## Understanding Plan mode

Plan mode is designed to help you understand code and construct plans before making changes. It sits between Chat mode (no tools) and Agent mode (all tools), providing a middle ground where you can explore and analyze without risk.

### The key difference: Read-only tools

While Agent mode has access to all tools including those that modify files, Plan mode restricts access to only read-only tools. This ensures that:

- No files are created, modified, or deleted
- No commands are executed that could change system state
- All exploration is safe and non-destructive
- You can confidently investigate without unintended consequences

## How Plan mode works

When you select Plan mode:

1. Continue sends a special system message instructing the model to focus on understanding and planning
2. The tool list is filtered to include only read-only tools
3. The model can use these tools to explore and analyze your codebase
4. When you're ready to implement changes, you switch to Agent mode

### Available tools in Plan mode

Plan mode includes these read-only built-in tools:

- **Read file** (`read_file`): Read the contents of any file in the project
- **Read currently open file** (`read_currently_open_file`): Read the contents of the currently open file
- **List directory** (`ls`): List files and directories
- **Glob search** (`glob_search`): Search for files matching a pattern
- **Grep search** (`grep_search`): Search file contents using regex patterns
- **Fetch URL content** (`fetch_url_content`): Retrieve content from web URLs
- **Search web** (`search_web`): Perform web searches for additional context
- **View diff** (`view_diff`): View the current git diff
- **View repo map** (`view_repo_map`): Get an overview of the repository structure
- **View subdirectory** (`view_subdirectory`): Get a detailed view of a specific directory
- **Codebase tool** (`codebase_tool`): Advanced codebase analysis capabilities

### MCP tools support

In addition to built-in read-only tools, Plan mode also supports all MCP (Model Context Protocol) tools. This allows integration with external services that provide additional context or analysis capabilities without modifying your local environment.

<Info>
While Plan mode restricts built-in tools to read-only operations, MCP tools are not filtered by Continue. Some MCP tools may have write capabilities that could modify your system or external services. Always verify what actions your MCP tools can perform before using them in Plan mode.
</Info>

## The planning workflow

A typical Plan mode workflow follows these steps:

1. **Exploration**: Use read-only tools to understand the current state
2. **Analysis**: Identify what needs to change and potential impacts
3. **Planning**: Develop a detailed plan for implementation
4. **Verification**: Review the plan and ensure it addresses all requirements
5. **Execution**: Switch to Agent mode to implement the plan

### Example: Planning a refactor

```
User: Help me plan a refactor to extract the authentication logic into a separate module

Plan mode:
1. Reads relevant files to understand current structure
2. Analyzes dependencies and usage patterns
3. Identifies all places that need updates
4. Creates a step-by-step refactoring plan
5. Suggests: "Switch to Agent mode to implement this plan"
```

## System message and behavior

Plan mode uses a dedicated system message that:

- Instructs the model to focus on understanding and planning
- Emphasizes using only read-only tools
- Reminds the model to suggest switching to Agent mode for implementation
- Encourages thorough analysis before suggesting changes

<Info>
The system message can be customized per model. See [How to
Customize](/features/plan/how-to-customize) for details or see it [directly in
the
code](https://github.com/continuedev/continue/blob/main/core/llm/defaultSystemMessages.ts).
</Info>

## When to use Plan mode vs other modes

### Use Plan mode when:

- Exploring unfamiliar codebases
- Planning complex refactors or features
- Debugging and understanding issues
- Reviewing code architecture
- Creating implementation strategies

### Use Chat mode when:

- Having discussions without needing file access
- Asking general programming questions
- Getting explanations without exploring code

### Use Agent mode when:

- Ready to implement changes
- Need to create or modify files
- Want to run commands or tests
- Implementing a plan developed in Plan mode
60 changes: 60 additions & 0 deletions docs/features/plan/quick-start.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
title: "Quick Start"
---

## How to use it

Plan mode provides a safe environment for understanding and constructing plans without making changes. It equips the Chat model with read-only tools, allowing you to explore, analyze, and plan modifications before executing them.

### Use Plan

You can switch to `Plan` in the mode selector below the chat input box.

![How to select plan mode](/images/mode-select-plan.png)

<Info>
If Plan is disabled with a `Not Supported` message, the selected model or
provider doesn't support tools. See [Model Setup](/features/plan/model-setup)
for more information.
</Info>

### Chat with Plan

Plan mode lives within the same interface as [Chat](/features/chat/how-it-works) and [Agent](/features/agent/how-it-works), so the same [input](/features/chat/quick-start#1-start-a-conversation) is used to send messages and you can still use the same manual methods of providing context, such as [`@` context providers](/features/chat/quick-start#3-use--for-additional-context) or adding [highlighted code from the editor](/features/chat/quick-start#2-include-code-context).

#### What makes Plan different

Unlike Agent mode, Plan mode:
- Only uses read-only tools (file reading, searching, analysis)
- Cannot modify, create, or delete files
- Focuses on understanding and planning rather than execution
- Provides a safe environment for exploration

### Common use cases

Plan mode is ideal for:
- **Code exploration**: Understanding how a codebase works
- **Planning refactors**: Analyzing impact before making changes
- **Debugging**: Investigating issues without modifying code
- **Architecture review**: Understanding system design and dependencies
- **Pre-implementation planning**: Thinking through changes before executing

### Example workflow

1. **Start in Plan mode** to explore and understand the task
2. **Develop a plan** with the model's help
3. **Switch to Agent mode** when ready to implement changes

For example, you might say:

> Help me understand how the authentication system works and plan improvements to add OAuth support

Plan mode will analyze the existing code, understand the current implementation, and help you create a detailed plan—all without making any changes.

## Switching to execution

When you're ready to implement your plan, simply switch to Agent mode using the mode selector or keyboard shortcut (`Cmd/Ctrl + .`). The conversation context carries over, so Agent mode can immediately start implementing the plan you developed.

<Tip>
Use the keyboard shortcut `Cmd/Ctrl + .` to quickly cycle between Chat, Plan, and Agent modes.
</Tip>
10 changes: 10 additions & 0 deletions docs/getting-started/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -43,4 +43,14 @@ description: "To quickly understand what you can do with Continue, check out eac
Learn more about [Agent](/features/agent/quick-start)
</Info>
</Tab>

<Tab title="Plan">
[Plan](/features/agent/plan-mode) provides a safe environment with read-only tools for exploring code and planning changes

![plan](/images/plan-mode.gif)

<Info>
Learn more about [Plan](/features/agent/plan-mode)
</Info>
</Tab>
</Tabs>
Binary file added docs/images/plan-mode-compressed.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/plan-mode-selector.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/plan-mode.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading