scriptoriumadmin/Roo-Code
1
0
Fork 0
mirror of https://github.com/RooVetGit/Roo-Code.git synced 2026-08-28 05:27:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add docs app and GitHub Pages deploy (#12344)

Browse source 
* Add docs app and Pages deploy

* Configure knip for docs app
This commit is contained in:
Bruno Bergher 2026-05-12 14:23:21 +01:00 • committed by GitHub
parent 2428199851
commit 28acb6acf2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
911 changed files with 48592 additions and 82 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
.github/workflows/docs-pages.yml vendored Normal file
View file

@ -0,0 +1,55 @@
name: Deploy docs to GitHub Pages
on:
push:
branches:
- main
paths:
- "apps/docs/**"
- ".github/workflows/docs-pages.yml"
- ".github/actions/setup-node-pnpm/**"
- "package.json"
- "pnpm-lock.yaml"
- "pnpm-workspace.yaml"
workflow_dispatch:
concurrency:
group: docs-pages
cancel-in-progress: true
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Setup Node.js and pnpm
uses: ./.github/actions/setup-node-pnpm
with:
install-args: "--frozen-lockfile"
- name: Run type check
run: pnpm --filter @roo-code/docs check-types
- name: Run lint
run: pnpm --filter @roo-code/docs lint
- name: Build docs
run: pnpm --filter @roo-code/docs build
- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v3
with:
path: apps/docs/build
deploy:
runs-on: ubuntu-latest
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4

1
apps/docs/.env.example Normal file
View file

@ -0,0 +1 @@
# No environment variables are required for local docs development.

31
apps/docs/.gitignore vendored Normal file
View file

@ -0,0 +1,31 @@
# Dependencies
/node_modules
# Production
/build
# Generated files
.docusaurus
.cache-loader
*.js
!src/**/*.js
# Misc
.DS_Store
.env
!.env.example
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.devcontainer
TEMP/
.history/
.roo/mcp.json

201
apps/docs/LICENSE Normal file
View file

@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

21
apps/docs/README.md Normal file
View file

@ -0,0 +1,21 @@
# Roo Code Docs
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator, and lives at https://roocode.github.io
### Installation
```
$ pnpm install
```
### Local Development
```
$ pnpm start
```
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
### License
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

164
apps/docs/docs/advanced-usage/available-tools/access-mcp-resource.md Normal file
View file

@ -0,0 +1,164 @@
---
description: Learn how the access_mcp_resource tool retrieves data from Model Context Protocol servers for additional context in Roo Code tasks.
keywords:
- access_mcp_resource
- MCP
- Model Context Protocol
- MCP resources
- Roo Code tools
- context retrieval
- API integration
---
# access_mcp_resource
The `access_mcp_resource` tool retrieves data from resources exposed by connected Model Context Protocol (MCP) servers. It allows Roo to access files, API responses, documentation, or system information that provides additional context for tasks.
---
## Parameters
The tool accepts these parameters:
- `server_name` (required): The name of the MCP server providing the resource
- `uri` (required): The URI identifying the specific resource to access
---
## What It Does
This tool connects to MCP servers and fetches data from their exposed resources. Unlike `use_mcp_tool` which executes actions, this tool specifically retrieves information that serves as context for tasks.
---
## When is it used?
- When Roo needs additional context from external systems
- When Roo needs to access domain-specific data from specialized MCP servers
- When Roo needs to retrieve reference documentation hosted by MCP servers
- When Roo needs to integrate real-time data from external APIs via MCP
---
## Key Features
- Retrieves both text and image data from MCP resources
- Requires user approval before executing resource access
- Uses URI-based addressing to precisely identify resources
- Integrates with the Model Context Protocol SDK
- Displays resource content appropriately based on content type
- Supports timeouts for reliable network operations
- Handles server connection states (connected, connecting, disconnected)
- Discovers available resources from connected servers
- Processes structured response data with metadata
- Handles image content special rendering
---
## Limitations
- Depends on external MCP servers being available and connected
- Limited to the resources provided by connected servers
- Cannot access resources from disabled servers
- Network issues can affect reliability and performance
- Resource access subject to configured timeouts
- URI formats are determined by the specific MCP server implementation
- No offline or cached resource access capabilities
---
## How It Works
When the `access_mcp_resource` tool is invoked, it follows this process:
1. **Connection Validation**:
- Verifies that an MCP hub is available and initialized
- Confirms the specified server exists in the connection list
- Checks if the server is disabled (returns an error if it is)
2. **User Approval**:
- Presents the resource access request to the user for approval
- Provides server name and resource URI for user verification
- Proceeds only if the user approves the resource access
3. **Resource Request**:
- Uses the Model Context Protocol SDK to communicate with servers
- Makes a `resources/read` request to the server through the MCP hub
- Applies configured timeouts to prevent hanging on unresponsive servers
4. **Response Processing**:
- Receives a structured response with metadata and content arrays
- Processes text content for display to the user
- Handles image data specially for appropriate display
- Returns the processed resource data to Roo for use in the current task
---
## Resource Types
MCP servers can provide two main types of resources:
1. **Standard Resources**:
- Fixed resources with specific URIs
- Defined name, description, and MIME type
- Direct access without parameters
- Typically represent static data or real-time information
2. **Resource Templates**:
- Parameterized resources with placeholder values in URIs
- Allow dynamic resource generation based on provided parameters
- Can represent queries or filtered views of data
- More flexible but require additional URI formatting
---
## Examples When Used
- When helping with API development, Roo retrieves endpoint specifications from MCP resources to ensure correct implementation.
- When assisting with data visualization, Roo accesses current data samples from connected MCP servers.
- When working in specialized domains, Roo retrieves technical documentation to provide accurate guidance.
- When generating industry-specific code, Roo references compliance requirements from documentation resources.
---
## Usage Examples
Accessing current weather data:
```
<access_mcp_resource>
<server_name>weather-server</server_name>
<uri>weather://san-francisco/current</uri>
</access_mcp_resource>
```
Retrieving API documentation:
```
<access_mcp_resource>
<server_name>api-docs</server_name>
<uri>docs://payment-service/endpoints</uri>
</access_mcp_resource>
```
Accessing domain-specific knowledge:
```
<access_mcp_resource>
<server_name>knowledge-base</server_name>
<uri>kb://medical/terminology/common</uri>
</access_mcp_resource>
```
Fetching system configuration:
```
<access_mcp_resource>
<server_name>infra-monitor</server_name>
<uri>config://production/database</uri>
</access_mcp_resource>
```

120
apps/docs/docs/advanced-usage/available-tools/apply-diff.md Normal file
View file

@ -0,0 +1,120 @@
---
description: Master the apply_diff tool for making surgical code changes using fuzzy matching and line hints in Roo Code with multi-file support.
keywords:
- apply_diff
- file editing
- code modifications
- fuzzy matching
- diff tool
- Roo Code tools
- multi-file edits
---
# apply_diff
The `apply_diff` tool makes precise, surgical changes to files by specifying exactly what content to replace. It uses a sophisticated strategy for finding and applying changes while maintaining proper code formatting and structure.
---
## Parameters
The tool accepts these parameters:
- `path` (required): The path of the file to modify relative to the current working directory.
- `diff` (required): The search/replace block defining the changes using a format specific to the active diff strategy.
- `start_line` (optional): A hint for where the search content begins. _Note: This top-level parameter appears unused by the current main strategy, which relies on `:start_line:` within the diff content._
- `end_line` (optional): A hint for where the search content ends. _Note: This top-level parameter appears unused by the current main strategy._
---
## What It Does
This tool applies targeted changes to existing files using fuzzy matching guided by line number hints to locate and replace content precisely. Unlike simple search and replace, it identifies the exact block for replacement based on the provided content and location hints.
---
## When is it used?
- When Roo needs to make precise changes to existing code without rewriting entire files.
- When refactoring specific sections of code while maintaining surrounding context.
- When fixing bugs in existing code with surgical precision.
- When implementing feature enhancements that modify only certain parts of a file.
---
## Key Features
- Uses fuzzy matching (Levenshtein distance on normalized strings) guided by a `:start_line:` hint, with configurable confidence thresholds (typically 0.8-1.0).
- Provides context around matches using `BUFFER_LINES` (default 40).
- Performs a middle-out search within a configurable context window (`bufferLines`) around the hinted start line.
- Preserves code formatting and indentation passively by replacing exact blocks.
- Shows changes in a diff view for user review and editing before applying.
- Tracks consecutive errors per file (`consecutiveMistakeCountForApplyDiff`) to prevent repeated failures.
- Validates file access against `.rooignore` rules.
- Handles multi-line edits effectively.
---
## Limitations
- Works best with unique, distinctive code sections for reliable identification.
- Performance can vary with very large files or highly repetitive code patterns.
- Fuzzy matching might occasionally select incorrect locations if content is ambiguous.
- Each diff strategy has specific format requirements.
- Complex edits might require careful strategy selection or manual review.
---
## How It Works
When the `apply_diff` tool is invoked, it follows this process:
1. **Parameter Validation**: Validates required `path` and `diff` parameters.
2. **RooIgnore Check**: Validates if the target file path is allowed by `.rooignore` rules.
3. **File Analysis**: Loads the target file content.
4. **Match Finding**: Uses a fuzzy matching algorithm (Levenshtein on normalized strings) guided by the `:start_line:` hint within a context window (`BUFFER_LINES`), searching middle-out to locate the target content based on the confidence threshold.
5. **Change Preparation**: Generates the proposed changes by replacing the identified block.
6. **User Interaction**:
- Displays the changes in a diff view.
- Allows the user to review and potentially edit the proposed changes.
- Waits for user approval or rejection.
7. **Change Application**: If approved, applies the changes (potentially including user edits) to the file.
8. **Error Handling**: If errors occur (e.g., match failure, partial application), increments the `consecutiveMistakeCountForApplyDiff` for the file and reports the failure type.
9. **Feedback**: Returns the result, including any user feedback or error details.
---
## Diff Format Requirements
The `<diff>` parameter requires a specific format supporting one or more changes in a single request. Each change block requires a line number hint for the original content.
- **Requires**: Exact match for the `SEARCH` block content (within the fuzzy threshold), including whitespace and indentation. The `:start_line:` number hint is mandatory within each block. The `:end_line:` hint is optional (but supported by the parser). Markers like `<<<<<<<` within the file's content must be escaped (`\\`) in the SEARCH block.
Example format for the `<diff>` block:
```diff
<<<<<<< SEARCH
:start_line:10
:end_line:12
-------
// Old calculation logic
const result = value * 0.9;
return result;
=======
// Updated calculation logic with logging
console.log(`Calculating for value: ${value}`);
const result = value * 0.95; // Adjusted factor
return result;
>>>>>>> REPLACE
<<<<<<< SEARCH
:start_line:25
:end_line:25
-------
const defaultTimeout = 5000;
=======
const defaultTimeout = 10000; // Increased timeout
>>>>>>> REPLACE
```
---

110
apps/docs/docs/advanced-usage/available-tools/apply-patch.md Normal file
View file

@ -0,0 +1,110 @@
---
description: Apply unified diff patches to multiple files in a single operation using the apply_patch tool in Roo Code.
keywords:
- apply_patch
- patch
- unified diff
- multi-file edits
- file operations
- Roo Code tools
- diff patches
---
# apply_patch
The `apply_patch` tool applies unified diff patches to multiple files in a single operation. It supports custom patch headers for adding, deleting, and updating files, making it ideal for complex multi-file refactoring operations.
---
## Parameters
The tool accepts these parameters:
- `patch` (required): A unified diff patch string with custom headers. Supports `*** Add File:`, `*** Delete File:`, and `*** Update File:` headers.
---
## What It Does
This tool processes unified diff patches containing operations for multiple files. It parses the patch content, identifies file operations (add, delete, update), and applies the changes atomically. Unlike [`apply_diff`](/advanced-usage/available-tools/apply-diff) which handles single-file search-and-replace operations, `apply_patch` works with traditional unified diff format.
---
## When is it used?
- When applying patches generated by version control systems or diff tools
- When performing complex multi-file refactoring with precise line-level changes
- When migrating code changes from one branch or repository to another
- When bulk-adding, updating, or removing multiple files in one operation
- When working with patches from external sources or automated tools
---
## Key Features
- Supports multiple files in a single patch operation
- Handles file addition, deletion, and modification
- Uses unified diff format for precise line-level control
- Custom headers (`*** Add File:`, `*** Delete File:`, `*** Update File:`) for clarity
- Atomic operations with validation before applying changes
- Compatible with standard diff/patch tooling output
---
## Limitations
- Requires proper unified diff format syntax
- Line numbers and context must match existing file content
- Cannot apply patches with conflicts or mismatched context
- Less flexible than search-and-replace tools for fuzzy matching
- Requires exact line-level accuracy in patches
---
## How It Works
When the `apply_patch` tool is invoked, it follows this process:
1. **Patch Parsing**: Parses the patch string to identify custom headers (`*** Add File:`, `*** Delete File:`, `*** Update File:`) and unified diff blocks.
2. **Operation Identification**: Groups changes by file path and operation type (add, delete, update).
3. **Validation**: Validates that target files exist (for updates/deletes) or can be created (for adds).
4. **RooIgnore Check**: Ensures target files are not restricted by `.rooignore` rules.
5. **User Review**: Presents the patch operations for user review and approval.
6. **Application**: Applies approved changes to each file sequentially.
7. **Feedback**: Reports success or failure for each file operation.
---
## Patch Format
The patch format uses custom headers followed by unified diff blocks:
```diff
*** Add File: src/utils/newHelper.ts
--- /dev/null
+++ b/src/utils/newHelper.ts
@@ -0,0 +1,5 @@
+export function helperFunction(value: string): string {
+ return value.toUpperCase();
+}
*** Update File: src/main.ts
--- a/src/main.ts
+++ b/src/main.ts
@@ -10,7 +10,7 @@
import { config } from './config';
-const timeout = 5000;
+const timeout = 10000;
function main() {
*** Delete File: src/deprecated/oldUtil.ts
```
---
## Relation to Other Tools
- [`apply_diff`](/advanced-usage/available-tools/apply-diff): Use for single-file search-and-replace with fuzzy matching
- `apply_patch`: Use for multi-file operations with unified diff format
- [`write_to_file`](/advanced-usage/available-tools/write-to-file): Use for creating entire new files

208
apps/docs/docs/advanced-usage/available-tools/ask-followup-question.md Normal file
View file

@ -0,0 +1,208 @@
---
description: Enable interactive communication in Roo Code with the ask_followup_question tool for gathering clarification and user preferences.
keywords:
- ask_followup_question
- user interaction
- interactive communication
- Roo Code tools
- clarification
- user feedback
---
# ask_followup_question
The `ask_followup_question` tool enables interactive communication by asking specific questions to gather additional information needed to complete tasks effectively.
---
## Parameters
The tool accepts these parameters:
- `question` (required): The specific question to ask the user
- `follow_up` (optional): A list of 2-4 suggested answers that help guide user responses, each within `<suggest>` tags
---
## What It Does
This tool creates a conversational interface between Roo and the user, allowing for gathering clarification, additional details, or user preferences when facing ambiguities or decision points. Each question can include suggested responses to streamline the interaction.
---
## When is it used?
- When critical information is missing from the original request
- When Roo needs to choose between multiple valid implementation approaches
- When technical details or preferences are required to proceed
- When Roo encounters ambiguities that need resolution
- When additional context would significantly improve the solution quality
---
## Key Features
- Provides a structured way to gather specific information without breaking workflow
- Includes suggested answers to reduce user typing and guide responses
- Maintains conversation history and context across interactions
- Supports responses containing images and code snippets
- Available in all modes as part of the "always available" tool set
- Enables direct user guidance on implementation decisions
- Formats responses with `<answer>` tags to distinguish them from regular conversation
- Resets consecutive error counter when used successfully
---
## Limitations
- Limited to asking one specific question per tool use
- Presents suggestions as selectable options in the UI
- Cannot force structured responses – users can still respond freely
- Excessive use can slow down task completion and create a fragmented experience
- Suggested answers must be complete, with no placeholders requiring user edits
- No built-in validation for user responses
- Contains no mechanism to enforce specific answer formats
---
## How It Works
When the `ask_followup_question` tool is invoked, it follows this process:
1. **Parameter Validation**: Validates the required `question` parameter and checks for optional suggestions
- Ensures question text is provided
- Parses any suggested answers from the `follow_up` parameter using the `fast-xml-parser` library
- Normalizes suggestions into an array format even if there's only one suggestion
2. **JSON Transformation**: Converts the XML structure into a standardized JSON format for UI display
```typescript
{
question: "User's question here",
suggest: [
{ answer: "Suggestion 1" },
{ answer: "Suggestion 2" }
]
}
```
3. **UI Integration**:
- Passes the JSON structure to the UI layer via the `ask("followup", ...)` method
- Displays selectable suggestion buttons to the user in the interface
- Creates an interactive experience for selecting or typing a response
4. **Response Collection and Processing**:
- Captures user text input and any images included in the response
- Wraps user responses in `<answer>` tags when returning to the assistant
- Preserves any images included in the user's response
- Maintains the conversational context by adding the response to the history
- Resets the consecutive error counter when the tool is used successfully
5. **Error Handling**:
- Tracks consecutive mistakes using a counter
- Resets the counter when the tool is used successfully
- Provides specific error messages:
- For missing parameters: "Missing required parameter 'question'"
- For XML parsing: "Failed to parse operations: [error message]"
- For invalid format: "Invalid operations xml format"
- Contains safeguards to prevent tool execution when required parameters are missing
- Increments consecutive mistake count when errors occur
---
## Workflow Sequence
The question-answer cycle follows this sequence:
1. **Information Gap Recognition**: Roo identifies missing information needed to proceed
2. **Specific Question Creation**: Roo formulates a clear, targeted question
3. **Suggestion Development**: Roo creates relevant suggested answers (optional but recommended)
4. **Tool Invocation**: Assistant invokes the tool with question and optional suggestions
5. **UI Presentation**: Question and suggestions are displayed to the user as interactive elements
6. **User Response**: The user selects a suggestion or provides a custom answer
7. **Message Handling**: System handles both partial and complete messages
- For streaming responses, processes chunks as they arrive
- For complete messages, processes the entire response at once
- Maintains state consistency regardless of message chunking
8. **Response Processing**: System wraps the response in `<answer>` tags and preserves images
9. **Context Integration**: Response is added to the conversation history
10. **Task Continuation**: Roo proceeds with the task using the new information
---
## Examples When Used
- When developing a web application, Roo might ask about preferred styling frameworks (Bootstrap, Tailwind, custom CSS)
- When creating an API, Roo might ask about authentication methods (JWT, OAuth, API keys)
- When refactoring code, Roo might ask about prioritizing performance vs. readability
- When setting up a database, Roo might ask about specific schema design preferences
- When creating a custom feature, Roo might ask about specific behavior expectations
- When troubleshooting errors, Roo might ask about specific environment details
---
## Response Format
When a user responds to a question, the response is formatted with `<answer>` tags for clarity and consistency. This format helps clearly separate the user's answer from other conversation elements.
Example response format:
```
<answer>
Use Tailwind CSS for utility-first styling with maximum flexibility
</answer>
```
Key characteristics of the response format:
- Surrounded by `<answer>` tags
- Preserves formatting of the original response
- Maintains images if included in the response
- Returns the complete text, even for long responses
---
## Usage Examples
Asking about implementation preferences:
```
<ask_followup_question>
<question>Which styling approach would you prefer for this web application?</question>
<follow_up>
<suggest>Use Bootstrap for rapid development with consistent components</suggest>
<suggest>Use Tailwind CSS for utility-first styling with maximum flexibility</suggest>
<suggest>Use vanilla CSS with custom styling for complete control and minimal dependencies</suggest>
</follow_up>
</ask_followup_question>
```
Requesting technical clarification:
```
<ask_followup_question>
<question>What database should this application use for storing user data?</question>
<follow_up>
<suggest>MongoDB for flexible schema and document-based storage</suggest>
<suggest>PostgreSQL for relational data with strong consistency guarantees</suggest>
<suggest>Firebase for real-time updates and simplified backend management</suggest>
<suggest>SQLite for lightweight local storage without external dependencies</suggest>
</follow_up>
</ask_followup_question>
```
Addressing ambiguity in requirements:
```
<ask_followup_question>
<question>How should the application handle user authentication?</question>
<follow_up>
<suggest>Implement email/password authentication with account verification</suggest>
<suggest>Use social login providers (Google, GitHub, etc.) for quick signup</suggest>
<suggest>Implement both email/password and social login options</suggest>
</follow_up>
</ask_followup_question>
```

215
apps/docs/docs/advanced-usage/available-tools/attempt-completion.md Normal file
View file

@ -0,0 +1,215 @@
---
description: Learn how the attempt_completion tool signals task completion, presents results, and enables iterative refinement in Roo Code.
keywords:
- attempt_completion
- task completion
- result presentation
- Roo Code tools
- user feedback
- task summary
---
# attempt_completion
The `attempt_completion` tool signals that Roo believes a task is complete and presents results to the user. It provides a summary of what was accomplished, optionally includes a command to demonstrate the result, and supports continued refinement through user feedback.
---
## Parameters
The tool accepts these parameters:
- `result` (required): The final result description summarizing what was accomplished
- `command` (optional): A CLI command to execute to demonstrate the result
---
## What It Does
This tool marks the end of a task by presenting a final summary of what was accomplished. It signals to both the user and the system that the current task is complete. When a command is provided, it can also demonstrate the result through a live execution.
---
## When is it used?
- When Roo believes the user's task has been completed
- When summarizing what changes or improvements were made
- When demonstrating the current result with a command execution
- When providing a checkpoint for user feedback on the solution
- When transitioning from one phase of work to potential refinements
---
## Key Features
- Provides a clear signal that Roo believes the task is complete
- Summarizes accomplishments in a concise message
- Optionally demonstrates results through command execution
- Enables user feedback for further refinements
- Displays results in a special UI format distinct from regular messages
- Maintains a structured conversation flow by providing checkpoints
- Supports subtask completion within larger workflows
- Ensures users receive a clear summary of what was done
- Available in all modes as part of the "always available" tool group
---
## Limitations
- Should not be used until previous tool uses are confirmed successful (guideline, not enforced)
- Limited to a single command for result demonstration
- Cannot present multiple command options
- Commands require user approval before execution
- Limited to demonstrating results that can be shown via CLI commands
- Cannot be used for partial task completion or progress updates
- Result formatting strips XML closing tags through internal processing
---
## How It Works
When the `attempt_completion` tool is invoked, it follows this process:
1. **Safety Consideration** (guideline, not enforced):
- The AI is instructed to confirm previous tool uses were successful
- This is a best practice rather than a programmatically enforced mechanism
2. **Result Presentation**:
- Displays the completion message to the user in a special "completion_result" UI format
- Removes XML closing tags from the result text using the `removeClosingTag` function
- Presents the result differently than regular messages for visual distinction
3. **Command Execution** (if provided):
- Requests user approval before executing the command
- Only executes if the user approves
- Executes the command using the system's command execution functionality
- Shows the result of the command to the user
4. **Feedback Collection**:
- Waits for user feedback on the completion result
- Processes this feedback and returns it to the AI
- Enables continued refinement based on user input
5. **Task Completion and Continuation**:
- Signals the task as completed in the system
- Captures telemetry data for the completed task
- For subtasks, offers to finish the subtask and resume the parent task
- Supports continued conversation through the feedback mechanism
6. **Implementation Integration**:
- Tool results are parsed through the system's parsing mechanism in `parse-assistant-message.ts`
- The tool is part of the "ALWAYS_AVAILABLE_TOOLS" constant, making it available in all modes
---
## Result Formatting Guidelines
The result message should follow these guidelines:
- Clearly communicate what was accomplished
- Be concise but complete
- Focus on the value delivered to the user
- Avoid unnecessary pleasantries or filler text
- Maintain a professional, straightforward tone
- Present information in a way that's easy to scan and understand
- Acknowledge that the user may provide feedback for further refinements
Note: The system automatically strips XML closing tags from the result text through the `removeClosingTag` function.
---
## Command Selection Guidelines
When including a command, follow these guidelines:
- Choose commands that visually demonstrate the result
- Prefer commands that show the user what was created or modified
- Examples include:
- `open index.html` to display a created website
- `npm start` to launch a development server
- `python app.py` to run a created application
- Avoid commands that merely print text (like `echo` or `cat`)
- Remember that commands require user approval before execution
- Ensure the command is valid for the user's operating system
---
## Feedback and UI Representation
The `attempt_completion` tool has a unique feedback mechanism:
- Results appear in a special "completion_result" UI format distinct from regular messages
- The system waits for user feedback after presenting the result
- Feedback is processed and returned to Roo for further refinements
- This creates an iterative improvement cycle rather than ending the conversation
- The UI includes special elements for providing feedback
- Results serve as clear checkpoints in the conversation flow
When used within subtasks:
- The system offers to finish the subtask and resume the parent task
- If approved, the subtask is completed with a summary
- The parent task resumes with context from the completed subtask
- This enables complex, nested workflows while maintaining context
---
## Examples When Used
- When creating a website, Roo presents the solution and uses `open index.html` to show the result. The user provides feedback, and Roo refines the design.
- When implementing a feature, Roo summarizes the changes and their impact. The user requests additional test coverage, and Roo continues the task.
- When fixing bugs, Roo explains what was fixed and how the solution addresses the root cause. The user confirms the fix works.
- When setting up a development environment, Roo confirms all components are installed. The user requests additional configuration, and Roo continues.
- When creating a data processing script, Roo summarizes the functionality. The user suggests performance improvements, and Roo optimizes the code.
---
## Usage Examples
Completing a task with just a result summary:
```
<attempt_completion>
<result>
I've updated the CSS for the navigation bar to match the design mockup. The changes include:
1. Updated color scheme to use the new brand colors
2. Added responsive behavior for mobile devices
3. Fixed the alignment issues in the dropdown menus
</result>
</attempt_completion>
```
Completing a task with a result and demonstration command:
```
<attempt_completion>
<result>
I've created a simple React application with the following features:
1. A responsive landing page with the requested hero section
2. A working contact form with validation
3. Navigation between all three requested pages
4. Styling that matches the provided design mockup
</result>
<command>npm start</command>
</attempt_completion>
```
Completing a Python script task with execution:
```
<attempt_completion>
<result>
I've created a data processing script that:
1. Reads the CSV files from the data directory
2. Cleans and normalizes the data as requested
3. Generates the summary statistics in JSON format
4. Outputs the processed data to the output directory
</result>
<command>python process_data.py</command>
</attempt_completion>
```

275
apps/docs/docs/advanced-usage/available-tools/codebase-search.md Normal file
View file

@ -0,0 +1,275 @@
---
description: Perform intelligent semantic searches across your codebase using AI embeddings to find relevant code by meaning, not just keywords.
keywords:
- codebase_search
- semantic search
- AI embeddings
- code search
- Roo Code tools
- vector search
- Qdrant
---
# codebase_search
:::info Setup Required
The `codebase_search` tool is part of the [Codebase Indexing](/features/codebase-indexing) feature. It requires additional setup including an embedding provider and vector database.
:::
The `codebase_search` tool performs semantic searches across your entire codebase using AI embeddings. Unlike traditional text-based search, it understands the meaning of your queries and finds relevant code even when exact keywords don't match.
---
## Parameters
The tool accepts these parameters:
- `query` (required): Natural language search query describing what you're looking for
- `path` (optional): Directory path to limit search scope to a specific part of your codebase
---
## What It Does
This tool searches through your indexed codebase using semantic similarity rather than exact text matching. It finds code blocks that are conceptually related to your query, even if they don't contain the exact words you searched for. Results include relevant code snippets with file paths, line numbers, and similarity scores.
---
## When is it used?
- When Roo needs to find code related to specific functionality across your project
- When looking for implementation patterns or similar code structures
- When searching for error handling, authentication, or other conceptual code patterns
- When exploring unfamiliar codebases to understand how features are implemented
- When finding related code that might be affected by changes or refactoring
---
## Key Features
- **Semantic Understanding**: Finds code by meaning rather than exact keyword matches
- **Cross-Project Search**: Searches across your entire indexed codebase, not just open files
- **Contextual Results**: Returns code snippets with file paths and line numbers for easy navigation
- **Similarity Scoring**: Results ranked by relevance with similarity scores (0-1 scale)
- **Scope Filtering**: Optional path parameter to limit searches to specific directories
- **Intelligent Ranking**: Results sorted by semantic relevance to your query
- **UI Integration**: Results displayed with syntax highlighting and navigation links
- **Performance Optimized**: Fast vector-based search with configurable result limits
---
## Requirements
This tool is only available when the Codebase Indexing feature is properly configured:
- **Feature Configured**: Codebase Indexing must be configured in settings
- **Embedding Provider**: OpenAI API key or Ollama configuration required
- **Vector Database**: Qdrant instance running and accessible
- **Index Status**: Codebase must be indexed (status: "Indexed" or "Indexing")
---
## Limitations
- **Requires Configuration**: Depends on external services (embedding provider + Qdrant)
- **Index Dependency**: Only searches through indexed code blocks
- **Result Limits**: Maximum of 50 results per search to maintain performance
- **Similarity Threshold**: Only returns results above similarity threshold (default: 0.4, configurable)
- **File Size Limits**: Limited to files under 1MB that were successfully indexed
- **Language Support**: Effectiveness depends on Tree-sitter language support
---
## How It Works
When the `codebase_search` tool is invoked, it follows this process:
1. **Availability Validation**:
- Verifies that the CodeIndexManager is available and initialized
- Confirms codebase indexing is enabled in settings
- Checks that indexing is properly configured (API keys, Qdrant URL)
- Validates the current index state allows searching
2. **Query Processing**:
- Takes your natural language query and generates an embedding vector
- Uses the same embedding provider configured for indexing (OpenAI or Ollama)
- Converts the semantic meaning of your query into a mathematical representation
3. **Vector Search Execution**:
- Searches the Qdrant vector database for similar code embeddings
- Uses cosine similarity to find the most relevant code blocks
- Applies the minimum similarity threshold (default: 0.4, configurable) to filter results
- Limits results to 50 matches for optimal performance
4. **Path Filtering** (if specified):
- Filters results to only include files within the specified directory path
- Uses normalized path comparison for accurate filtering
- Maintains relevance ranking within the filtered scope
5. **Result Processing and Formatting**:
- Converts absolute file paths to workspace-relative paths
- Structures results with file paths, line ranges, similarity scores, and code content
- Formats for both AI consumption and UI display with syntax highlighting
6. **Dual Output Format**:
- **AI Output**: Structured text format with query, file paths, scores, and code chunks
- **UI Output**: JSON format with syntax highlighting and navigation capabilities
---
## Search Query Best Practices
### Effective Query Patterns
**Good: Conceptual and specific**
```xml
<codebase_search>
<query>user authentication and password validation</query>
</codebase_search>
```
**Good: Feature-focused**
```xml
<codebase_search>
<query>database connection pool setup</query>
</codebase_search>
```
**Good: Problem-oriented**
```xml
<codebase_search>
<query>error handling for API requests</query>
</codebase_search>
```
**Less effective: Too generic**
```xml
<codebase_search>
<query>function</query>
</codebase_search>
```
### Query Types That Work Well
- **Functional Descriptions**: "file upload processing", "email validation logic"
- **Technical Patterns**: "singleton pattern implementation", "factory method usage"
- **Domain Concepts**: "user profile management", "payment processing workflow"
- **Architecture Components**: "middleware configuration", "database migration scripts"
---
## Directory Scoping
Use the optional `path` parameter to focus searches on specific parts of your codebase:
**Search within API modules:**
```xml
<codebase_search>
<query>endpoint validation middleware</query>
<path>src/api</path>
</codebase_search>
```
**Search in test files:**
```xml
<codebase_search>
<query>mock data setup patterns</query>
<path>tests</path>
</codebase_search>
```
**Search specific feature directories:**
```xml
<codebase_search>
<query>component state management</query>
<path>src/components/auth</path>
</codebase_search>
```
---
## Result Interpretation
### Similarity Scores
- **0.8-1.0**: Highly relevant matches, likely exactly what you're looking for
- **0.6-0.8**: Good matches with strong conceptual similarity
- **0.4-0.6**: Potentially relevant but may require review
- **Below 0.4**: Filtered out as too dissimilar
### Result Structure
Each search result includes:
- **File Path**: Workspace-relative path to the file containing the match
- **Score**: Similarity score indicating relevance (0.4-1.0)
- **Line Range**: Start and end line numbers for the code block
- **Code Chunk**: The actual code content that matched your query
---
## Examples When Used
- When implementing a new feature, Roo searches for "authentication middleware" to understand existing patterns before writing new code.
- When debugging an issue, Roo searches for "error handling in API calls" to find related error patterns across the codebase.
- When refactoring code, Roo searches for "database transaction patterns" to ensure consistency across all database operations.
- When onboarding to a new codebase, Roo searches for "configuration loading" to understand how the application bootstraps.
---
## Usage Examples
Searching for authentication-related code across the entire project:
```xml
<codebase_search>
<query>user login and authentication logic</query>
</codebase_search>
```
Finding database-related code in a specific directory:
```xml
<codebase_search>
<query>database connection and query execution</query>
<path>src/data</path>
</codebase_search>
```
Looking for error handling patterns in API code:
```xml
<codebase_search>
<query>HTTP error responses and exception handling</query>
<path>src/api</path>
</codebase_search>
```
Searching for testing utilities and mock setups:
```xml
<codebase_search>
<query>test setup and mock data creation</query>
<path>tests</path>
</codebase_search>
```
Finding configuration and environment setup code:
```xml
<codebase_search>
<query>environment variables and application configuration</query>
</codebase_search>
```

91
apps/docs/docs/advanced-usage/available-tools/edit-file.md Normal file
View file

@ -0,0 +1,91 @@
---
description: Replace a uniquely-identified occurrence of text in files using the edit_file search-and-replace tool in Roo Code.
keywords:
- edit_file
- search and replace
- file editing
- text replacement
- Roo Code tools
- code modifications
---
# edit_file
The `edit_file` tool performs targeted search-and-replace operations on files. By default it replaces **exactly one** uniquely-identified occurrence and errors if multiple matches are found. It also supports a special file-creation mode when `old_string` is empty.
---
## Parameters
The tool accepts these parameters:
- `file_path` (required): The path of the file to modify relative to the current working directory.
- `old_string` (required): The exact text to search for and replace. Pass an empty string (`""`) to create a new file or append to an existing file.
- `new_string` (required): The replacement text.
- `expected_replacements` (optional): Expected number of replacements (defaults to 1). The operation fails if the actual count doesn't match. Use this only when intentionally replacing more than one occurrence.
---
## What It Does
This tool searches for an exact string in a file and replaces **exactly one** occurrence with new text. The search string must uniquely identify the target location. If multiple matches are found, the tool returns an error unless `expected_replacements` is explicitly set to match. When `old_string` is empty, the tool creates a new file or appends `new_string` to an existing file.
---
## When is it used?
- When making a targeted change to a specific, uniquely identifiable location in a file
- When updating a specific string literal or configuration value at a known location
- When fixing a specific instance of a typo or outdated terminology
- When replacing a uniquely-identified occurrence of a deprecated API or import path
- When creating a new file or appending content to an existing file (`old_string=""`)
- When you need to ensure exact match replacement without fuzzy logic
---
## Key Features
- Replaces **exactly one** uniquely-identified occurrence by default
- Errors if multiple matches are found (unless `expected_replacements` is explicitly set)
- `old_string=""` mode: creates a new file or appends content to an existing file
- Exact string matching (no regex or fuzzy matching)
- Optional `expected_replacements` for intentional multi-occurrence replacements
- Shows preview of changes before applying
- Fails safely if actual replacement count doesn't match `expected_replacements`
- Preserves file formatting and structure
---
## Limitations
- Requires exact string matches (case-sensitive, whitespace-sensitive)
- Errors if the search string matches more than one location (unless `expected_replacements` is set)
- Cannot use regular expressions or patterns
- Not suitable for context-dependent replacements
- Less precise than [`apply_diff`](/advanced-usage/available-tools/apply-diff) for complex edits
---
## How It Works
When the `edit_file` tool is invoked, it follows this process:
1. **Parameter Validation**: Validates required `file_path`, `old_string`, and `new_string` parameters.
2. **File Creation Mode**: If `old_string` is empty (`""`), creates the file with `new_string` as content (or appends if the file already exists), then stops.
3. **File Loading**: Reads the target file content.
4. **Uniqueness Check**: Counts occurrences of `old_string`. If the count doesn't match `expected_replacements` (default: 1), returns an error.
5. **Replacement**: Replaces the matched occurrence(s) with `new_string`.
6. **User Review**: Shows a preview of changes for user approval.
7. **Application**: Applies changes to the file if approved.
8. **Feedback**: Reports the number of replacements made.
---
## Relation to Other Tools
- `edit_file`: Replaces **exactly one** uniquely-identified occurrence by default; supports `old_string=""` file creation (this tool)
- [`edit`](/advanced-usage/available-tools/edit): Replaces **first occurrence** only (unless `replace_all: true`)
- [`search_replace`](/advanced-usage/available-tools/search-replace): Also replaces **exactly one** uniquely-identified occurrence
- [`apply_diff`](/advanced-usage/available-tools/apply-diff): Use for precise, context-aware edits with fuzzy matching
These are different implementations of search-and-replace with varying capabilities.

91
apps/docs/docs/advanced-usage/available-tools/edit.md Normal file
View file

@ -0,0 +1,91 @@
---
description: Replace the first or all occurrences of text using the edit search-and-replace tool in Roo Code.
keywords:
- edit
- search and replace
- file editing
- text replacement
- Roo Code tools
- code modifications
---
# edit
The `edit` tool performs search-and-replace operations on files, replacing either the **first occurrence** (default) or **all occurrences** when explicitly specified. It provides flexible control over replacement scope.
---
## Parameters
The tool accepts these parameters:
- `file_path` (required): The path of the file to modify relative to the current working directory.
- `old_string` (required): The exact text to search for and replace.
- `new_string` (required): The text to replace occurrences with.
- `replace_all` (optional): Boolean flag. When `true`, replaces all occurrences. When `false` or omitted, replaces only the first occurrence.
---
## What It Does
This tool searches for an exact string in a file and replaces either the first occurrence or all occurrences based on the `replace_all` parameter. By default, it replaces only the **first match**, making it suitable for targeted single-instance changes.
---
## When is it used?
- When updating a single specific occurrence of text (default behavior)
- When the first instance requires different handling than subsequent ones
- When you need explicit control over whether to replace once or globally
- When making targeted changes to specific instances without affecting others
- When replacing all instances by setting `replace_all: true`
---
## Key Features
- Replaces **first occurrence only** by default (conservative behavior)
- Optional `replace_all` parameter for global replacement
- Exact string matching (no regex or fuzzy matching)
- Shows preview of changes before applying
- Preserves file formatting and structure
- User approval required before applying changes
---
## Limitations
- Requires exact string matches (case-sensitive, whitespace-sensitive)
- Cannot use regular expressions or patterns
- Not suitable for context-dependent replacements requiring code analysis
- Less precise than [`apply_diff`](/advanced-usage/available-tools/apply-diff) for complex edits
- Cannot specify which specific occurrence to replace (first vs. second vs. third)
---
## How It Works
When the `edit` tool is invoked, it follows this process:
1. **Parameter Validation**: Validates required `file_path`, `old_string`, and `new_string` parameters.
2. **File Loading**: Reads the target file content.
3. **Search Operation**: Searches for occurrences of `old_string` in the file.
4. **Replacement Logic**:
- If `replace_all` is `false` or omitted: replaces only the first occurrence
- If `replace_all` is `true`: replaces all occurrences
5. **User Review**: Shows a preview of changes for user approval.
6. **Application**: Applies changes to the file if approved.
7. **Feedback**: Reports the result of the operation.
---
## Relation to Other Tools
- `edit`: Replaces **first occurrence** by default (this tool)
- [`edit_file`](/advanced-usage/available-tools/edit-file): Always replaces **all occurrences**
- [`search_replace`](/advanced-usage/available-tools/search-replace): Always replaces **all occurrences**
- [`apply_diff`](/advanced-usage/available-tools/apply-diff): Use for precise, context-aware edits with fuzzy matching
:::info Deprecated Alias
`SearchAndReplaceTool` is a deprecated internal alias for `EditTool`. They are the same tool.
:::

194
apps/docs/docs/advanced-usage/available-tools/execute-command.md Normal file
View file

@ -0,0 +1,194 @@
---
description: Execute terminal commands in Roo Code for system operations, dependency installation, builds, and development workflows.
keywords:
- execute_command
- CLI commands
- terminal
- system operations
- Roo Code tools
- command execution
- shell integration
---
# execute_command
The `execute_command` tool runs CLI commands on the user's system. It allows Roo to perform system operations, install dependencies, build projects, start servers, and execute other terminal-based tasks needed to accomplish user objectives.
---
## Parameters
The tool accepts these parameters:
- `command` (required): The CLI command to execute. Must be valid for the user's operating system.
- `cwd` (optional): The working directory to execute the command in. If not provided, the current working directory is used.
---
## What It Does
This tool executes terminal commands directly on the user's system, enabling a wide range of operations from file manipulations to running development servers. Commands run in managed terminal instances with real-time output capture, integrated with VS Code's terminal system for optimal performance and security.
---
## When is it used?
- When installing project dependencies (npm install, pip install, etc.)
- When building or compiling code (make, npm run build, etc.)
- When starting development servers or running applications
- When initializing new projects (git init, npm init, etc.)
- When performing file operations beyond what other tools provide
- When running tests or linting operations
- When needing to execute specialized commands for specific technologies
---
## Key Features
- Integrates with VS Code shell API for reliable terminal execution
- Reuses terminal instances when possible through a registry system
- Captures command output line by line with real-time feedback
- Supports long-running commands that continue in the background
- Allows specification of custom working directories
- Maintains terminal history and state across command executions
- Handles complex command chains appropriate for the user's shell
- Provides detailed command completion status and exit code interpretation
- Supports interactive terminal applications with user feedback loop
- Shows terminals during execution for transparency
- Validates commands for security using shell-quote parsing
- Blocks potentially dangerous subshell execution patterns
- Integrates with RooIgnore system for file access control
- Handles terminal escape sequences for clean output
---
## Limitations
- Command access may be restricted by RooIgnore rules and security validations
- Commands with elevated permission requirements may need user configuration
- Behavior may vary across operating systems for certain commands
- Very long-running commands may require specific handling
- File paths should be properly escaped according to the OS shell rules
- Not all terminal features may work with remote development scenarios
---
## How It Works
When the `execute_command` tool is invoked, it follows this process:
1. **Command Validation and Security Checks**:
- Parses the command using shell-quote to identify components
- Validates against security restrictions (subshell usage, restricted files)
- Checks against RooIgnore rules for file access permissions
- Ensures the command meets system security requirements
2. **Terminal Management**:
- Gets or creates a terminal through TerminalRegistry
- Sets up the working directory context
- Prepares event listeners for output capture
- Shows the terminal for user visibility
3. **Command Execution and Monitoring**:
- Executes via VS Code's shellIntegration API
- Captures output with escape sequence processing
- Throttles output handling (100ms intervals)
- Monitors for command completion or errors
- Detects "hot" processes like compilers for special handling
4. **Result Processing**:
- Strips ANSI/VS Code escape sequences for clean output
- Interprets exit codes with detailed signal information
- Updates working directory tracking if changed by command
- Provides command status with appropriate context
---
## Terminal Implementation Details
The tool uses a sophisticated terminal management system:
1. **First Priority: Terminal Reuse**
- The TerminalRegistry tries to reuse existing terminals when possible
- This reduces proliferation of terminal instances and improves performance
- Terminal state (working directory, history) is preserved across commands
2. **Second Priority: Security Validation**
- Commands are parsed using shell-quote for component analysis
- Dangerous patterns like `$(...)` and backticks are blocked
- Commands are checked against RooIgnore rules for file access control
- A prefix-based allowlist system validates command patterns
3. **Performance Optimizations**
- Output is processed in 100ms throttled intervals to prevent UI overload
- Zero-copy buffer management uses index-based tracking for efficiency
- Special handling for compilation and "hot" processes
- Platform-specific optimizations for Windows PowerShell
4. **Error and Signal Handling**
- Exit codes are mapped to detailed signal information (SIGTERM, SIGKILL, etc.)
- Core dump detection for critical failures
- Working directory changes are tracked and handled automatically
- Clean recovery from terminal disconnection scenarios
---
## Examples When Used
- When setting up a new project, Roo runs initialization commands like `npm init -y` followed by installing dependencies.
- When building a web application, Roo executes build commands like `npm run build` to compile assets.
- When deploying code, Roo runs git commands to commit and push changes to a repository.
- When troubleshooting, Roo executes diagnostic commands to gather system information.
- When starting a development server, Roo launches the appropriate server command (e.g., `npm start`).
- When running tests, Roo executes the test runner command for the project's testing framework.
---
## Usage Examples
Running a simple command in the current directory:
```
<execute_command>
<command>npm run dev</command>
</execute_command>
```
Installing dependencies for a project:
```
<execute_command>
<command>npm install express mongodb mongoose dotenv</command>
</execute_command>
```
Running multiple commands in sequence:
```
<execute_command>
<command>mkdir -p src/components && touch src/components/App.js</command>
</execute_command>
```
Executing a command in a specific directory:
```
<execute_command>
<command>git status</command>
<cwd>./my-project</cwd>
</execute_command>
```
Building and then starting a project:
```
<execute_command>
<command>npm run build && npm start</command>
</execute_command>
```

128
apps/docs/docs/advanced-usage/available-tools/generate-image.md Normal file
View file

@ -0,0 +1,128 @@
---
description: Generate or edit images using AI models through the generate_image tool in Roo Code.
keywords:
- generate_image
- AI images
- image generation
- image editing
- OpenRouter
- Roo Code tools
- experimental
---
# generate_image
The `generate_image` tool creates new images from text prompts or modifies existing images using AI models. It supports two providers: **OpenRouter** and the **Roo provider**. This experimental feature enables visual content generation and transformation within your development workflow.
---
## Parameters
The tool accepts these parameters:
- `prompt` (required): The text description of what to generate or how to edit the image.
- `path` (required): The file path where the generated/edited image should be saved (relative to the workspace). The tool automatically adds the appropriate extension if not provided.
- `image` (optional): The file path to an input image to edit or transform (relative to the workspace). Supported formats: PNG, JPG, JPEG, GIF, WEBP.
---
## What It Does
This tool generates images from text descriptions or applies transformations to existing images using AI models. When no input image is provided, it creates new images from scratch. When an input image is provided, it applies the prompt as editing instructions to transform the image.
---
## When is it used?
- When creating visual assets for documentation, mockups, or prototypes
- When generating placeholder images or illustrations
- When transforming existing images (style transfer, enhancement, modifications)
- When creating diagrams or visual explanations from descriptions
- When prototyping UI elements visually
---
## Key Features
- **Text-to-image generation**: Create images from descriptive prompts
- **Image-to-image transformation**: Edit or transform existing images
- Supports multiple input formats (PNG, JPG, JPEG, GIF, WEBP)
- Automatic file extension handling
- Powered by **OpenRouter** or the **Roo provider** for access to various AI models
- Experimental feature with ongoing improvements
---
## Limitations
- Requires OpenRouter or Roo provider API configuration
- Image quality depends on the AI model and prompt quality
- Generation time varies based on complexity and model
- Experimental feature: behavior may change in future releases
- API usage may incur costs based on OpenRouter pricing
- Some image transformations may not produce expected results
---
## How It Works
When the `generate_image` tool is invoked, it follows this process:
1. **Parameter Validation**: Validates required `prompt` and `path` parameters.
2. **Mode Selection**:
- If `image` parameter is provided: operates in **edit mode** (transform existing image)
- Otherwise: operates in **generation mode** (create new image from prompt)
3. **API Request**: Sends request to the configured provider (OpenRouter or Roo) with prompt and optional input image.
4. **Image Processing**: Receives generated/edited image from the API.
5. **File Saving**: Saves the image to the specified `path` with appropriate extension.
6. **Feedback**: Reports success and the location of the generated image.
---
## Usage Examples
Generating a new image:
```
<generate_image>
<prompt>A beautiful sunset over mountains with vibrant orange and purple colors</prompt>
<path>images/sunset.png</path>
</generate_image>
```
Editing an existing image:
```
<generate_image>
<prompt>Transform this image into a watercolor painting style</prompt>
<path>images/watercolor-output.png</path>
<image>images/original-photo.jpg</image>
</generate_image>
```
Upscaling and enhancing:
```
<generate_image>
<prompt>Upscale this image to higher resolution, enhance details, improve clarity and sharpness while maintaining the original content and composition</prompt>
<path>images/enhanced-photo.png</path>
<image>images/low-res-photo.jpg</image>
</generate_image>
```
---
## Relation to Features
The `generate_image` tool is the programmatic interface to the [Image Generation](/features/image-generation) feature. For comprehensive documentation on configuration, model selection, API setup, and advanced usage, see the [Image Generation feature documentation](/features/image-generation).
---
## Configuration
Image generation requires OpenRouter API configuration. See the [Image Generation](/features/image-generation) feature page for detailed setup instructions including:
- OpenRouter API key configuration
- Model selection and capabilities
- Best practices for prompts
- Troubleshooting and limitations

168
apps/docs/docs/advanced-usage/available-tools/list-files.md Normal file
View file

@ -0,0 +1,168 @@
---
description: Learn how the list_files tool helps Roo Code explore project structures, list directories, and navigate codebases with recursive and filtered listing capabilities.
keywords:
- list_files
- Roo Code tools
- directory listing
- file exploration
- project structure
- recursive listing
- codebase navigation
- VS Code AI
---
# list_files
The `list_files` tool displays the files and directories within a specified location. It helps Roo understand your project structure and navigate your codebase effectively.
---
## Parameters
The tool accepts these parameters:
- `path` (required): The path of the directory to list contents for, relative to the current working directory
- `recursive` (optional): Whether to list files recursively. Use `true` for recursive listing, `false` or omit for top-level only.
---
## What It Does
This tool lists all files and directories in a specified location, providing a clear overview of your project structure. It can either show just the top-level contents or recursively explore subdirectories.
---
## When is it used?
- When Roo needs to understand your project structure
- When Roo explores what files are available before reading specific ones
- When Roo maps a codebase to better understand its organization
- Before using more targeted tools like `read_file` or `search_files`
- When Roo needs to check for specific file types (like configuration files) across a project
---
## Key Features
- Lists both files and directories with directories clearly marked
- Offers both recursive and non-recursive listing modes
- Intelligently ignores common large directories like `node_modules` and `.git` in recursive mode
- Respects `.gitignore` rules when in recursive mode
- Marks files ignored by `.rooignore` with a lock symbol (🔒) when `showRooIgnoredFiles` is enabled
- Optimizes file listing performance by leveraging the `ripgrep` tool.
- Sorts results to show directories before their contents, maintaining a logical hierarchy
- Presents results in a clean, organized format
- Automatically creates a mental map of your project structure
---
## Limitations
- File listing is capped at about 200 files by default to prevent performance issues
- The underlying `ripgrep` file listing process has a 10-second timeout; if exceeded, partial results may be returned.
- When the file limit is hit, it adds a note suggesting to use `list_files` on specific subdirectories
- Not designed for confirming the existence of files you've just created
- May have reduced performance in very large directory structures
- Cannot list files in root or home directories for security reasons
---
## How It Works
When the `list_files` tool is invoked, it follows this process:
1. **Parameter Validation**: Validates the required `path` parameter and optional `recursive` parameter
2. **Path Resolution**: Resolves the relative path to an absolute path
3. **Security Checks**: Prevents listing files in sensitive locations like root or home directories
4. **Directory/File Scanning**:
- Uses the `ripgrep` tool to efficiently list files, applying a 10-second timeout.
- Uses Node.js `fs` module to list directories.
- Applies different filtering logic for recursive vs. non-recursive modes.
5. **Result Filtering**:
- In recursive mode, skips common large directories like `node_modules`, `.git`, etc.
- Respects `.gitignore` rules when in recursive mode
- Handles `.rooignore` patterns, either hiding files or marking them with a lock symbol
6. **Formatting**:
- Marks directories with a trailing slash (`/`)
- Sorts results to show directories before their contents for logical hierarchy
- Marks ignored files with a lock symbol (🔒) when `showRooIgnoredFiles` is enabled
- Caps results at 200 files by default with a note about using subdirectories
- Organizes results for readability
---
## File Listing Format
The file listing results include:
- Each file path is displayed on its own line
- Directories are marked with a trailing slash (`/`)
- Files ignored by `.rooignore` are marked with a lock symbol (🔒) when `showRooIgnoredFiles` is enabled
- Results are sorted logically with directories appearing before their contents
- When the file limit is reached, a message appears suggesting to use `list_files` on specific subdirectories
Example output format:
```
src/
src/components/
src/components/Button.tsx
src/components/Header.tsx
src/utils/
src/utils/helpers.ts
src/index.ts
...
File listing truncated (showing 200 of 543 files). Use list_files on specific subdirectories for more details.
```
When `.rooignore` files are used and `showRooIgnoredFiles` is enabled:
```
src/
src/components/
src/components/Button.tsx
src/components/Header.tsx
🔒 src/secrets.json
src/utils/
src/utils/helpers.ts
src/index.ts
```
---
## Examples When Used
- When starting a new task, Roo may list the project files to understand its structure before diving into specific code.
- When asked to find specific types of files (like all JavaScript files), Roo first lists directories to know where to look.
- When providing recommendations for code organization, Roo examines the current project structure first.
- When setting up a new feature, Roo lists related directories to understand the project conventions.
---
## Usage Examples
Listing top-level files in the current directory:
```
<list_files>
<path>.</path>
</list_files>
```
Recursively listing all files in a source directory:
```
<list_files>
<path>src</path>
<recursive>true</recursive>
</list_files>
```
Examining a specific project subdirectory:
```
<list_files>
<path>src/components</path>
<recursive>false</recursive>
</list_files>
```

171
apps/docs/docs/advanced-usage/available-tools/new-task.md Normal file
View file

@ -0,0 +1,171 @@
---
description: Discover how the new_task tool enables complex workflow management by creating subtasks with different modes, maintaining parent-child relationships for organized development.
keywords:
- new_task
- Roo Code tools
- subtasks
- workflow management
- task hierarchy
- mode switching
- complex projects
- task organization
- VS Code AI
---
# new_task
The `new_task` tool creates subtasks with specialized modes while maintaining a parent-child relationship. It breaks down complex projects into manageable pieces, each operating in the mode best suited for specific work.
---
## Parameters
The tool accepts these parameters:
- `mode` (required): The slug of the mode to start the new task in (e.g., "code", "ask", "architect")
- `message` (required): The initial user message or instructions for this new task
- `todos` (optional): Initial todo list in markdown checklist format
---
## What It Does
This tool creates a new task instance with a specified starting mode and initial message. It allows complex workflows to be divided into subtasks with their own conversation history. Parent tasks are paused during subtask execution and resumed when the subtask completes, with results transferred back to the parent.
---
## When is it used?
- When breaking down complex projects into separate, focused subtasks
- When different aspects of a task require different specialized modes
- When different phases of work benefit from context separation
- When organizing multi-phase development workflows
---
## Key Features
- Creates subtasks with their own conversation history and specialized mode
- Pauses parent tasks for later resumption
- Maintains hierarchical task relationships for navigation
- Transfers results back to parent tasks upon completion
- Supports workflow segregation for complex projects
- Allows different parts of a project to use modes optimized for specific work
- Requires explicit user approval for task creation
- Provides clear task transition in the UI
---
## Limitations
- Cannot create tasks with modes that don't exist
- Requires user approval before creating each new task
- Task interface may become complex with deeply nested subtasks
- Subtasks inherit certain workspace and extension configurations from parents
- May require re-establishing context when switching between deeply nested tasks
- Task completion needs explicit signaling to properly return to parent tasks
---
## How It Works
When the `new_task` tool is invoked, it follows this process:
1. **Parameter Validation**:
- Validates the required `mode` and `message` parameters
- Verifies that the requested mode exists in the system
2. **Task Stack Management**:
- Maintains a task stack that tracks all active and paused tasks
- Preserves the current mode for later resumption
- Sets the parent task to paused state
3. **Task Context Management**:
- Creates a new task context with the provided message
- Assigns unique taskId and instanceId identifiers for state management
- Captures telemetry data on tool usage and task lifecycles
4. **Mode Switching and Integration**:
- Switches to the specified mode with appropriate role and capabilities
- Initializes the new task with the provided message
- Integrates with VS Code's command palette and code actions
5. **Task Completion and Result Transfer**:
- When subtask completes, result is passed back to parent task via `finishSubTask()`
- Parent task resumes in its original mode
- Task history and token usage metrics are updated
- The `taskCompleted` event is emitted with performance data
---
## Configuration
Streamline hierarchical task planning with the optional todo list parameter for subtasks:
- **Pass Todo Lists**: Include predefined todo lists when creating subtasks
- **Maintain Context**: Pass along context to the subtask in the form of a todo list
- **Optional Enforcement**: The "New Task Require Todos" setting in VS Code can enforce todo lists for all new subtasks if desired
<img src="/img/v3.25.21/v3.25.21.png" alt="Subtask todo lists configuration in VS Code settings" width="600" />
This feature works out of the box, and you can optionally configure VS Code settings to require todos for all new tasks.
---
## Examples When Used
- When a front-end developer needs to architect a new feature, implement the code, and document it, they can create separate tasks for each phase with results flowing from one phase to the next.
- When debugging an issue before implementing a fix, the debugging task can document findings that are passed to the implementation task.
- When developing a full-stack application, database schema designs from an architect-mode task inform implementation details in a subsequent code-mode task.
- When documenting a system after implementation, the documentation task can reference the completed implementation while using documentation-specific features.
---
## Usage Examples
Creating a new task in code mode:
```
<new_task>
<mode>code</mode>
<message>Implement a user authentication service with login, registration, and password reset functionality.</message>
</new_task>
```
Creating a documentation task after completing implementation:
```
<new_task>
<mode>docs</mode>
<message>Create comprehensive API documentation for the authentication service we just built.</message>
</new_task>
```
Breaking down a complex feature into architectural planning and implementation:
```
<new_task>
<mode>architect</mode>
<message>Design the database schema and system architecture for our new e-commerce platform.</message>
</new_task>
```
Creating a task with an initial todo list:
```
<new_task>
<mode>code</mode>
<message>Build a REST API for user management</message>
<todos>
[ ] Set up Express server
[ ] Create user model
[ ] Implement CRUD endpoints
[ ] Add authentication middleware
[ ] Write API tests
</todos>
</new_task>
```

126
apps/docs/docs/advanced-usage/available-tools/read-command-output.md Normal file
View file

@ -0,0 +1,126 @@
---
description: Retrieve full command output that was truncated in execute_command using the read_command_output tool in Roo Code.
keywords:
- read_command_output
- command output
- truncated output
- CLI output
- terminal output
- Roo Code tools
- artifact retrieval
---
# read_command_output
The `read_command_output` tool retrieves the full output from commands executed via [`execute_command`](/advanced-usage/available-tools/execute-command) when the output was too large and got truncated. It provides access to stored command output artifacts with advanced filtering and pagination capabilities.
---
## Parameters
The tool accepts these parameters:
- `artifact_id` (required): The artifact filename from the truncated output message (e.g., `cmd-1706119234567.txt`).
- `search` (optional): Pattern to filter lines (supports regex or literal strings). Case-insensitive. Similar to `grep`. **Omit entirely if not needed** (do not pass null or empty string).
- `offset` (optional): Byte offset to start reading from for pagination. Default: 0.
- `limit` (optional): Maximum bytes to return. Default: 40KB (40960 bytes).
---
## What It Does
When [`execute_command`](/advanced-usage/available-tools/execute-command) produces very large output, it gets truncated and saved to an artifact file. This tool retrieves the full output from those artifacts, with support for searching specific patterns (like grep) and paginating through large results.
---
## When is it used?
- When [`execute_command`](/advanced-usage/available-tools/execute-command) output includes the message: `[OUTPUT TRUNCATED - Full output saved to artifact: cmd-XXXX.txt]`
- When you need to search for specific errors or patterns in large command output
- When analyzing verbose build logs, test results, or compilation output
- When paginating through command output that's too large to view at once
- When filtering command output to find relevant lines without reading everything
---
## Key Features
- **Read mode**: Access full output with pagination using `offset` and `limit`
- **Search mode**: Filter lines matching a regex or literal pattern (case-insensitive)
- Handles very large command outputs efficiently
- Similar to `grep` for filtering output
- Byte-level pagination for precise control
- Access to complete untruncated command output
---
## Limitations
- Only works with artifacts created by [`execute_command`](/advanced-usage/available-tools/execute-command)
- Artifacts may be cleaned up after a certain time period
- Search patterns are case-insensitive only
- Returns content as bytes with limits (not entire files at once for very large outputs)
- Requires the exact artifact ID from the truncation message
---
## How It Works
When the `read_command_output` tool is invoked, it follows this process:
1. **Artifact Lookup**: Locates the stored command output artifact by ID.
2. **Mode Selection**:
- If `search` parameter is provided: operates in **search mode** (filter lines)
- Otherwise: operates in **read mode** (return raw content with offset/limit)
3. **Search Mode** (if `search` provided):
- Applies regex or literal pattern matching to each line
- Returns only lines that match the pattern
- Case-insensitive matching
4. **Read Mode** (if no `search`):
- Reads from `offset` byte position
- Returns up to `limit` bytes
- Supports pagination through large files
5. **Result Return**: Returns filtered or paginated content.
---
## Usage Examples
Reading truncated output:
```
When execute_command shows:
"[OUTPUT TRUNCATED - Full output saved to artifact: cmd-1706119234567.txt]"
Use:
<read_command_output>
<artifact_id>cmd-1706119234567.txt</artifact_id>
</read_command_output>
```
Searching for errors:
```
<read_command_output>
<artifact_id>cmd-1706119234567.txt</artifact_id>
<search>error|failed|Error</search>
</read_command_output>
```
Paginating through output (reading next chunk):
```
<read_command_output>
<artifact_id>cmd-1706119234567.txt</artifact_id>
<offset>40960</offset>
<limit>40960</limit>
</read_command_output>
```
---
## Relation to Other Tools
- [`execute_command`](/advanced-usage/available-tools/execute-command): Creates the artifacts that this tool reads
- [`search_files`](/advanced-usage/available-tools/search-files): Use for searching project files with regex
- `read_command_output`: Use for searching command output artifacts

708
apps/docs/docs/advanced-usage/available-tools/read-file.md Normal file
View file

@ -0,0 +1,708 @@
---
description: Explore the read_file tool's capabilities for examining file contents, supporting line ranges, PDF/DOCX extraction, image reading, and experimental multi-file concurrent reading.
keywords:
- read_file
- Roo Code tools
- file reading
- concurrent reads
- line numbers
- PDF extraction
- DOCX support
- image support
- OCR workflows
- code analysis
- VS Code AI
---
# read_file
The `read_file` tool examines the contents of files in a project. It allows Roo to understand code, configuration files, documentation, and now images to provide better assistance.
:::info Multi-File Support
The `read_file` tool accepts multiple files via the `args` format. Concurrency and per‑request limits are configured in the UI; the backend tool doesn’t hard‑enforce a file count cap. Some models may use a simplified single‑file variant.
**Note:** When reading files (even single files), the LLM will see a message encouraging multi-file reads: "Reading multiple files at once is more efficient for the LLM. If other files are relevant to your current task, please read them simultaneously."
:::
---
## Parameters
The tool accepts parameters in two formats:
### Standard Format (Single File)
- `path` (required): The path of the file to read relative to the current working directory
- `mode` (optional): Reading mode — `"slice"` (default) or `"indentation"`
- `offset` (optional): 1-based line offset to start reading from (slice mode only, default: `1`)
- `limit` (optional): Maximum number of lines to return (slice mode only, default: `2000`)
- `indentation` (optional): Indentation-mode options — only used when `mode="indentation"`:
- `anchor_line` (required): 1-based line number to anchor the extraction. The tool extracts the complete semantic code block (function, class, method) containing this line.
- `max_levels` (optional): Maximum indentation levels to include above the anchor.
- `include_siblings` (optional): Whether to include sibling blocks at the same indentation level.
- `include_header` (optional): Whether to include file header content (imports, module-level comments) at the top of output.
- `max_lines` (optional): Hard cap on lines returned in indentation mode.
:::note Mode Summary
- **Slice mode** (default): Reads lines sequentially from `offset` up to `limit` lines. Use for initial file exploration or reading a specific line range.
- **Indentation mode**: Extracts complete, syntactically valid code blocks around `anchor_line` based on indentation hierarchy. Preferred when you have a target line number (e.g., from search results or error messages) and need the entire function/class without mid-function truncation.
- **`start_line` and `end_line` do not exist** as parameters. Use `offset` and `limit` for range reads in slice mode.
:::
### Enhanced Format (Multi-File)
The tool also accepts an `args` parameter containing multiple file entries. Concurrency is UI‑configured; the backend accepts multiple files regardless of that setting. Some models may use a simple single‑file tool.
- `args` (required): Container for multiple file specifications
- `file` (required): Individual file specification
- `path` (required): The path of the file to read
- `line_range` (optional): Line range specification (e.g., "1-50" or "100-150"). Multiple `line_range` elements can be specified per file.
---
## What It Does
This tool reads the content of a specified file and returns it with line numbers for easy reference. It can read entire files or specific sections, extract text from PDFs and Word documents, and display images in various formats.
---
## When is it used?
- When Roo needs to understand existing code structure
- When Roo needs to analyze configuration files
- When Roo needs to extract information from text files
- When Roo needs to see code before suggesting changes
- When specific line numbers need to be referenced in discussions
---
## Key Features
- Displays file content with line numbers for easy reference
- Can read specific portions of files by specifying line ranges
- Extracts readable text from PDF, DOCX, XLSX, and IPYNB files
- **Image support**: Displays images in multiple formats (PNG, JPG, JPEG, GIF, WebP, SVG, BMP, ICO, TIFF/TIF, AVIF)
- **Intelligent reading**: Token-budget aware reading that auto-truncates to fit remaining budget instead of failing
- **Large file preview**: Returns a 100KB preview for very large files to enable quick inspection
- **Graceful error recovery**: Recovers from stream errors and guides you to use line_range for targeted reads
- Automatically truncates large text files when no line range is specified, showing the beginning of the file
- Efficiently streams only requested line ranges for better performance
- Makes it easy to discuss specific parts of code with line numbering
- **Multi-file support**: Read multiple files simultaneously with batch approval
---
## Multi-File Capabilities
Multi-file reads are supported. Concurrency and per‑request limits are configured in Settings; the backend tool doesn’t hard‑enforce a file count cap and behavior may be constrained by model/tool selection:
### Configuration
- **Location**: Settings > Context > "Concurrent file reads limit"
- **Description**: "Maximum number of files the 'read_file' tool can process concurrently. Higher values may speed up reading multiple small files but increase memory usage."
- **Range**: 1-100 (slider control)
- **Default**: 5
### Batch Processing
- UI‑configurable limit up to 100 files per request (default 5). Backend doesn’t hard‑enforce a cap; actual behavior may be constrained by model/tool.
- Parallel processing for improved performance
- Batch approval interface for user consent
### Enhanced User Experience
- Single approval dialog for multiple files
- Individual file override options
- Clear visibility into which files will be accessed
- Graceful handling of mixed success/failure scenarios
### Improved Efficiency
- Reduces interruptions from multiple approval dialogs
- Faster processing through parallel file reading
- Smart batching of related files
- Configurable concurrency limits to match system capabilities
---
## Limitations
- **Large files**: For extremely large files, the tool may return a preview and will guide you to use `line_range` for targeted reading.
- **Binary files**: Except for PDF, DOCX, XLSX, IPYNB, and supported image formats, content may not be human‑readable.
- **UI/model constraints**: Concurrency limits and per‑request file counts are configured in the UI; the backend tool doesn’t hard‑enforce a cap.
- **Image files**: Images are provided as base64 data URLs. High‑resolution images can be large.
- Default max single image size: 5MB
- Default max total image size: 20MB
- **Unsupported binary formats**: Returns a `<binary_file format="ext">Binary file - content not displayed</binary_file>` placeholder.
- **Token budget**: Content may be truncated to fit remaining token budget; notices indicate how to proceed.
---
## How It Works
When the `read_file` tool is invoked, it follows this process:
1. **Parameter Validation**: Validates the required `path` parameter and optional parameters
2. **Path Resolution**: Resolves the relative path to an absolute path
3. **Reading Strategy Selection**:
- The tool uses a strict priority hierarchy (explained in detail below)
- It chooses between range reading, auto-truncation, or full file reading
4. **Content Processing**:
- Adds line numbers to the content (e.g., "1 | const x = 13") where `1 |` is the line number.
- For truncated files, adds truncation notice and method definitions
- For special formats (PDF, DOCX, XLSX, IPYNB), extracts readable text
- For image formats, the XML includes a `<notice>` with size; the actual image is attached to the tool result as a base64 data URL (no dimensions returned; MIME type is implied by the data URL)
---
## Reading Strategy Priority
The tool uses a clear decision hierarchy to determine how to read a file:
1. **First Priority: Explicit Line Range**
- Single‑file format: specify `offset` and `limit` for a range read in slice mode, or use `anchor_line` in indentation mode.
- Multi‑file `args` format: specify one or more `line_range` entries per file.
- Range reads stream only the requested lines and bypass `maxReadFileLine`, taking precedence over other options.
2. **Second Priority: Token Budget Management**
- The tool respects the remaining token budget to prevent context overruns
- If a file would exceed the remaining budget, it automatically truncates to fit
- For very large files (exceeding practical limits), returns a 100KB preview for quick inspection
- Provides guidance to use `line_range` for targeted reading of specific sections
- Recovers gracefully from stream errors and suggests alternative approaches
3. **Third Priority: Automatic Truncation for Large Text Files**
- Applies only when all of the following are true:
- No `offset`/`limit` range is specified (slice mode) and no `anchor_line` is provided (indentation mode).
- The file is identified as a text‑based file (not binary like PDF/DOCX/XLSX/IPYNB).
- The file's total line count exceeds the `maxReadFileLine` setting (configurable; UI default may be 500; backend uses `-1`—no line limit—when unset).
- When automatic truncation occurs:
- The tool reads only the first `maxReadFileLine` lines.
- It appends a notice like: `Showing only X of Y total lines. Use line_range if you need to read more lines.`
- **Special Case – Definitions‑Only Mode**: When `maxReadFileLine` is `0`, the tool returns only code definitions without file content (plus a notice).
4. **Default Behavior: Read Entire File**
- If neither an explicit range is given nor automatic truncation applies (e.g., the file is within the line limit, or it's a supported binary type), the tool reads the entire content.
- For supported formats like PDF and DOCX, it attempts to extract the full text content.
- For image formats, it returns a base64-encoded data URL that can be displayed in the chat interface.
---
## Examples When Used
- When asked to explain or improve code, Roo first reads the relevant files to understand the current implementation.
- When troubleshooting configuration issues, Roo reads config files to identify potential problems.
- When working with documentation, Roo reads existing docs to understand the current content before suggesting improvements.
---
## Usage Examples
Here are several scenarios demonstrating how the `read_file` tool is used and the typical output you might receive.
### Reading an Entire File
To read the complete content of a file:
**Input:**
```xml
<read_file>
<path>src/app.js</path>
</read_file>
```
**Simulated Output (for a small file like `example_small.txt`):**
```
1 | This is the first line.
2 | This is the second line.
3 | This is the third line.
```
_(Output will vary based on the actual file content)_
### Reading Specific Lines
To read only a specific range of lines (e.g., lines 46-68), use `offset` and `limit` in slice mode:
**Input:**
```xml
<read_file>
<path>src/app.js</path>
<offset>46</offset>
<limit>23</limit>
</read_file>
```
**Simulated Output (for lines 2-3 of `example_five_lines.txt`):**
```
2 | Content of line two.
3 | Content of line three.
```
_(Output shows only the requested lines with their original line numbers)_
### Reading a Large Text File (Automatic Truncation)
When reading a large text file without specifying a line range, the tool automatically truncates the content if it exceeds the internal line limit (e.g., 500 lines).
**Input:**
```xml
<read_file>
<path>logs/large_app.log</path>
</read_file>
```
**Simulated Output (for a 1500-line log file with a 500-line limit):**
```
1 | Log entry 1...
2 | Log entry 2...
...
500 | Log entry 500...
Showing only 500 of 1500 total lines. Use line_range to read specific sections.
// Optional: Source code definitions summary might appear here for code files
```
_(Output shows the beginning lines up to the `maxReadFileLine` limit, plus a truncation notice. Use line ranges for full access.)_
### Reading Definitions Only
When `maxReadFileLine` is set to `0` in user settings, the tool returns only source code definitions without file content:
**Input:**
```xml
<!-- Assuming maxReadFileLine is set to 0 in user settings -->
<read_file>
<path>src/services/auth.service.ts</path>
</read_file>
```
**Simulated Output:**
```xml
<file>
<path>src/services/auth.service.ts</path>
<notice>Showing only 0 of 150 total lines. Use line_range if you need to read more lines</notice>
</file>
```
_(This mode provides a quick overview of file structure without reading content.)_
### Attempting to Read a Non-Existent File
If the specified file does not exist:
**Input:**
```xml
<read_file>
<path>non_existent_file.txt</path>
</read_file>
```
**Simulated Output (Error):**
```
Error: File not found at path 'non_existent_file.txt'.
```
### Attempting to Read a Blocked File
If the file is excluded by rules in a `.rooignore` file:
**Input:**
```xml
<read_file>
<path>.env</path>
</read_file>
```
**Simulated Output (Error):**
```xml
<file>
<path>.env</path>
<error>Access denied by .rooignore rules</error>
</file>
```
---
### Intelligent Reading with Token Budget Management
When reading large files, the tool automatically manages token budgets to prevent context overruns.
**Scenario:** Reading a very large file without specifying a line range.
**Input:**
```xml
<read_file>
<path>logs/massive-debug.log</path>
</read_file>
```
**Simulated Output (for a file exceeding token budget):**
```
Preview: Showing first …MB of …MB file. Use line_range to read specific sections.
```
Alternative truncation notice:
```
File truncated to N of M characters due to context limitations. Use line_range to read specific sections.
```
This behavior ensures that:
- Small files read completely with zero overhead
- Large files auto‑truncate to fit remaining token budget
- Very large files provide a quick preview
- You receive guidance to use `line_range` for targeted reads
- Stream errors are handled gracefully
**Example with offset/limit for targeted reading:**
```xml
<read_file>
<path>logs/massive-debug.log</path>
<offset>1000</offset>
<limit>101</limit>
</read_file>
```
## Image Reading Examples
The `read_file` tool now supports reading and displaying images directly in the chat interface. This enables powerful visual analysis workflows.
### Reading a Single Image
**Input:**
```xml
<read_file>
<path>assets/logo.png</path>
</read_file>
```
**Output:**
```xml
<file>
<path>assets/logo.png</path>
<notice>Image file (123 KB)</notice>
</file>
```
The image is displayed inline in the chat (base64 data URL attached to the tool result). No dimensions are returned; MIME type is implied by the data URL.
### OCR Workflow Example
Reading multiple images from a folder for text extraction:
**Input:**
```xml
<read_file>
<args>
<file>
<path>screenshots/page1.png</path>
</file>
<file>
<path>screenshots/page2.png</path>
</file>
<file>
<path>screenshots/page3.png</path>
</file>
</args>
</read_file>
```
**Usage:**
```
Please extract all text from these screenshot images and compile them into a single markdown document.
```
### Design Review Workflow
Analyzing multiple design mockups:
**Input:**
```xml
<read_file>
<args>
<file>
<path>designs/homepage-v1.jpg</path>
</file>
<file>
<path>designs/homepage-v2.jpg</path>
</file>
<file>
<path>designs/mobile-view.png</path>
</file>
</args>
</read_file>
```
**Usage:**
```
Compare these design mockups and provide feedback on:
1. Visual consistency
2. Mobile responsiveness
3. Accessibility concerns
4. UI/UX improvements
```
### Supported Image Formats
The tool supports the following image formats:
- PNG
- JPG/JPEG
- GIF
- WebP
- SVG
- BMP
- ICO
- TIFF/TIF
- AVIF
### Image Analysis Use Cases
1. **Documentation Screenshots**: Extract text and create documentation from UI screenshots
2. **Error Debugging**: Analyze error screenshots to understand issues
3. **Design Reviews**: Compare mockups and provide visual feedback
4. **Diagram Analysis**: Understand architecture diagrams and flowcharts
5. **Code Screenshots**: Extract code from images when text isn't available
6. **UI Testing**: Verify visual elements and layouts
---
## Multi-File Examples
You can read multiple files simultaneously using the enhanced XML format.
### Reading Multiple Complete Files
To read several complete files at once:
**Input:**
```xml
<read_file>
<args>
<file>
<path>src/app.ts</path>
</file>
<file>
<path>src/utils.ts</path>
</file>
<file>
<path>src/config.json</path>
</file>
</args>
</read_file>
```
**Simulated Output:**
```xml
<files>
<file>
<path>src/app.ts</path>
<content>
1 | import React from 'react'
2 | import { Utils } from './utils'
3 | // ... rest of file content
</content>
</file>
<file>
<path>src/utils.ts</path>
<content>
1 | export class Utils {
2 | static formatDate(date: Date): string {
3 | // ... utility functions
</content>
</file>
<file>
<path>src/config.json</path>
<content>
1 | {
2 | "apiUrl": "https://api.example.com",
3 | "timeout": 5000
4 | }
</content>
</file>
</files>
```
### Reading Specific Line Ranges from Multiple Files
To read specific sections from multiple files:
**Input:**
```xml
<read_file>
<args>
<file>
<path>src/app.ts</path>
<line_range>1-20</line_range>
<line_range>45-60</line_range>
</file>
<file>
<path>src/utils.ts</path>
<line_range>10-25</line_range>
</file>
</args>
</read_file>
```
**Simulated Output:**
```xml
<files>
<file>
<path>src/app.ts</path>
<content>
1 | import React from 'react'
2 | import { Utils } from './utils'
...
20 | const App = () => {
45 | const handleSubmit = () => {
46 | // Handle form submission
...
60 | }
</content>
</file>
<file>
<path>src/utils.ts</path>
<content>
10 | static formatDate(date: Date): string {
11 | return date.toISOString().split('T')[0]
...
25 | }
</content>
</file>
</files>
```
### Handling Mixed Results (Some Files Denied/Blocked)
When some files are approved and others are denied or blocked:
**Input:**
```xml
<read_file>
<args>
<file>
<path>src/app.ts</path>
</file>
<file>
<path>.env</path>
</file>
<file>
<path>src/secret-config.ts</path>
</file>
</args>
</read_file>
```
**Simulated Output:**
```xml
<files>
<file>
<path>src/app.ts</path>
<content>
1 | import React from 'react'
2 | // ... file content successfully read
</content>
</file>
<file>
<path>.env</path>
<error>Access denied by .rooignore rules</error>
</file>
<file>
<path>src/secret-config.ts</path>
<error>User denied access to file</error>
</file>
</files>
```
### Batch Approval Interface
When requesting multiple files, you'll see a batch approval interface that allows you to:
- **Approve All**: Grant access to all requested files
- **Deny All**: Deny access to all requested files
- **Individual Control**: Override decisions for specific files
- **File Preview**: Click file headers to open them in your editor
The interface displays each file path clearly, making it easy to understand what Roo wants to access before granting permission.
### Mixed Content Types
You can read different types of files in a single request:
**Input:**
```xml
<read_file>
<args>
<file>
<path>README.md</path>
</file>
<file>
<path>architecture-diagram.png</path>
</file>
<file>
<path>config.json</path>
</file>
<file>
<path>requirements.pdf</path>
</file>
</args>
</read_file>
```
This allows Roo to analyze documentation, visual diagrams, configuration, and specifications all in one context.
---
## Troubleshooting
- Range read returns error
- Cause: Invalid `offset` or `limit` values (e.g., non-positive integers).
- Fix: Use `offset` (1-based starting line) and `limit` (max lines to return) as positive integers in slice mode; or use `anchor_line` in indentation mode; or use the multi-file `args` format with `line_range` entries.
- Prevention: Prefer the multi-file `args` format with `line_range` for targeted reads across multiple files.
- Large file returned a preview
- Cause: File exceeded token budget or the large‑file tokenization threshold; a preview was returned.
- Fix: Use `line_range` to request only the section you need; reduce requested ranges.
- Prevention: Adjust `maxReadFileLine` in Settings, or prefer targeted ranges on large files.
- Image not displayed
- Cause: Model may not support images, or image limits exceeded (5MB per image; 20MB total per request).
- Fix: Switch to a vision‑capable model; reduce image size; request fewer/smaller images.
- Prevention: Keep images within limits and use supported formats (PNG, JPG/JPEG, GIF, WebP, SVG, BMP, ICO, TIFF/TIF, AVIF).

359
apps/docs/docs/advanced-usage/available-tools/run-slash-command.md Normal file
View file

@ -0,0 +1,359 @@
---
description: Execute predefined slash commands that provide templated instructions for common tasks, with support for built-in, global, and project-specific commands in Roo Code.
keywords:
- run_slash_command
- slash commands
- command templates
- Roo Code tools
- workflow automation
- instruction templates
- custom commands
- experimental feature
---
# run_slash_command
:::warning Experimental Feature
The `run_slash_command` tool is an experimental feature that must be explicitly enabled in settings. Navigate to Settings > Experimental Settings and enable "Run Slash Command" to use this tool.
:::
The `run_slash_command` tool executes predefined slash commands to retrieve specific instructions or content templates. These commands act as reusable instruction sets for common tasks, providing detailed guidance that Roo can interpret and execute. Commands can be defined at three levels with a clear priority hierarchy: project > global > built-in.
---
## Parameters
The tool accepts these parameters:
- `command` (required): Name of the slash command to execute (without the leading slash)
- `args` (optional): Additional arguments or context to pass to the command
---
## What It Does
This tool retrieves and executes instruction templates defined as markdown files in command directories. It enables standardized workflows, reusable task instructions, and team-wide consistency through shared command templates. The tool validates experimental flag status, resolves commands through the priority hierarchy, and returns formatted instructions for Roo to interpret.
---
## When is it used?
- When executing standardized workflows that require consistent steps
- When retrieving project-specific or team-wide instruction templates
- When initializing codebases with analysis and documentation
- When accessing complex multi-step processes as single commands
- When maintaining consistency across team development practices
---
## Key Features
- **Three-Level Command System**: Built-in, global (~/.roo/commands/), and project-specific (.roo/commands/) commands
- **Priority Hierarchy**: Project commands override global, which override built-in commands
- **Markdown-Based Templates**: Simple `.md` files with optional YAML frontmatter for metadata
- **Dynamic Arguments**: Pass context-specific arguments to customize command execution
- **Automatic Discovery**: Commands are automatically found from their respective directories
- **Safe Execution**: Commands are text-only instructions requiring user approval, not executable code
- **Metadata Support**: Optional frontmatter for descriptions and argument hints
- **Error Recovery**: Graceful handling with helpful error messages and command suggestions
- **No Registration Required**: Simply place `.md` files in command directories
---
## Requirements
This tool requires explicit enablement:
1. Open VS Code Settings
2. Navigate to Experimental Settings
3. Enable "Run Slash Command"
4. Restart VS Code if necessary
---
## Limitations
- **Experimental Status**: Feature is disabled by default and requires opt-in
- **Text-Only Instructions**: Commands provide instructions, not direct code execution
- **Approval Required**: All command executions require user approval
- **Directory-Based**: Commands must be in specific directory locations
- **Case-Sensitive**: Command names are matched with case sensitivity
- **Single Command**: Can only execute one command per tool invocation
---
## How It Works
When the `run_slash_command` tool is invoked, it follows this process:
1. **Experimental Flag Validation**:
- Checks if the `runSlashCommand` experiment is enabled
- Returns descriptive error if feature is disabled
- Provides instructions for enabling the feature
2. **Parameter Processing**:
- Validates the required `command` parameter
- Captures optional `args` for command customization
- Increments mistake counter for missing parameters
3. **Command Resolution**:
- Searches project directory first (`.roo/commands/`)
- Falls back to global directory (`~/.roo/commands/`)
- Finally checks built-in commands
- Returns undefined if command doesn't exist
4. **Command Loading**:
- Reads the markdown file for the command
- Parses optional YAML frontmatter using `gray-matter`
- Extracts description and argument hints if present
- Returns command content without frontmatter
5. **Response Formatting**:
- Includes command name and source location
- Adds description and argument hints if available
- Shows provided arguments for context
- Returns the full command content for interpretation
6. **Error Handling**:
- Lists available commands if requested command not found
- Provides helpful error messages with alternatives
- Tracks consecutive mistakes for error patterns
---
## Command Structure
### File Format
Commands are markdown files placed in designated directories:
```markdown
---
description: Brief description of what this command does
argument-hint: What arguments this command accepts
---
# Command Content
Detailed instructions for the task go here.
This can include:
- Step-by-step procedures
- Code templates
- Configuration examples
- Best practices
```
### Naming Convention
- File name becomes the command name
- Use `.md` extension
- Example: `deploy.md` creates `/deploy` command
- Case-sensitive matching
### Directory Locations
1. **Built-in Commands**: Hardcoded in source code
2. **Global Commands**: `~/.roo/commands/`
3. **Project Commands**: `<project-root>/.roo/commands/`
---
## Built-in Commands
### /init Command
The only current built-in command analyzes your codebase and creates documentation:
- Analyzes project structure and architecture
- Creates AGENTS.md documentation files
- Identifies coding patterns and conventions
- Documents non-obvious implementation details
- Provides AI-friendly project context
---
## Creating Custom Commands
### Step-by-Step Guide
1. **Create Command Directory**:
```bash
# For project-specific commands
mkdir -p .roo/commands
# For global commands
mkdir -p ~/.roo/commands
```
2. **Create Command File**:
```bash
# Create a deployment command
touch .roo/commands/deploy.md
```
3. **Add Command Content**:
```markdown
---
description: Deploy application to production environment
argument-hint: environment name (staging, production)
---
## Deployment Process
1. Run test suite to ensure all tests pass
2. Build production bundle with optimizations
3. Update environment variables for target
4. Deploy to specified environment
5. Run post-deployment health checks
6. Update deployment documentation
```
4. **Use the Command**:
The command is immediately available for use without registration.
---
## Command Priority System
When multiple commands with the same name exist:
1. **Project Level** (highest priority)
- Located in `.roo/commands/`
- Allows project-specific overrides
- Committed to version control for team sharing
2. **Global Level** (medium priority)
- Located in `~/.roo/commands/`
- Shared across all projects
- User-specific customizations
3. **Built-in Level** (lowest priority)
- Hardcoded in the extension
- Provides default functionality
- Always available as fallback
---
## Examples When Used
- When initializing a new project, Roo executes `/init` to analyze the codebase structure and create comprehensive documentation.
- When deploying applications, Roo retrieves standardized deployment instructions specific to the project's infrastructure.
- When implementing features, Roo accesses team-agreed patterns and best practices through custom commands.
- When setting up development environments, Roo follows project-specific setup instructions consistently.
- When performing code reviews, Roo uses standardized review checklists defined as commands.
---
## Usage Examples
Executing the built-in initialization command:
```xml
<run_slash_command>
<command>init</command>
</run_slash_command>
```
Running a custom deployment command with arguments:
```xml
<run_slash_command>
<command>deploy</command>
<args>production environment with zero-downtime strategy</args>
</run_slash_command>
```
Executing a test command with specific focus:
```xml
<run_slash_command>
<command>test</command>
<args>focus on integration tests for authentication module</args>
</run_slash_command>
```
Running a project-specific build command:
```xml
<run_slash_command>
<command>build</command>
<args>optimized for production with source maps</args>
</run_slash_command>
```
Accessing team coding standards:
```xml
<run_slash_command>
<command>standards</command>
<args>TypeScript and React best practices</args>
</run_slash_command>
```
---
## Best Practices
### Command Design
1. **Clear Naming**: Use descriptive, action-oriented names
2. **Comprehensive Instructions**: Include all necessary steps
3. **Argument Flexibility**: Design commands to work with or without arguments
4. **Metadata Usage**: Always include description and argument hints
5. **Version Control**: Commit project commands for team consistency
### Organization Strategies
1. **Categorization**: Group related commands with prefixes (e.g., `test-unit`, `test-integration`)
2. **Documentation**: Maintain a README in command directories
3. **Templates**: Create template commands for common patterns
4. **Overrides**: Use project-level to customize global commands
5. **Maintenance**: Regularly review and update command content
### Team Collaboration
1. **Standardization**: Define team-wide commands in global directory
2. **Project Specifics**: Override with project-level customizations
3. **Documentation**: Document available commands and their usage
4. **Review Process**: Include command changes in code reviews
5. **Training**: Share command knowledge across team members
---
## Troubleshooting
### Common Issues
**Feature Not Enabled**:
- Error: "Run slash command is an experimental feature that must be enabled in settings"
- Solution: Enable 'Run Slash Command' in Experimental Settings
**Command Not Found**:
- Error: "Command 'X' not found. Available commands: Y, Z"
- Solution: Check command name spelling and available commands list
**Missing Parameters**:
- Error tracked in consecutive mistake counter
- Solution: Provide required `command` parameter
### Debugging Commands
1. **Verify File Location**: Ensure `.md` file is in correct directory
2. **Check File Name**: Command name must match filename without extension
3. **Validate Frontmatter**: Ensure YAML frontmatter is properly formatted
4. **Test Resolution**: Try same command name at different levels to test priority
5. **Review Content**: Ensure command content is properly formatted markdown

209
apps/docs/docs/advanced-usage/available-tools/search-files.md Normal file
View file

@ -0,0 +1,209 @@
---
description: Learn how search_files performs powerful regex searches across your codebase, finding patterns with context using Ripgrep for high-performance results.
keywords:
- search_files
- Roo Code tools
- regex search
- code patterns
- Ripgrep
- multi-file search
- codebase search
- pattern matching
- VS Code AI
---
# search_files
The `search_files` tool performs regex searches across multiple files within your project's workspace. For security, it cannot search outside the current workspace directory. It helps Roo locate specific code patterns, text, or other content throughout your codebase with contextual results.
---
## Parameters
The tool accepts these parameters:
- `path` (required): The path of the directory to search in, relative to the current workspace directory. The search is confined to the workspace.
- `regex` (required): The regular expression pattern to search for (uses Rust regex syntax)
- `file_pattern` (optional): Glob pattern to filter files (e.g., '\*.ts' for TypeScript files)
- `respect_gitignore` (optional): Whether to respect `.gitignore` patterns (default: `true`). Set to `false` to search all files including those in `.gitignore`.
---
## What It Does
This tool searches across files in a specified directory using regular expressions, showing each match with surrounding context. It's like having a powerful "Find in Files" feature that works across the entire project structure.
---
## When is it used?
- When Roo needs to find where specific functions or variables are used
- When Roo helps with refactoring and needs to understand usage patterns
- When Roo needs to locate all instances of a particular code pattern
- When Roo searches for text across multiple files with filtering capabilities
---
## Key Features
- Searches across multiple files in a single operation using high-performance Ripgrep
- **Respects .gitignore**: Automatically excludes files and directories listed in `.gitignore` (including nested `.gitignore` files)
- Shows context around each match (1 line before and after)
- Filters files by type using glob patterns (e.g., only TypeScript files)
- Provides line numbers for easy reference
- Uses powerful regex patterns for precise searches
- Automatically limits output to 300 results with notification
- Truncates lines longer than 500 characters with "[truncated...]" marker
- Intelligently combines nearby matches into single blocks for readability
---
## Limitations
- Works best with text-based files (not effective for binary files like images)
- Performance may slow with extremely large codebases
- Uses Rust regex syntax, which may differ slightly from other regex implementations
- Cannot search within compressed files or archives
- Default context size is fixed (1 line before and after)
- May display varying context sizes when matches are close together due to result grouping
- For security, searches are strictly limited to the current workspace and cannot access parent directories or other locations on the file system.
- **Respects .gitignore by default**: Files listed in `.gitignore` are excluded from searches unless explicitly overridden with `respect_gitignore: false`
---
## How It Works
When the `search_files` tool is invoked, it follows this process:
1. **Parameter Validation**: Validates the required `path` and `regex` parameters
2. **Path Resolution**: Resolves the relative path to an absolute path
3. **Search Execution**:
- Uses Ripgrep (rg) for high-performance text searching
- Applies file pattern filtering if specified
- Collects matches with surrounding context
4. **Result Formatting**:
- Formats results with file paths, line numbers, and context
- Displays 1 line of context before and after each match
- Structures output for easy readability
- Limits results to a maximum of 300 matches with notification
- Truncates lines longer than 500 characters
- Merges nearby matches into contiguous blocks
---
## Search Results Format
The search results include:
- Relative file paths for each matching file (prefixed with #)
- Context lines before and after each match (1 line by default)
- Line numbers padded to 3 spaces followed by `|` and the line content
- A separator line (----) after each match group
Example output format:
```
# rel/path/to/app.ts
11 | // Some processing logic here
12 | // TODO: Implement error handling
13 | return processedData;
----
# Showing first 300 of 300+ results. Use a more specific search if necessary.
```
When matches occur close to each other, they're merged into a single block rather than shown as separate results:
```
# rel/path/to/auth.ts
13 | // Some code here
14 | // TODO: Add proper validation
15 | function validateUser(credentials) {
16 | // TODO: Implement rate limiting
17 | return checkDatabase(credentials);
----
```
---
## Examples When Used
- When asked to refactor a function, Roo first searches for all places the function is used to ensure comprehensive changes.
- When investigating bugs, Roo searches for similar patterns to identify related issues across the codebase.
- When addressing technical debt, Roo locates all TODO comments across the project.
- When analyzing dependencies, Roo finds all imports of a particular module.
---
## Usage Examples
Searching for TODO comments in all JavaScript files:
```
<search_files>
<path>src</path>
<regex>TODO|FIXME</regex>
<file_pattern>*.js</file_pattern>
</search_files>
```
Finding all usages of a specific function:
```
<search_files>
<path>.</path>
<regex>function\s+calculateTotal</regex>
<file_pattern>*.{js,ts}</file_pattern>
</search_files>
```
Searching for a specific import pattern across the entire project:
```xml
<search_files>
<path>.</path>
<regex>import\s+.*\s+from\s+['"]@components/</regex>
</search_files>
```
## Respecting .gitignore
By default, `search_files` respects `.gitignore` patterns in your workspace, including nested `.gitignore` files. This prevents searches in excluded directories like `node_modules/`, `dist/`, or other ignored paths.
### Default Behavior (Respecting .gitignore)
**Input:**
```xml
<search_files>
<path>.</path>
<regex>TODO</regex>
</search_files>
```
This search will **exclude** files and directories listed in `.gitignore`, ensuring focused results on tracked code.
### Overriding .gitignore (Search All Files)
To search **all files** including those in `.gitignore`, explicitly set `respect_gitignore` to `false`:
**Input:**
```xml
<search_files>
<path>.</path>
<regex>TODO</regex>
<respect_gitignore>false</respect_gitignore>
</search_files>
```
This searches **everything**, including `node_modules/`, build artifacts, and other ignored paths.
**When to override:**
- Debugging issues in dependencies or build output
- Searching through generated code
- Comprehensive audits that need to check all files
- Investigating ignored configuration files
---

87
apps/docs/docs/advanced-usage/available-tools/search-replace.md Normal file
View file

@ -0,0 +1,87 @@
---
description: Replace a uniquely-identified occurrence of text in a file using the search_replace tool in Roo Code.
keywords:
- search_replace
- search and replace
- file editing
- text replacement
- Roo Code tools
- code modifications
---
# search_replace
The `search_replace` tool performs a targeted search-and-replace operation on a file, replacing **exactly one** uniquely-identified occurrence of specified text. If the search string matches multiple locations, the tool returns an error—the search string must be specific enough to identify a single target location.
---
## Parameters
The tool accepts these parameters:
- `file_path` (required): The path of the file to modify relative to the current working directory.
- `old_string` (required): The exact text to search for and replace.
- `new_string` (required): The replacement text.
---
## What It Does
This tool searches for an exact string in a file and replaces **exactly one** occurrence with new text. The search string must uniquely identify the target location in the file. If multiple matches are found, the tool returns an error and requires a more specific search string to proceed. This is an intentional safety design to prevent unintended changes.
---
## When is it used?
- When making a targeted change to a specific, uniquely identifiable location in a file
- When updating a specific string literal or configuration value at a known location
- When fixing a specific instance of a pattern or outdated terminology
- When you need simple, exact string replacement at a unique location
- When you need to ensure only one specific location is changed
---
## Key Features
- Replaces **exactly one** uniquely-identified occurrence per call
- Errors if multiple matches are found (intentional safety design)
- Exact string matching (no regex or fuzzy matching)
- Simple three-parameter interface
- Shows preview of changes before applying
- Preserves file formatting and structure
- User approval required before applying changes
---
## Limitations
- Requires exact string matches (case-sensitive, whitespace-sensitive)
- Errors if the search string matches more than one location (must be unique)
- Cannot use regular expressions or patterns
- Not suitable for replacing all occurrences globally (use scripting for that)
- Less precise than [`apply_diff`](/advanced-usage/available-tools/apply-diff) for complex edits
---
## How It Works
When the `search_replace` tool is invoked, it follows this process:
1. **Parameter Validation**: Validates required `file_path`, `old_string`, and `new_string` parameters.
2. **File Loading**: Reads the target file content.
3. **Uniqueness Check**: Counts occurrences of `old_string` in the file. If more than one match is found, returns an error asking for a more specific search string.
4. **Replacement**: Replaces the single found occurrence with `new_string`.
5. **User Review**: Shows a preview of changes for user approval.
6. **Application**: Applies changes to the file if approved.
7. **Feedback**: Reports the result of the operation.
---
## Relation to Other Tools
- `search_replace`: Replaces **exactly one** uniquely-identified occurrence (this tool)
- [`edit_file`](/advanced-usage/available-tools/edit-file): Also replaces **exactly one** occurrence by default; also supports `old_string=""` for file creation
- [`edit`](/advanced-usage/available-tools/edit): Replaces **first occurrence** by default (unless `replace_all: true`)
- [`apply_diff`](/advanced-usage/available-tools/apply-diff): Use for precise, context-aware edits with fuzzy matching
These are different implementations of search-and-replace functionality with varying capabilities.

110
apps/docs/docs/advanced-usage/available-tools/skill.md Normal file
View file

@ -0,0 +1,110 @@
---
description: Load and execute skill instructions using the skill tool for specialized tasks in Roo Code.
keywords:
- skill
- skills
- specialized tasks
- instructions
- Roo Code tools
- automation
- workflows
---
# skill
The `skill` tool loads and injects specialized skill instructions into the conversation context. Skills provide detailed, step-by-step guidance for specific tasks like creating MCP servers, custom modes, or following standardized workflows.
---
## Parameters
The tool accepts these parameters:
- `skill` (required): The name of the skill to load (e.g., `create-mcp-server`, `create-mode`). Must match a skill name from the available skills list.
- `args` (optional): Additional context or arguments to pass to the skill for customization.
---
## What It Does
This tool retrieves skill instructions from the skills directory and loads them into the active conversation. Skills are pre-written instruction sets that guide Roo through complex, multi-step procedures. The tool is mode-aware, loading skills specific to the current mode when available.
---
## When is it used?
- When executing specialized procedures that have standardized workflows
- When creating MCP servers, custom modes, or other structured artifacts
- When following documented best practices for specific task types
- When you need to invoke expert knowledge for a particular domain
- When the task matches a known skill pattern available in the system
---
## Key Features
- Mode-aware skill resolution (loads mode-specific skills when available)
- Supports project-level skill overrides (take precedence over global skills)
- Progressive disclosure: linked files are not auto-loaded (explicit reads required)
- Optional arguments for skill customization
- Skills persist in context for the duration of the conversation
- Provides structured, step-by-step guidance for complex tasks
---
## How It Works
When the `skill` tool is invoked, it follows this process:
1. **Skill Resolution**: Searches for the named skill in the following locations (highest priority first):
- Project `.roo` mode-specific (e.g., `.roo/skills-code/`)
- Project `.roo` generic (`.roo/skills/`)
- Project `.agents` mode-specific (e.g., `.agents/skills-code/`)
- Project `.agents` generic (`.agents/skills/`)
- Global `.roo` mode-specific (e.g., `~/.roo/skills-code/`)
- Global `.roo` generic (`~/.roo/skills/`)
- Global `.agents` mode-specific (e.g., `~/.agents/skills-code/`)
- Global `.agents` generic (`~/.agents/skills/`)
2. **Skill Loading**: Loads the skill's main instruction file (typically `SKILL.md`).
3. **Context Injection**: Injects skill instructions into conversation context.
4. **Linked Files**: Files referenced in the skill are **not** automatically loaded; Roo must explicitly read them if needed.
5. **Execution**: Roo follows the skill's instructions to complete the task.
---
## Available Skills
Skills are dynamically loaded based on the current mode and project configuration. Common skills include:
- `create-mcp-server`: Guide for creating Model Context Protocol servers
- `create-mode`: Guide for creating custom Roo Code modes
- `find-skills`: Helps discover and install agent skills
To see available skills, check the skills list in the system prompt or ask Roo "what skills are available?"
---
## Relation to Features
The `skill` tool is the programmatic interface to the [Skills](/features/skills) feature. For comprehensive documentation on how skills work, how to create custom skills, and the skills system architecture, see the [Skills feature documentation](/features/skills).
---
## Example Usage
Loading a skill to create an MCP server:
```
<skill>
<skill>create-mcp-server</skill>
<args>weather API integration</args>
</skill>
```
Loading a skill without additional context:
```
<skill>
<skill>create-mode</skill>
</skill>
```

199
apps/docs/docs/advanced-usage/available-tools/switch-mode.md Normal file
View file

@ -0,0 +1,199 @@
---
description: Understand how switch_mode enables seamless transitions between Code, Architect, Ask, and Debug modes for specialized task handling in Roo Code.
keywords:
- switch_mode
- Roo Code tools
- mode switching
- operational modes
- Code mode
- Architect mode
- Debug mode
- Ask mode
- task transitions
- VS Code AI
---
# switch_mode
The `switch_mode` tool enables Roo to change between different operational modes, each with specialized capabilities for specific types of tasks. This allows seamless transitions between modes like Code, Architect, Ask, or Debug when the current task requires different expertise.
---
## Parameters
The tool accepts these parameters:
- `mode_slug` (required): The slug of the mode to switch to (e.g., "code", "ask", "architect")
- `reason` (optional): The reason for switching modes, providing context for the user
---
## What It Does
This tool requests a mode change when the current task would be better handled by another mode's capabilities. It maintains context while shifting Roo's focus and available toolsets to match the requirements of the new task phase.
---
## When is it used?
- When transitioning from information gathering to code implementation
- When shifting from coding to architecture or design
- When the current task requires capabilities only available in a different mode
- When specialized expertise is needed for a particular phase of a complex project
---
## Key Features
- Maintains context continuity across mode transitions
- Provides clear reasoning for mode switch recommendations
- Requires user approval for all mode changes
- Enforces tool group restrictions specific to each mode
- Seamlessly adapts tool availability based on the selected mode
- Works with both standard and custom modes
- Displays the mode switch and reasoning in the UI
- Uses XML-style formatting for parameter specification
- Handles file type restrictions specific to certain modes
---
## Limitations
- Cannot switch to modes that don't exist in the system
- Requires explicit user approval for each mode transition
- Cannot use tools specific to a mode until the switch is complete
- Applies a 500ms delay after mode switching to allow the change to take effect
- Some modes have file type restrictions (e.g., Architect mode can only edit markdown files)
- Mode preservation for resumption applies only to the `new_task` functionality, not general mode switching
---
## How It Works
When the `switch_mode` tool is invoked, it follows this process:
1. **Request Validation**:
- Validates that the requested mode exists in the system
- Checks that the `mode_slug` parameter is provided and valid
- Verifies the user isn't already in the requested mode
- Ensures the `reason` parameter (if provided) is properly formatted
2. **Mode Transition Preparation**:
- Packages the mode change request with the provided reason
- Presents the change request to the user for approval
3. **Mode Activation (Upon User Approval)**:
- Updates the UI to reflect the new mode
- Adjusts available tools based on the mode's tool group configuration
- Applies the mode-specific prompt and behavior
- Applies a 500ms delay to allow the change to take effect before executing next tool
- Enforces any file restrictions specific to the mode
4. **Continuation**:
- Proceeds with the task using the capabilities of the new mode
- Retains relevant context from the previous interaction
---
## Tool Group Association
The `switch_mode` tool belongs to the "modes" tool group but is also included in the "always available" tools list. This means:
- It can be used in any mode regardless of the mode's configured tool groups
- It's available alongside other core tools like `ask_followup_question` and `attempt_completion`
- It allows mode transitions at any point in a workflow when task requirements change
---
## Mode Structure
Each mode in the system has a specific structure:
- `slug`: Unique identifier for the mode (e.g., "code", "ask")
- `name`: Display name for the mode (e.g., "Code", "Ask")
- `roleDefinition`: The specialized role and capabilities of the mode
- `customInstructions`: Optional mode-specific instructions that guide behavior
- `groups`: Tool groups available to the mode with optional restrictions
---
## Mode Capabilities
The core modes provide these specialized capabilities:
- **Code Mode**: Focused on coding tasks with full access to code editing tools
- **Architect Mode**: Specialized for system design and architecture planning, limited to editing markdown files only
- **Ask Mode**: Optimized for answering questions and providing information
- **Debug Mode**: Equipped for systematic problem diagnosis and resolution
---
## Custom Modes
Beyond the core modes, the system supports custom project-specific modes:
- Custom modes can be defined with specific tool groups enabled
- They can specify custom role definitions and instructions
- The system checks custom modes first before falling back to core modes
- Custom mode definitions take precedence over core modes with the same slug
---
## File Restrictions
Different modes may have specific file type restrictions:
- **Architect Mode**: Can only edit files matching the `.md` extension
- Attempting to edit restricted file types results in a `FileRestrictionError`
- These restrictions help enforce proper separation of concerns between modes
---
## Examples When Used
- When discussing a new feature, Roo switches from Ask mode to Architect mode to help design the system structure.
- After completing architecture planning in Architect mode, Roo switches to Code mode to implement the designed features.
- When encountering bugs during development, Roo switches from Code mode to Debug mode for systematic troubleshooting.
---
## Usage Examples
Switching to Code mode for implementation:
```
<switch_mode>
<mode_slug>code</mode_slug>
<reason>Need to implement the login functionality based on the architecture we've discussed</reason>
</switch_mode>
```
Switching to Architect mode for design:
```
<switch_mode>
<mode_slug>architect</mode_slug>
<reason>Need to design the system architecture before implementation</reason>
</switch_mode>
```
Switching to Debug mode for troubleshooting:
```
<switch_mode>
<mode_slug>debug</mode_slug>
<reason>Need to systematically diagnose the authentication error</reason>
</switch_mode>
```
Switching to Ask mode for information:
```
<switch_mode>
<mode_slug>ask</mode_slug>
<reason>Need to answer questions about the implemented feature</reason>
</switch_mode>
```

319
apps/docs/docs/advanced-usage/available-tools/tool-use-overview.md Normal file
View file

@ -0,0 +1,319 @@
---
description: Comprehensive guide to Roo Code's tool system, including tool groups, calling mechanisms, mode integration, and best practices for AI-powered development.
keywords:
- Roo Code tools
- tool system
- tool groups
- AI development
- tool architecture
- mode integration
- tool security
- workflow tools
- VS Code AI
---
# Tool Use Overview
Roo Code implements a sophisticated tool system that allows AI models to interact with your development environment in a controlled and secure manner. This document explains how tools work, when they're called, and how they're managed.
---
## Core Concepts
### Tool Groups
Tools are organized into logical groups based on their functionality:
| Category | Purpose | Tools | Common Use |
| ------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| **Read Group** | File system reading and exploration | [read_file](/advanced-usage/available-tools/read-file), [list_files](/advanced-usage/available-tools/list-files), [read_command_output](/advanced-usage/available-tools/read-command-output) | Code exploration and analysis |
| **Search Group** | Pattern and semantic searching | [search_files](/advanced-usage/available-tools/search-files), [codebase_search](/advanced-usage/available-tools/codebase-search) | Finding code patterns and functionality |
| **Edit Group** | File system modifications | [apply_diff](/advanced-usage/available-tools/apply-diff), [apply_patch](/advanced-usage/available-tools/apply-patch), [edit](/advanced-usage/available-tools/edit), [edit_file](/advanced-usage/available-tools/edit-file), [search_replace](/advanced-usage/available-tools/search-replace), [write_to_file](/advanced-usage/available-tools/write-to-file) | Code changes and file manipulation |
| **Image Group** | AI image generation | [generate_image](/advanced-usage/available-tools/generate-image) | Creating and editing images |
| **Command Group** | System command execution | [execute_command](/advanced-usage/available-tools/execute-command), [run_slash_command](/advanced-usage/available-tools/run-slash-command)\* | Running scripts, building projects, executing command templates |
| **MCP Group** | External tool integration | [use_mcp_tool](/advanced-usage/available-tools/use-mcp-tool), [access_mcp_resource](/advanced-usage/available-tools/access-mcp-resource) | Specialized functionality through external servers |
| **Workflow Group** | Mode and task management | [switch_mode](/advanced-usage/available-tools/switch-mode), [new_task](/advanced-usage/available-tools/new-task), [ask_followup_question](/advanced-usage/available-tools/ask-followup-question), [attempt_completion](/advanced-usage/available-tools/attempt-completion), [update_todo_list](/advanced-usage/available-tools/update-todo-list), [skill](/advanced-usage/available-tools/skill) | Context switching and task organization |
\*_Experimental feature - requires explicit enablement in settings_
### Always Available Tools
Certain tools are accessible regardless of the current mode:
- [ask_followup_question](/advanced-usage/available-tools/ask-followup-question): Gather additional information from users
- [attempt_completion](/advanced-usage/available-tools/attempt-completion): Signal task completion
- [switch_mode](/advanced-usage/available-tools/switch-mode): Change operational modes
- [new_task](/advanced-usage/available-tools/new-task): Create subtasks
---
## Available Tools
### Read Tools
These tools help Roo understand your code and project:
- [read_file](/advanced-usage/available-tools/read-file) - Examines the contents of files
- [list_files](/advanced-usage/available-tools/list-files) - Maps your project's file structure
- [read_command_output](/advanced-usage/available-tools/read-command-output) - Retrieves full output from truncated commands
### Search Tools
These tools help Roo find patterns and functionality across your codebase:
- [search_files](/advanced-usage/available-tools/search-files) - Finds patterns across multiple files using regex
- [codebase_search](/advanced-usage/available-tools/codebase-search) - Performs semantic searches across your indexed codebase
### Edit Tools
These tools help Roo make changes to your code:
- [apply_diff](/advanced-usage/available-tools/apply-diff) - Makes precise, surgical changes to your code
- [apply_patch](/advanced-usage/available-tools/apply-patch) - Applies multi-file unified diff patches
- [edit](/advanced-usage/available-tools/edit) - Search-and-replace editing (first occurrence by default)
- [edit_file](/advanced-usage/available-tools/edit-file) - Search-and-replace editing (all occurrences with count validation)
- [search_replace](/advanced-usage/available-tools/search-replace) - Simple search-and-replace (all occurrences)
- [write_to_file](/advanced-usage/available-tools/write-to-file) - Creates new files or completely rewrites existing ones
### Image Tools
These tools help Roo generate and edit images:
- [generate_image](/advanced-usage/available-tools/generate-image) - Generates AI-powered images from text prompts
### Command Tools
These tools help Roo execute commands:
- [execute_command](/advanced-usage/available-tools/execute-command) - Runs system commands and programs
- [run_slash_command](/advanced-usage/available-tools/run-slash-command) - Executes predefined slash commands for templated instructions _(Experimental - requires enablement)_
### MCP Tools
These tools help Roo connect with external services:
- [use_mcp_tool](/advanced-usage/available-tools/use-mcp-tool) - Uses specialized external tools
- [access_mcp_resource](/advanced-usage/available-tools/access-mcp-resource) - Accesses external data sources
### Workflow Tools
These tools help manage the conversation and task flow:
- [ask_followup_question](/advanced-usage/available-tools/ask-followup-question) - Gets additional information from you
- [attempt_completion](/advanced-usage/available-tools/attempt-completion) - Presents final results
- [switch_mode](/advanced-usage/available-tools/switch-mode) - Changes to a different mode for specialized tasks
- [new_task](/advanced-usage/available-tools/new-task) - Creates a new subtask
- [update_todo_list](/advanced-usage/available-tools/update-todo-list) - Updates task checklist progress
- [skill](/advanced-usage/available-tools/skill) - Loads and executes predefined skill instructions
---
## Tool Calling Mechanism
### Handling Complex Tasks
For certain complex operations that require multiple steps, Roo doesn't just figure them out on the fly. Instead, it follows predefined, internal plans to ensure consistency and accuracy.
A prime example is creating a new MCP server, identified internally by `create_mcp_server`. **This identifier does not represent a tool you will see being called.** Rather, when you ask Roo to create a server, it triggers this known, multi-step workflow.
This specific workflow is initiated by Roo using its internal `fetch_instructions` tool (with the task `create_mcp_server`) to retrieve a detailed plan. This plan then guides Roo to make calls to several standard, documented tools in sequence, such as:
- [`execute_command`](/advanced-usage/available-tools/execute-command) for running setup scripts (e.g., `npx @modelcontextprotocol/create-server`).
- [`write_to_file`](/advanced-usage/available-tools/write-to-file) or [`apply_diff`](/advanced-usage/available-tools/apply-diff) for creating or modifying server code and configuration files.
- [`ask_followup_question`](/advanced-usage/available-tools/ask-followup-question) to gather necessary information like API keys from you.
- Other standard tools as needed for steps like determining file locations or updating configuration entries.
So, while the overall task (like `create_mcp_server`) is complex, it's ultimately accomplished by intelligently orchestrating the standard tools available in your environment. This approach allows Roo to reliably perform complex operations by leveraging the tools documented here.
### When Tools Are Called
Tools are invoked under specific conditions:
1. **Direct Task Requirements**
- When specific actions are needed to complete a task as decided by the LLM
- In response to user requests
- During automated workflows
2. **Mode-Based Availability**
- Different modes enable different tool sets
- Mode switches can trigger tool availability changes
- Some tools are restricted to specific modes
3. **Context-Dependent Calls**
- Based on the current state of the workspace
- In response to system events
- During error handling and recovery
### Decision Process
The system uses a multi-step process to determine tool availability:
1. **Mode Validation**
```typescript
isToolAllowedForMode(
tool: string,
modeSlug: string,
customModes: ModeConfig[],
toolRequirements?: Record<string, boolean>,
toolParams?: Record<string, any>
)
```
2. **Requirement Checking**
- System capability verification
- Resource availability
- Permission validation
3. **Parameter Validation**
- Required parameter presence
- Parameter type checking
- Value validation
---
## Technical Implementation
### Tool Call Processing
1. **Initialization**
- Tool name and parameters are validated
- Mode compatibility is checked
- Requirements are verified
2. **Execution**
```typescript
const toolCall = {
type: "tool_call",
name: chunk.name,
arguments: chunk.input,
callId: chunk.callId,
}
```
3. **Result Handling**
- Success/failure determination
- Result formatting
- Error handling
### Security and Permissions
1. **Access Control**
- File system restrictions
- Command execution limitations
- Network access controls
2. **Validation Layers**
- Tool-specific validation
- Mode-based restrictions
- System-level checks
---
## Mode Integration
### Mode-Based Tool Access
Tools are made available based on the current mode:
- **Code Mode**: Full access to file system tools, code editing capabilities, command execution
- **Ask Mode**: Limited to reading tools, information gathering capabilities, no file system modifications
- **Architect Mode**: Design-focused tools, documentation capabilities, limited execution rights
- **Custom Modes**: Can be configured with specific tool access for specialized workflows
### Mode Switching
1. **Process**
- Current mode state preservation
- Tool availability updates
- Context switching
2. **Impact on Tools**
- Tool set changes
- Permission adjustments
- Context preservation
---
## Best Practices
### Tool Usage Guidelines
1. **Efficiency**
- Use the most specific tool for the task
- Avoid redundant tool calls
- Batch operations when possible
2. **Security**
- Validate inputs before tool calls
- Use minimum required permissions
- Follow security best practices
3. **Error Handling**
- Implement proper error checking
- Provide meaningful error messages
- Handle failures gracefully
### Common Patterns
1. **Information Gathering**
```
[ask_followup_question](/advanced-usage/available-tools/ask-followup-question) → [read_file](/advanced-usage/available-tools/read-file) → [codebase_search](/advanced-usage/available-tools/codebase-search)
```
2. **Code Modification**
```
[read_file](/advanced-usage/available-tools/read-file) → [apply_diff](/advanced-usage/available-tools/apply-diff) → [attempt_completion](/advanced-usage/available-tools/attempt-completion)
```
3. **Task Management**
```
[new_task](/advanced-usage/available-tools/new-task) → [switch_mode](/advanced-usage/available-tools/switch-mode) → [execute_command](/advanced-usage/available-tools/execute-command)
```
---
## Error Handling and Recovery
### Error Types
1. **Tool-Specific Errors**
- Parameter validation failures
- Execution errors
- Resource access issues
2. **System Errors**
- Permission denied
- Resource unavailable
- Network failures
3. **Context Errors**
- Invalid mode for tool
- Missing requirements
- State inconsistencies
### Recovery Strategies
1. **Automatic Recovery**
- Retry mechanisms
- Fallback options
- State restoration
2. **User Intervention**
- Error notifications
- Recovery suggestions
- Manual intervention options

210
apps/docs/docs/advanced-usage/available-tools/update-todo-list.md Normal file
View file

@ -0,0 +1,210 @@
---
description: Learn how update_todo_list creates dynamic TODO lists with status tracking, enabling step-by-step task management for complex workflows in Roo Code.
keywords:
- update_todo_list
- Roo Code tools
- task management
- TODO lists
- workflow tracking
- checklist management
- task status
- interactive UI
- VS Code AI
---
# update_todo_list
The `update_todo_list` tool enables dynamic, interactive task management within the chat interface. It replaces the entire TODO list with an updated checklist, ensuring that task status is always current and providing step-by-step tracking for complex, multi-step workflows.
---
## Parameters
The tool accepts these parameters:
- `todos` (required): A markdown-formatted string representing the complete checklist with status indicators
---
## What It Does
This tool creates and manages an interactive todo list that appears as a UI component in the chat interface. It allows for real-time task tracking, status updates, and dynamic addition of new items as they are discovered during complex workflows. The list provides a structured way to manage multi-step tasks with clear visual progress indicators.
---
## When is it used?
- When managing complex, multi-step tasks that benefit from structured tracking
- When Roo needs to show progress through a series of related activities
- When tasks require step-by-step completion verification before proceeding
- When new actionable items are discovered during long or complex workflows
- When providing clear checkpoints and progress visibility to users
---
## Key Features
- **Full Checklist Replacement**: Overwrites the existing todo list with the updated version provided
- **Interactive UI Component**: Displays as an editable interface element in the chat
- **Multiple Status Types**: Supports pending, in-progress, and completed task states
- **Dynamic Task Management**: Add new tasks as they arise during workflow execution
- **User-Friendly Editing**: Provides direct editing capabilities within the chat interface
- **Step-by-Step Tracking**: Enables confirmation of each step before updating and proceeding
- **Progress Visualization**: Clear visual indicators for task completion status
- **Workflow Integration**: Seamlessly integrates with task execution and completion flows
---
## Limitations
- **Complete Replacement**: Replaces the entire list rather than making incremental updates
- **Single-Level Structure**: Uses single-level markdown checklists without nesting support
- **Format Requirements**: Requires specific markdown checkbox syntax for proper parsing
- **Manual Updates**: Requires explicit tool calls to update the list status
- **State Management**: Todo list state is tied to the current task and conversation context
---
## How It Works
When the `update_todo_list` tool is invoked, it follows this process:
1. **Input Validation**:
- Validates the required `todos` parameter is provided
- Parses the markdown checklist format for syntax correctness
- Checks for valid status indicators: `[ ]`, `[-]`, and `[x]`
2. **List Processing**:
- Processes the markdown-formatted checklist
- Extracts individual todo items with their status indicators
- Validates the structure and format of each item
3. **UI Integration**:
- Presents the updated todo list to the user for approval
- Replaces any existing todo list with the new version
- Renders the list as an interactive component in the chat interface
4. **User Interaction**:
- Allows users to edit todos directly in the UI when in editing mode
- Provides "Add Todo" functionality for real-time list expansion
- Synchronizes changes back to the extension to maintain state consistency
5. **State Management**:
- Updates the task's internal todo list representation
- Maintains synchronization between UI state and backend data
- Preserves todo list state across conversation interactions
---
## Checklist Format Requirements
The tool uses a specific markdown format for todo items:
### Status Options
- `[ ]` - Pending task (not started)
- `[-]` - In progress task (currently being worked on)
- `[x]` - Completed task (fully finished)
### Format Rules
- Use single-level markdown checklist (no nesting or subtasks)
- List todos in intended execution order
- Each todo item should be clear and actionable
- Status should accurately reflect current task state
---
## Task Management Guidelines
### Status Updates
- Mark tasks as completed immediately after all work is finished
- Start the next task by marking it as in progress
- Use pending status for tasks not yet started
- Only mark tasks as completed when fully accomplished with no unresolved dependencies
### Dynamic List Management
- Add new todos as soon as they are identified during task execution
- Remove tasks only if they are no longer relevant or explicitly requested
- Retain all unfinished tasks and update their status as needed
- If a task is blocked, keep it as in progress and add new todos for resolution steps
---
## Examples When Used
- When developing a web application, Roo creates a todo list tracking design, implementation, testing, and deployment phases.
- When setting up a development environment, Roo tracks installation of dependencies, configuration steps, and verification tasks.
- When debugging complex issues, Roo maintains a list of investigation steps, potential causes, and testing procedures.
- When refactoring code, Roo tracks which files need updates, what tests need modification, and documentation changes required.
- When implementing new features, Roo manages tasks for planning, coding, testing, and integration steps.
---
## Usage Examples
Creating an initial todo list for a development task:
```xml
<update_todo_list>
<todos>
[ ] Analyze requirements
[ ] Design architecture
[ ] Implement core logic
[ ] Write tests
[ ] Update documentation
</todos>
</update_todo_list>
```
Updating progress after completing the first task:
```xml
<update_todo_list>
<todos>
[x] Analyze requirements
[-] Design architecture
[ ] Implement core logic
[ ] Write tests
[ ] Update documentation
</todos>
</update_todo_list>
```
Adding new tasks discovered during implementation:
```xml
<update_todo_list>
<todos>
[x] Analyze requirements
[x] Design architecture
[x] Implement core logic
[-] Write tests
[ ] Update documentation
[ ] Add performance benchmarks
[ ] Create deployment script
</todos>
</update_todo_list>
```
Managing a complex debugging workflow:
```xml
<update_todo_list>
<todos>
[x] Reproduce the issue
[x] Check recent code changes
[-] Analyze error logs
[ ] Test with different configurations
[ ] Check database queries
[ ] Verify network connectivity
[ ] Create fix and test
</todos>
</update_todo_list>
```

231
apps/docs/docs/advanced-usage/available-tools/use-mcp-tool.md Normal file
View file

@ -0,0 +1,231 @@
---
description: Discover how use_mcp_tool integrates external MCP servers to extend Roo Code with specialized tools, domain-specific functionality, and external services.
keywords:
- use_mcp_tool
- MCP tools
- Model Context Protocol
- external tools
- Roo Code integration
- MCP servers
- domain tools
- tool extension
- VS Code AI
---
# use_mcp_tool
The `use_mcp_tool` tool enables interaction with external tools provided by connected Model Context Protocol (MCP) servers. It extends Roo's capabilities with domain-specific functionality through a standardized protocol.
---
## Parameters
The tool accepts these parameters:
- `server_name` (required): The name of the MCP server providing the tool
- `tool_name` (required): The name of the tool to execute
- `arguments` (required/optional): A JSON object containing the tool's input parameters, following the tool's input schema. May be optional for tools that require no input.
---
## What It Does
This tool allows Roo to access specialized functionality provided by external MCP servers. Each MCP server can offer multiple tools with unique capabilities, extending Roo beyond its built-in functionality. The system validates arguments against schemas, manages server connections, and processes responses of various content types (text, image, resource).
---
## When is it used?
- When specialized functionality not available in core tools is needed
- When domain-specific operations are required
- When integration with external systems or services is needed
- When working with data that requires specific processing or analysis
- When accessing proprietary tools through a standardized interface
---
## Key Features
- Uses the standardized MCP protocol via the `@modelcontextprotocol/sdk` library
- Supports multiple transport mechanisms (StdioClientTransport, StreamableHTTPClientTransport and SSEClientTransport)
- Validates arguments using Zod schema validation on both client and server sides
- Processes multiple response content types: text, image, and resource references
- Manages server lifecycle with automatic restarts when server code changes
- Provides an "always allow" mechanism to bypass approval for trusted tools
- Works with the companion `access_mcp_resource` tool for resource retrieval
- Maintains proper error tracking and handling for failed operations
- Supports configurable timeouts (1-3600 seconds, default: 60 seconds)
- Allows file watchers to automatically detect and reload server changes
---
## Limitations
- Depends on external MCP servers being available and connected
- Limited to the tools provided by connected servers
- Tool capabilities vary between different MCP servers
- Network issues can affect reliability and performance
- Requires user approval before execution (unless in the "always allow" list)
- Cannot execute multiple MCP tool operations simultaneously
---
## Server Configuration
MCP servers can be configured globally or at the project level:
- **Global Configuration**: Managed through the Roo Code extension settings in VS Code. These apply across all projects unless overridden.
- **Project-level Configuration**: Defined in a `.roo/mcp.json` file within your project's root directory.
- This allows project-specific server setups.
- Project-level servers take precedence over global servers if they share the same name.
- Since `.roo/mcp.json` can be committed to version control, it simplifies sharing configurations with your team.
---
## How It Works
When the `use_mcp_tool` tool is invoked, it follows this process:
1. **Initialization and Validation**:
- The system verifies that the MCP hub is available
- Confirms the specified server exists and is connected
- Validates the requested tool exists on the server
- Arguments are validated against the tool's schema definition
- Timeout settings are extracted from server configuration (default: 60 seconds)
2. **Execution and Communication**:
- The system selects the appropriate transport mechanism:
- `StdioClientTransport`: For communicating with local processes via standard I/O
- `SSEClientTransport`: For communicating with HTTP servers via Server-Sent Events
- `StreamableHTTPClientTransport`: For communicating with HTTP servers via Streamable HTTP Events
- A request is sent with validated server name, tool name, and arguments
- Communication uses the `@modelcontextprotocol/sdk` library for standardized interactions
- Request execution is tracked with timeout handling to prevent hanging operations
3. **Response Processing**:
- Responses can include multiple content types:
- Text content: Plain text responses
- Image content: Binary image data with MIME type information
- Resource references: URIs to access server resources (works with `access_mcp_resource`)
- The system checks the `isError` flag to determine if error handling is needed
- Results are formatted for display in the Roo interface
4. **Resource and Error Handling**:
- The system uses WeakRef patterns to prevent memory leaks
- A consecutive mistake counter tracks and manages errors
- File watchers monitor for server code changes and trigger automatic restarts
- The security model requires approval for tool execution unless in the "always allow" list
---
## Security and Permissions
The MCP architecture provides several security features:
- Users must approve tool usage before execution (by default)
- Specific tools can be marked for automatic approval in the "always allow" list
- Server configurations are validated with Zod schemas for integrity
- Configurable timeouts prevent hanging operations (1-3600 seconds)
- Server connections can be enabled or disabled through the UI
---
## Examples When Used
- Analyzing specialized data formats using server-side processing tools
- Generating images or other media through AI models hosted on external servers
- Executing complex domain-specific calculations without local implementation
- Accessing proprietary APIs or services through a controlled interface
- Retrieving data from specialized databases or data sources
---
## Usage Examples
Requesting weather forecast data with text response:
```
<use_mcp_tool>
<server_name>weather-server</server_name>
<tool_name>get_forecast</tool_name>
<arguments>
{
"city": "San Francisco",
"days": 5,
"format": "text"
}
</arguments>
</use_mcp_tool>
```
Analyzing source code with a specialized tool that returns JSON:
```
<use_mcp_tool>
<server_name>code-analysis</server_name>
<tool_name>complexity_metrics</tool_name>
<arguments>
{
"language": "typescript",
"file_path": "src/app.ts",
"include_functions": true,
"metrics": ["cyclomatic", "cognitive"]
}
</arguments>
</use_mcp_tool>
```
Generating an image with specific parameters:
```
<use_mcp_tool>
<server_name>image-generation</server_name>
<tool_name>create_image</tool_name>
<arguments>
{
"prompt": "A futuristic city with flying cars",
"style": "photorealistic",
"dimensions": {
"width": 1024,
"height": 768
},
"format": "webp"
}
</arguments>
</use_mcp_tool>
```
Accessing a resource through a tool that returns a resource reference:
```
<use_mcp_tool>
<server_name>database-connector</server_name>
<tool_name>query_and_store</tool_name>
<arguments>
{
"database": "users",
"type": "select",
"fields": ["name", "email", "last_login"],
"where": {
"status": "active"
},
"store_as": "active_users"
}
</arguments>
</use_mcp_tool>
```
Tool with no required arguments:
```
<use_mcp_tool>
<server_name>system-monitor</server_name>
<tool_name>get_current_status</tool_name>
<arguments>
{}
</arguments>
</use_mcp_tool>
```

207
apps/docs/docs/advanced-usage/available-tools/write-to-file.md Normal file
View file

@ -0,0 +1,207 @@
---
description: Explore write_to_file for creating new files or replacing content with interactive diff view approval, ensuring safe file operations in Roo Code.
keywords:
- write_to_file
- Roo Code tools
- file creation
- file writing
- diff view
- content approval
- file operations
- interactive editing
- VS Code AI
---
# write_to_file
The `write_to_file` tool creates new files or completely replaces existing file content with an interactive approval process. It provides a diff view for reviewing changes before they're applied.
---
## Parameters
The tool accepts these parameters:
- `path` (required): The path of the file to write to, relative to the current working directory
- `content` (required): The complete content to write to the file
- `line_count` (required): The number of lines in the file, including empty lines
---
## What It Does
This tool writes content to a specified file, either creating a new file if it doesn't exist or completely overwriting an existing file. All changes require explicit user approval through a diff view interface, where users can review and even edit the proposed changes before they're applied.
---
## When is it used?
- When Roo needs to create a new file from scratch
- When Roo needs to completely rewrite an existing file
- When creating multiple files for a new project
- When generating configuration files, documentation, or source code
- When you need to review changes before they're applied
---
## Key Features
- Interactive Approval: Shows changes in a diff view requiring explicit approval before applying
- User Edit Support: Allows editing the proposed content before final approval
- Safety Measures: Detects code omission, validates paths, and prevents truncated content
- Editor Integration: Opens a diff view that scrolls to the first difference automatically
- Content Preprocessing: Handles artifacts from different AI models to ensure clean content
- Access Control: Validates against `.rooignore` restrictions before making changes
- Parent Directories: May handle directory creation through system dependencies
- Complete Replacement: Provides a fully transformed file in a single operation
---
## Limitations
- Not suitable for existing files: Much slower and less efficient than `apply_diff` for modifying existing files
- Performance with large files: Operation becomes significantly slower with larger files
- Complete overwrite: Replaces entire file content, cannot preserve original content
- Line count required: Needs accurate line count to detect potential content truncation
- Review overhead: The approval process adds extra steps compared to direct edits
- Interactive only: Cannot be used in automated workflows that require non-interactive execution
---
## How It Works
When the `write_to_file` tool is invoked, it follows this process:
1. **Parameter Validation**: Validates the required parameters and permissions
- Checks that `path`, `content`, and `line_count` are provided
- If `line_count` is missing/invalid, reverts any diff view changes and returns an error suggesting alternative tools (`apply_diff`, etc.) if modifying an existing file.
- Validates the file is allowed (not restricted by `.rooignore`)
- Ensures the path is within the workspace boundaries
- Tracks consecutive mistake counts for missing parameters
- Shows specific error messages for each validation failure
2. **Content Preprocessing**:
- Removes code block markers that might be added by AI models
- Handles escaped HTML entities (specifically for non-Claude models)
- Strips line numbers if accidentally included in content
- Performs model-specific processing for different AI providers
3. **Diff View Generation**:
- Opens a diff view in the editor showing the proposed changes
- Adds a 300ms delay to ensure UI responsiveness
- Scrolls automatically to the first difference
- Highlights changes for easy review
4. **User Approval Process**:
- Waits for explicit user approval to proceed
- Allows users to edit the content in the diff view
- Captures any user edits for the final content
- Provides option to reject changes entirely
- Detects and incorporates user modifications into the final result
5. **Safety Validation**:
- Detects potential content truncation by comparing with provided line count
- Shows warnings if content appears incomplete
- Validates file path and access permissions
- Specifically checks if files are outside the workspace with `isOutsideWorkspace` flag
6. **File Writing**:
- Writes the approved content (with any user edits) to the file
- Provides confirmation of successful write
- Resets the consecutive mistakes counter on success
---
## Examples When Used
- When creating a new project, Roo generates multiple files but lets you review each before committing changes.
- When setting up configuration files, Roo shows the proposed configuration in a diff view for approval.
- When generating documentation, Roo creates markdown files but lets you make final adjustments in the diff view.
- When developing a prototype, Roo shows complete source files in a diff view where you can fine-tune before saving.
---
## Usage Examples
Creating a new JSON configuration file:
```
<write_to_file>
<path>config/settings.json</path>
<content>
{
"apiEndpoint": "https://api.example.com",
"theme": {
"primaryColor": "#007bff",
"secondaryColor": "#6c757d",
"fontFamily": "Arial, sans-serif"
},
"features": {
"darkMode": true,
"notifications": true
},
"version": "1.0.0"
}
</content>
<line_count>13</line_count>
</write_to_file>
```
Creating a simple HTML file:
```
<write_to_file>
<path>src/index.html</path>
<content>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My Application</title>
<link rel="stylesheet" href="styles.css">
</head>
<body>
<div id="app"></div>
<script src="app.js"></script>
</body>
</html>
</content>
<line_count>13</line_count>
</write_to_file>
```
Creating a JavaScript module:
```
<write_to_file>
<path>src/utils/helpers.js</path>
<content>
/**
* Utility functions for the application
*/
export function formatDate(date) {
return new Date(date).toLocaleDateString();
}
export function calculateTotal(items) {
return items.reduce((sum, item) => sum + item.price, 0);
}
export function debounce(func, delay) {
let timeout;
return function(...args) {
clearTimeout(timeout);
timeout = setTimeout(() => func.apply(this, args), delay);
};
}
</content>
<line_count>18</line_count>
</write_to_file>
```

77
apps/docs/docs/advanced-usage/context-poisoning.md Normal file
View file

@ -0,0 +1,77 @@
---
description: Learn about context poisoning in AI coding assistants, its symptoms, causes, and effective recovery strategies to maintain accurate AI responses.
keywords:
- context poisoning
- AI accuracy
- Roo Code troubleshooting
- LLM context management
- session recovery
---
# Context Poisoning
:::info
Context poisoning is a persistent issue within a given session. Once a chat session's context is compromised, treat that session as disposable. Starting fresh with a clean context is crucial for maintaining the accuracy and effectiveness of your Roo Code agent.
:::
Context poisoning occurs when inaccurate or irrelevant data contaminates the language model's active context. This leads the model to draw incorrect conclusions, provide erroneous information to tools, and progressively deviate from the intended task with each interaction.
---
## Symptoms of Context Poisoning
Identify context poisoning by observing these behaviors:
- **Degraded Output Quality:** Suggestions become nonsensical, repetitive, or irrelevant.
- **Tool Misalignment:** Tool calls no longer correspond to the user's requests.
- **Orchestration Failures:** Orchestrator chains may stall, loop indefinitely, or fail to complete.
- **Temporary Fixes:** Re-applying a clean prompt or instructions offers only brief respite before issues resurface.
- **Tool Usage Confusion:** The model struggles to correctly use or recall how to use tools defined in the system prompt.
---
## Common Causes
Context poisoning can be triggered by several factors:
- **Model Hallucination:** The model generates an incorrect piece of information and subsequently treats it as a factual part of the context.
- **Code Comments:** Outdated, incorrect, or ambiguous comments in the codebase can be misinterpreted by the model, leading it down the wrong path.
- **Contaminated User Input:** Copy-pasting logs or text containing hidden or rogue control characters.
- **Context Window Overflow:** As a session grows, older, useful information may be pushed out of the model's limited context window, allowing "poisoned" data to have a greater relative impact.
Once bad data enters the context, it tends to persist. The model re-evaluates this tainted information in subsequent reasoning cycles, similar to a permanent flaw affecting its perception until the context is completely reset.
---
## Can a "Wake-Up Prompt" Resolve Context Poisoning?
**Short Answer:** No.
A corrective prompt might temporarily suppress symptoms, but the problematic data remains in the conversational buffer. The model will likely revert to the poisoned state as soon as the interaction deviates from the narrow scope of the corrective prompt.
**Detailed Explanation:**
- Re-injecting the full set of tool definitions or core directives can sometimes mask the damage for one or some interactions following the initial context poisoning .
- However, the underlying poisoned context remains. Any query or task outside the immediate "patch" will likely re-trigger the original issue.
- This approach is unreliable, akin to placing a warning label on a leaking pipe instead of repairing it.
---
## Effective Recovery Strategies
To reliably recover from context poisoning:
- **Hard Reset the Session:** The most dependable solution is to start a new chat session. This clears the contaminated context entirely.
- **Minimize Manual Data Dumps:** When pasting logs or other data, be selective. Only include the essential information the model requires.
- **Manage Context Window Size:** For large or complex tasks, consider breaking them into smaller, focused chat sessions. This helps ensure that stale or irrelevant information ages out of the context window more quickly.
- **Validate Tool Output:** If a tool returns nonsensical or clearly incorrect data, delete that message from the chat history before the model can process it and incorporate it into its context.
---
## Addressing a Common Question: The "Magic Bullet" Prompt
A frequent question from the community is:
> "Have you found a prompt that wakes it back up? Maybe a prompt that just has the tools instructions we can push back in manually?”
As explained, no single prompt offers a lasting fix. Any immediate improvement is superficial because the corrupted lines of text persist in the session's history, ready to cause further issues. The only robust solution is to discard the compromised session, initiate a new one, and provide it with a clean prompt and the correct tool definitions from the outset.

64
apps/docs/docs/advanced-usage/large-projects.md Normal file
View file

@ -0,0 +1,64 @@
---
description: Learn strategies for effectively using Roo Code with large codebases. Manage context limits, optimize token usage, and handle complex refactoring tasks.
keywords:
- large projects
- context management
- token optimization
- codebase refactoring
- Roo Code scalability
---
# Working with Large Projects
Roo Code can be used with projects of any size, but large projects require some extra care to manage context effectively. Here are some tips for working with large codebases:
---
## Understanding Context Limits
Roo Code uses large language models (LLMs) that have a limited "context window." This is the maximum amount of text (measured in tokens) that the model can process at once. If the context is too large, the model may not be able to understand your request or generate accurate responses.
The context window includes:
- The system prompt (instructions for Roo Code).
- The conversation history.
- The content of any files you mention using `@`.
- The output of any commands or tools Roo Code uses.
---
## Strategies for Managing Context
1. **Be Specific:** When referring to files or code, use specific file paths and function names. Avoid vague references like "the main file."
2. **Use Context Mentions Effectively:** Use `@/path/to/file.ts` to include specific files. Use `@problems` to include current errors and warnings. Use `@` followed by a commit hash to reference specific Git commits.
3. **Break Down Tasks:** Divide large tasks into smaller, more manageable sub-tasks. This helps keep the context focused.
4. **Summarize:** If you need to refer to a large amount of code, consider summarizing the relevant parts in your prompt instead of including the entire code.
5. **Prioritize Recent History:** Roo Code automatically truncates older messages in the conversation history to stay within the context window. Be mindful of this, and re-include important context if needed.
6. **Use Prompt Caching (if available):** Some API providers like Anthropic, OpenAI, OpenRouter and Requesty support "prompt caching". This caches your prompts for use in future tasks and helps reduce the cost and latency of requests.
---
## Example: Refactoring a Large File
Let's say you need to refactor a large TypeScript file (`src/components/MyComponent.tsx`). Here's a possible approach:
1. **Initial Overview:**
```
@/src/components/MyComponent.tsx List the functions and classes in this file.
```
2. **Target Specific Functions:**
```
@/src/components/MyComponent.tsx Refactor the `processData` function to use `async/await` instead of Promises.
```
3. **Iterative Changes:** Make small, incremental changes, reviewing and approving each step.
By breaking down the task and providing specific context, you can work effectively with large files even with a limited context window.

62
apps/docs/docs/advanced-usage/local-development-setup.mdx Normal file
View file

@ -0,0 +1,62 @@
---
description: Learn how to set up Roo Code for local development, build from source, and contribute to the project. Complete developer setup guide.
keywords:
- local development
- build from source
- Roo Code development
- contribute
- developer setup
sidebar_label: Local Development Setup
---
## Local Setup & Development
:::note Developer Information Only
This section is for developers contributing to Roo Code or those who wish to build and run the extension from source.
:::
To set up Roo Code for local development:
1. **Clone the repository:**
```bash
git clone https://github.com/RooCodeInc/Roo-Code.git
cd Roo-Code
```
2. **Install dependencies:**
Roo Code uses `pnpm` for package management.
```bash
pnpm install
```
3. **Run the extension for development:**
You have two primary methods:
* **Directly in VS Code (Recommended for active development):**
* Open the cloned `Roo-Code` folder in VS Code.
* Press `F5` (or select **Run** → **Start Debugging** from the menu). This opens a new VS Code window (Extension Development Host) with Roo Code running.
* Changes to the webview code (under `webview-ui/`) will often update live.
* Changes to the core extension code (under `src/`) typically require restarting the Extension Development Host window.
* **Building and Installing a VSIX package:**
This method is useful for testing the packaged extension or distributing development builds.
1. Build the VSIX file:
```bash
pnpm vsix
```
A `.vsix` file (e.g., `roo-cline-<version>.vsix`) will be created in the `bin/` directory.
2. Install the VSIX in VS Code:
* **Using the command line:**
```bash
code --install-extension bin/roo-cline-<version>.vsix
```
(Replace `<version>` with the actual version number in the filename).
* **Using the VS Code interface:**
* Open the Extensions view (`Ctrl+Shift+X` or `Cmd+Shift+X`).
* Click the "..." (More Actions) menu in the Extensions view sidebar.
* Select "Install from VSIX..."
* Browse to and select the generated `.vsix` file from the `bin/` directory.
<img src="/img/installing/installing-2.png" alt="VS Code's Install from VSIX dialog" width="600" />
*Installing a development VSIX using VS Code's "Install from VSIX..." dialog.*

57
apps/docs/docs/advanced-usage/local-models.md Normal file
View file

@ -0,0 +1,57 @@
---
description: Learn how to run Roo Code with local AI models using Ollama and LM Studio. Complete setup guide for offline AI coding assistance.
keywords:
- local models
- Ollama
- LM Studio
- offline AI
- local LLM
- self-hosted AI
- privacy-focused AI
---
# Using Local Models
Roo Code supports running language models locally on your own machine using [Ollama](https://ollama.com/) and [LM Studio](https://lmstudio.ai/). This offers several advantages:
- **Privacy:** Your code and data never leave your computer.
- **Offline Access:** You can use Roo Code even without an internet connection.
- **Cost Savings:** Avoid API usage fees associated with cloud-based models.
- **Customization:** Experiment with different models and configurations.
**However, using local models also has some drawbacks:**
- **Resource Requirements:** Local models can be resource-intensive, requiring a powerful computer with a good CPU and, ideally, a dedicated GPU.
- **Setup Complexity:** Setting up local models can be more complex than using cloud-based APIs.
- **Model Performance:** The performance of local models can vary significantly. While some are excellent, they may not always match the capabilities of the largest, most advanced cloud models.
- **Limited Features**: Local models (and many online models) often do not support advanced features such as prompt caching, computer use, and others.
---
## Supported Local Model Providers
Roo Code currently supports two main local model providers:
1. **Ollama:** A popular open-source tool for running large language models locally. It supports a wide range of models.
2. **LM Studio:** A user-friendly desktop application that simplifies the process of downloading, configuring, and running local models. It also provides a local server that emulates the OpenAI API.
---
## Setting Up Local Models
For detailed setup instructions, see:
- [Setting up Ollama](/providers/ollama)
- [Setting up LM Studio](/providers/lmstudio)
Both providers offer similar capabilities but with different user interfaces and workflows. Ollama provides more control through its command-line interface, while LM Studio offers a more user-friendly graphical interface.
---
## Troubleshooting
- **"No connection could be made because the target machine actively refused it":** This usually means that the Ollama or LM Studio server isn't running, or is running on a different port/address than Roo Code is configured to use. Double-check the Base URL setting.
- **Slow Response Times:** Local models can be slower than cloud-based models, especially on less powerful hardware. If performance is an issue, try using a smaller model.
- **Model Not Found:** Ensure you have typed in the name of the model correctly. If you're using Ollama, use the same name that you provide in the `ollama run` command.

115
apps/docs/docs/advanced-usage/prompt-engineering.md Normal file
View file

@ -0,0 +1,115 @@
---
description: Master the art of writing effective prompts for Roo Code. Learn principles, techniques, and examples to get better AI coding assistance results.
keywords:
- prompt engineering
- AI prompts
- effective communication
- Roo Code tips
- custom instructions
---
# Prompt Engineering Tips
Prompt engineering is the art of crafting effective instructions for AI models like Roo Code. Well-written prompts lead to better results, fewer errors, and a more efficient workflow.
---
## General Principles
- **Be Clear and Specific:** Clearly state what you want Roo Code to do. Avoid ambiguity.
- **Bad:** Fix the code.
- **Good:** Fix the bug in the `calculateTotal` function that causes it to return incorrect results.
- **Provide Context:** Use [Context Mentions](/basic-usage/context-mentions) to refer to specific files, folders, or problems.
- **Good:** `@/src/utils.ts` Refactor the `calculateTotal` function to use async/await.
- **Break Down Tasks:** Divide complex tasks into smaller, well-defined steps.
- **Give Examples:** If you have a specific coding style or pattern in mind, provide examples.
- **Specify Output Format:** If you need the output in a particular format (e.g., JSON, Markdown), specify it in the prompt.
- **Iterate:** Don't be afraid to refine your prompt if the initial results aren't what you expect.
---
## Thinking vs. Doing
It's often helpful to guide Roo Code through a "think-then-do" process:
1. **Analyze:** Ask Roo Code to analyze the current code, identify problems, or plan the approach.
2. **Plan:** Have Roo Code outline the steps it will take to complete the task.
3. **Execute:** Instruct Roo Code to implement the plan, one step at a time.
4. **Review:** Carefully review the results of each step before proceeding.
---
## Using Custom Instructions
You can provide custom instructions to further tailor Roo Code's behavior. There are two types of custom instructions:
- **Global Custom Instructions:** Apply to all modes.
- **Mode-Specific Custom Instructions:** Apply only to a specific mode (e.g., Code, Architect, Ask, Debug, or a custom mode).
Custom instructions are added to the system prompt, providing persistent guidance to the AI model. You can use these to:
- Enforce coding style guidelines.
- Specify preferred libraries or frameworks.
- Define project-specific conventions.
- Adjust Roo Code's tone or personality.
See the [Custom Instructions](/features/custom-instructions) section for more details.
---
## Handling Ambiguity
If your request is ambiguous or lacks sufficient detail, Roo Code might:
- **Make Assumptions:** It might proceed based on its best guess, which may not be what you intended.
- **Ask Follow-Up Questions:** It might use the `ask_followup_question` tool to clarify your request.
It's generally better to provide clear and specific instructions from the start to avoid unnecessary back-and-forth.
---
## Providing Feedback
If Roo Code doesn't produce the desired results, you can provide feedback by:
- **Rejecting Actions:** Click the "Reject" button when Roo Code proposes an action you don't want.
- **Providing Explanations:** When rejecting, explain _why_ you're rejecting the action. This helps Roo Code learn from its mistakes.
- **Rewording Your Request:** Try rephrasing your initial task or providing more specific instructions.
- **Manually Correcting:** If there are a few small issues, you can also directly modify the code before accepting the changes.
---
## Examples
**Good Prompt:**
> `@/src/components/Button.tsx` Refactor the `Button` component to use the `useState` hook instead of the `useReducer` hook.
**Bad Prompt:**
> Fix the button.
**Good Prompt:**
> Create a new file named `utils.py` and add a function called `calculate_average` that takes a list of numbers and returns their average.
**Bad Prompt:**
> Write some Python code.
**Good Prompt:**
> `@problems` Address all errors and warnings in the current file.
**Bad Prompt:**
> Fix everything.
By following these tips, you can write effective prompts that get the most out of Roo Code's capabilities.

126
apps/docs/docs/advanced-usage/prompt-structure.md Normal file
View file

@ -0,0 +1,126 @@
---
description: Understand the technical structure of prompts in Roo Code. Learn how messages are constructed, system prompts work, and optimize your interactions.
keywords:
- prompt structure
- system prompt
- message flow
- technical documentation
- LLM communication
---
# Prompt Structure
This page explains the technical structure of prompts in Roo Code - how messages are constructed and sent to the Large Language Model (LLM).
---
## Core Message Types
Roo Code uses three primary message types when communicating with LLMs:
- **System Prompt**: The initial instructions that define Roo's capabilities, persona, and operational rules
- **User Messages**: Content sent by you (the user) to Roo
- **Assistant Messages**: Responses generated by the LLM based on your requests
At the API level, there's also a fourth message role:
- **Tool Messages**: Results returned from tool executions, sent back to the LLM as input
Understanding these message types helps you work more effectively with Roo and can be valuable for troubleshooting or advanced customization.
---
## System Prompt
The system prompt is the foundation of Roo's behavior. It contains:
- **Role Definition**: The core persona instructions based on the selected mode (Code, Ask, Debug, etc.)
- **Tool Descriptions**: Detailed information about available tools, including parameters and examples
- **Tool Use Guidelines**: Rules for how tools should be used (sequential execution, waiting for results)
- **Capabilities**: Description of what Roo can do in the current environment
- **Available Modes**: List of all available modes and their descriptions
- **Operational Rules**: Critical guidelines for handling files, project structure, and user interaction
- **System Information**: Details about your environment (OS, shell, working directory)
- **Custom Instructions**: Your global and mode-specific customizations
The system prompt is generated dynamically each time you interact with Roo, adapting to your current mode, available tools, and custom settings.
---
## User Messages
User messages contain your direct inputs to Roo, plus additional contextual information:
- **Your Query**: The text you type in the chat interface
- **Images**: Any images you include in your message (for supported models)
- **Environment Details**: Automatically appended information about your workspace state:
- Open files/tabs
- Cursor position
- Active terminals with output
- Recently modified files
- Current time
- Token/cost information
- Current mode
- File listing (on initial connection)
This automatic context enrichment helps Roo understand your workspace without requiring you to explicitly describe it.
---
## Assistant Messages
Assistant messages are the LLM's responses, which may include:
- **Text Responses**: Direct answers to your queries
- **Thinking**: Internal reasoning process (visible when enabled)
- **Tool Calls**: Requests to use specific tools like reading files or executing commands
Note that while assistant messages contain tool calls, the results of those tools are sent back to the LLM in separate tool messages, not as part of the assistant message itself.
---
## Message Flow
Here's how these components work together:
1. **Initial Setup**: Roo generates the system prompt based on your selected mode and configuration
2. **User Input**: You send a message, which is enriched with environment details
3. **LLM Processing**: The LLM receives all previous messages plus your new input
4. **Assistant Response**: The LLM generates a response, potentially using tools
5. **Tool Execution**: If the LLM requests a tool, Roo executes it and provides the result
6. **Conversation History**: All messages are maintained in a structured history for context
---
## Technical Implementation
Internally, Roo's prompt construction is handled by several components:
- **System Prompt Generation**: The `SYSTEM_PROMPT` function in `src/core/prompts/system.ts` assembles the complete system prompt
- **Section Generators**: Specialized functions create each section of the system prompt
- **Message Transformation**: Provider-specific transformers convert Roo's internal message format to the format required by each LLM API
---
## Support Prompts
Alongside the main chat flow, Roo uses specialized templates for specific code actions:
- **Code Action Prompts**: For commands like "Explain", "Fix", "Improve", or "Add to Context"
- **Template-Based**: Generated from templates in `src/shared/support-prompt.ts`
- **Independent Context**: Often operates without the main chat history
- **Task-Specific Format**: Optimized for the specific code task being performed
These support prompts work outside the normal conversation flow to provide focused assistance for specific coding tasks.
---
## Optimizing Your Interactions
Understanding this structure can help you:
- **Write Better Prompts**: Knowing what context Roo already has helps you avoid redundant information
- **Troubleshoot Issues**: Understanding message flow helps identify where problems might occur
- **Create Custom Modes**: With knowledge of the system prompt structure, you can create more effective custom modes
This technical foundation powers all of Roo's capabilities, enabling it to understand your requests and effectively utilize available tools to complete tasks.

68
apps/docs/docs/advanced-usage/rate-limits-costs.md Normal file
View file

@ -0,0 +1,68 @@
---
description: Understand token usage, cost calculation, and optimization strategies for Roo Code. Learn how to manage API costs and set request limits effectively.
keywords:
- rate limits
- API costs
- token usage
- cost optimization
- auto-approval limits
- API management
---
# Rate Limits and Costs
Understanding and managing API usage is crucial for a smooth and cost-effective experience with Roo Code. This section explains how to track your token usage and costs. Rate limits, which default to 0 (disabled) and typically don't need adjustment, are now configured per profile; see the [API Configuration Profiles](/features/api-configuration-profiles#creating-a-profile) documentation for details on how to set them if needed.
---
## Token Usage
Roo Code interacts with AI models using tokens. Tokens are essentially pieces of words. The number of tokens used in a request and response affects both the processing time and the cost.
- **Input Tokens:** These are the tokens in your prompt, including the system prompt, your instructions, and any context provided (e.g., file contents).
- **Output Tokens:** These are the tokens generated by the AI model in its response.
You can see the number of input and output tokens used for each interaction in the chat history.
---
## Cost Calculation
Most AI providers charge based on the number of tokens used. Pricing varies depending on the provider and the specific model.
Roo Code automatically calculates the estimated cost of each API request based on the configured model's pricing. This cost is displayed in the chat history, next to the token usage.
For reasoning-capable models (for example, Gemini 3 Pro Preview and other models that expose separate "thinking" or reasoning tokens), Roo Code now includes both normal tokens **and** reasoning / "thought" tokens in its estimates when the provider reports them. This can make the displayed token usage and cost slightly higher than in older versions, but it better matches how providers actually bill you.
**Note:**
- The cost calculation is an _estimate_. The actual cost may vary slightly depending on the provider's billing practices.
- Some providers may offer free tiers or credits. Check your provider's documentation for details.
- Some providers offer prompt caching which greatly lowers cost.
### Limiting Auto-Approved Requests
To further help manage API costs and prevent unexpected expenses, Roo Code includes a "Max Requests" setting for auto-approved actions. This allows you to define a specific limit on how many consecutive API calls Roo Code can make without requiring your explicit re-approval during a task.
- **How it works:** If you set a limit (e.g., 5 requests), Roo Code will perform up to 5 auto-approved API calls. Before making the 6th call, it will pause and prompt you to "Reset and Continue," as shown below.
<img src="/img/v3.18.0/v3.18.0-1.png" alt="Warning message indicating the auto-approved request limit has been reached." width="600" />
_Notification when the auto-approved request limit is met._
- **Configuration:** This limit is configured within the "Auto-approve actions" settings. You can set a specific number or choose "Unlimited." For detailed steps on configuring this and other auto-approval settings, see the [Auto-Approving Actions documentation](/features/auto-approving-actions).
<img src="/img/v3.18.0/v3.18.0.png" alt="Setting the Max Requests limit for auto-approved actions in Roo Code settings." width="600" />
_Setting the "Max Requests" for auto-approved actions._
This feature provides an additional safeguard, particularly for complex or long-running tasks where multiple API calls might be involved.
---
## Tips for Optimizing Token Usage
- **Be Concise:** Use clear and concise language in your prompts. Avoid unnecessary words or details.
- **Provide Only Relevant Context:** Use context mentions (`@file.ts`, `@folder/`) selectively. Only include the files that are directly relevant to the task.
- **Break Down Tasks:** Divide large tasks into smaller, more focused sub-tasks.
- **Use Custom Instructions:** Provide custom instructions to guide Roo Code's behavior and reduce the need for lengthy explanations in each prompt.
- **Choose the Right Model:** Some models are more cost-effective than others. Consider using a smaller, faster model for tasks that don't require the full power of a larger model.
- **Use Modes:** Different modes can access different tools, for example `Architect` can't modify code, which makes it a safe choice when analyzing a complex codebase, without worrying about accidentally allowing expensive operations.
- **Disable MCP If Not Used:** If you're not using MCP (Model Context Protocol) features, consider [disabling it in the MCP settings](/features/mcp/using-mcp-in-roo#enabling-or-disabling-mcp-server-creation) to significantly reduce the size of the system prompt and save tokens.
By understanding and managing your API usage, you can use Roo Code effectively and efficiently.

53
apps/docs/docs/advanced-usage/roo-code-nightly.mdx Normal file
View file

@ -0,0 +1,53 @@
---
description: Learn how to install and use Roo Code Nightly builds to test the latest features and improvements before official releases.
keywords:
- Roo Code Nightly
- prerelease builds
- beta testing
- latest features
- nightly builds
sidebar_label: Roo Code Nightly
---
# Roo Code Nightly
For users who want the latest features and updates, Roo Code offers a prerelease build called **Roo Code Nightly**, which is automatically published whenever changes are merged into our main development branch. This means it always reflects the latest code. It's designed for users who want to access the newest features and contribute to early testing.
---
## Understanding Nightly vs. Other Prereleases
It's important to distinguish Roo Code Nightly from other types of prerelease software (like beta versions or release candidates):
* **Roo Code Nightly:**
* **Frequency:** Automated builds, generated on each merge to the main development branch.
* **Content:** Reflects the very latest merged code.
* **Stability:** Highly experimental; may contain bugs or incomplete features.
* **Testing:** Minimal or no manual testing before release.
* **Audience:** Primarily for developers, internal testing, or users comfortable with potentially unstable software who want to see the absolute latest changes and help identify issues early.
* **General Prerelease (e.g., Beta, Release Candidate):**
* **Frequency:** Released periodically (e.g., weekly, monthly) as specific milestones are met.
* **Content:** Represents a more curated and planned intermediate version.
* **Stability:** More stable than Nightly builds; often undergoes some manual testing or validation.
* **Testing:** Typically receives more focused testing.
* **Audience:** Intended for a wider group of early adopters or beta testers to gather feedback before a stable release.
In short: **Nightly = latest code, potentially unstable, frequent updates.** Other prereleases are generally less frequent, more validated, and aimed at broader testing.
---
## Installing Roo Code Nightly
To install Roo Code Nightly:
1. Open VS Code.
2. Access Extensions: Click the Extensions icon in the Activity Bar or press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS).
3. Search for "Roo Code Nightly".
4. Select "Roo Code Nightly" by Roo Code and click **Install**.
5. Reload VS Code if prompted.
<img src="/img/installing/installing-5.png" alt="Roo Code Nightly extension in VS Code Marketplace" width="400" />
*Roo Code Nightly in the VS Code Marketplace.*
You can have both the stable version of Roo Code and Roo Code Nightly installed simultaneously.

185
apps/docs/docs/basic-usage/context-mentions.md Normal file
View file

@ -0,0 +1,185 @@
---
description: Learn how to use context mentions (@) in Roo Code to reference files, folders, problems, terminal output, and Git commits for more accurate AI assistance.
keywords:
- "Roo Code context mentions"
- "@ mentions"
- "file references"
- "folder mentions"
- "problems panel"
- "terminal mentions"
- "Git integration"
---
# Context Mentions
Context mentions are a powerful way to provide Roo Code with specific information about your project, allowing it to perform tasks more accurately and efficiently. You can use mentions to refer to files, folders, problems, and Git commits. Context mentions start with the `@` symbol.
<img src="/img/context-mentions/context-mentions.png" alt="Context Mentions Overview - showing the @ symbol dropdown menu in the chat interface" width="600" />
_Context mentions overview showing the @ symbol dropdown menu in the chat interface._
---
## Types of Mentions
<img src="/img/context-mentions/context-mentions-1.png" alt="File mention example showing a file being referenced with @ and its contents appearing in the conversation" width="600" />
_File mentions add actual code content into the conversation for direct reference and analysis._
| Mention Type | Format | Description | Example Usage |
| ----------------- | ---------------------- | -------------------------------------------------------------------------- | -------------------------------------------------- |
| **File** | `@/path/to/file.ts` | Includes file contents in request context | "Explain the function in @/src/utils.ts" |
| **Image** | `@/path/to/image.png` | Includes image as inline visual content (file mention with vision support) | "What's wrong with this UI? @/screenshots/bug.png" |
| **Folder** | `@/path/to/folder/` | Includes contents of all files directly in the folder (non-recursive) | "Analyze the code in @/src/components/" |
| **Problems** | `@problems` | Includes VS Code Problems panel diagnostics | "@problems Fix all errors in my code" |
| **Terminal** | `@terminal` | Includes recent terminal command and output | "Fix the errors shown in @terminal" |
| **Git Commit** | `@a1b2c3d` | References specific commit by hash | "What changed in commit @a1b2c3d?" |
| **Git Changes** | `@git-changes` | Shows uncommitted changes | "Suggest a message for @git-changes" |
| **URL** | `@https://example.com` | Imports website content | "Summarize @https://docusaurus.io/" |
| **Slash Command** | `/<command-name>` | Executes a slash command (uses `/` not `@`) | "/test Run all tests" |
### File Mentions
<img src="/img/context-mentions/context-mentions-1.png" alt="File mention example showing a file being referenced with @ and its contents appearing in the conversation" width="600" />
_File mentions incorporate source code with line numbers for precise references._
| Capability | Details |
|------------|---------|
| **Format** | `@/path/to/file.ts` (always start with `/` from workspace root) |
| **Provides** | Complete file contents with line numbers |
| **Supports** | Text files, PDFs, and DOCX files (with text extraction) |
| **Works in** | Initial requests, feedback responses, and follow-up messages |
| **Limitations** | Very large files may be truncated; binary files not supported |
### Image Mentions
Image mentions are file mentions with special visual processing. When you mention an image file, and the model supports vision, the image is sent as inline visual content rather than text.
| Capability | Details |
| ------------ | ---------------------------------------------------------------------- |
| **Type** | Sub-type of file mentions (not a separate mention type) |
| **Format** | `@/path/to/image.png` (same path format as file mentions) |
| **Provides** | Image sent as inline visual content to the model |
| **Supports** | PNG, JPG, JPEG, GIF, BMP, SVG, WEBP, ICO, AVIF |
| **Best for** | UI reviews, screenshot debugging, diagram analysis |
| **Requires** | A model with vision support (non-vision models can't interpret images) |
### Folder Mentions
<img src="/img/context-mentions/context-mentions-2.png" alt="Folder mention example showing directory contents being referenced in the chat" width="600" />
_Folder mentions include the content of all files within the specified directory._
| Capability | Details |
|------------|---------|
| **Format** | `@/path/to/folder/` (trailing slash required to distinguish from file mentions) |
| **Provides** | Complete contents of all files within the directory |
| **Includes** | Contents of non-binary text files directly within the folder (not recursive) |
| **Best for** | Providing context from multiple files in a directory |
| **Tip** | Be mindful of context window limits when mentioning large directories |
### Problems Mention
<img src="/img/context-mentions/context-mentions-3.png" alt="Problems mention example showing VS Code problems panel being referenced with @problems" width="600" />
_Problems mentions import diagnostics directly from VS Code's problems panel._
| Capability | Details |
|------------|---------|
| **Format** | `@problems` |
| **Provides** | All errors and warnings from VS Code's problems panel |
| **Includes** | File paths, line numbers, and diagnostic messages |
| **Groups** | Problems organized by file for better clarity |
| **Best for** | Fixing errors without manual copying |
For comprehensive details on how Roo Code integrates with VSCode's diagnostics system, see [Diagnostics Integration](/features/diagnostics-integration).
### Terminal Mention
<img src="/img/context-mentions/context-mentions-4.png" alt="Terminal mention example showing terminal output being included in Roo's context" width="600" />
_Terminal mentions capture recent command output for debugging and analysis._
| Capability | Details |
| -------------- | -------------------------------------------------- |
| **Format** | `@terminal` |
| **Captures** | Last command and its complete output |
| **Preserves** | Terminal state (doesn't clear the terminal) |
| **Limitation** | Limited to visible terminal buffer content |
| **Best for** | Debugging build errors or analyzing command output |
### Git Mentions
<img src="/img/context-mentions/context-mentions-5.png" alt="Git commit mention example showing commit details being analyzed by Roo" width="600" />
_Git mentions provide commit details and diffs for context-aware version analysis._
| Type | Format | Provides | Limitations |
|------|--------|----------|------------|
| **Commit** | `@a1b2c3d` | Commit message, author, date, and complete diff | Only works in Git repositories |
| **Working Changes** | `@git-changes` | `git status` output and diff of uncommitted changes | Only works in Git repositories |
### URL Mentions
<img src="/img/context-mentions/context-mentions-6.png" alt="URL mention example showing website content being converted to Markdown in the chat" width="600" />
_URL mentions import external web content and convert it to readable Markdown format._
| Capability | Details |
| -------------- | ------------------------------------------------ |
| **Format** | `@https://example.com` |
| **Processing** | Uses headless browser to fetch content |
| **Cleaning** | Removes scripts, styles, and navigation elements |
| **Output** | Converts content to Markdown for readability |
| **Limitation** | Complex pages may not convert perfectly |
### Slash Command Mentions
Slash commands are processed by the mentions system but use a `/` prefix instead of `@`. They execute predefined commands to perform specific actions.
| Capability | Details |
| ---------------- | ------------------------------------------------------------ |
| **Format** | `/<command-name>` (uses `/` not `@`) |
| **Provides** | Executes the specified command and includes relevant context |
| **Content Type** | Processed as content block type "command" |
| **Examples** | `/test`, `/init`, `/deploy`, and other custom commands |
| **Best for** | Quick access to predefined workflows and actions |
For comprehensive details on available slash commands and how to create custom ones, see [Slash Commands](/features/slash-commands).
---
## How to Use Mentions
1. Type `@` in the chat input to trigger the suggestions dropdown
2. Continue typing to filter suggestions or use arrow keys to navigate
3. Select with Enter key or mouse click
4. Combine multiple mentions in a request: "Fix @problems in @/src/component.ts"
The dropdown automatically suggests:
- Recently opened files
- Visible folders
- Recent git commits
- Special keywords (`problems`, `terminal`, `git-changes`)
- **All currently open files** (regardless of ignore settings or directory filters)
The dropdown respects `.rooignore` by default, hiding ignored files from suggestions. Enable the `showRooIgnoredFiles` setting to include ignored files in the dropdown (they'll appear with a 🔒 indicator). Common directories like `node_modules`, `.git`, `dist`, and `out` are also filtered to reduce noise.
---
## Important Behaviors
### Ignore File Interactions
| Behavior | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Dropdown filtering** | The `@` dropdown hides `.rooignore`-matched files by default. Enable `showRooIgnoredFiles` to see them (marked with 🔒). |
| **`.rooignore` bypass** | File and folder `@mentions` bypass `.rooignore` checks when fetching content for context. Content from ignored files will be included if directly mentioned. |
| **`.gitignore` bypass** | Similarly, file and folder `@mentions` do not respect `.gitignore` rules when fetching content. |
| **Git command respect** | Git-related mentions (`@git-changes`, `@commit-hash`) do respect `.gitignore` since they rely on Git commands. |
---
## Related Features
- [Diagnostics Integration](/features/diagnostics-integration) - Learn about automatic error detection and smart severity filtering
- [Code Actions](/features/code-actions) - Discover quick fixes and AI assistance directly in your editor
- [Shell Integration](/features/shell-integration) - Understand how terminal mentions work with shell integration

111
apps/docs/docs/basic-usage/how-tools-work.md Normal file
View file

@ -0,0 +1,111 @@
---
description: Learn how Roo Code uses tools to interact with your system. Understand file operations, command execution, and the approval workflow.
keywords:
- Roo Code tools
- AI tools
- file operations
- command execution
- tool approval
---
# How Tools Work
Roo Code uses tools to interact with your code and environment. These specialized helpers perform specific actions like reading files, making edits, running commands, or searching your codebase. Tools provide automation for common development tasks without requiring manual execution.
---
## Tool Workflow
Describe what you want to accomplish in natural language, and Roo Code will:
1. Select the appropriate tool based on your request
2. Present the tool with its parameters for your review
3. Execute the approved tool and show you the results
4. Continue this process until your task is complete
---
## Tool Categories
| Category | Purpose | Tool Names |
| :------- | :----------------------------------------- | :---------------------------------------------------------------------------------- |
| Read | Access file content and code structure | `read_file`, `search_files`, `list_files`, `codebase_search`, `read_command_output` |
| Edit | Create or modify files and code | `write_to_file`, `apply_diff`, `apply_patch`, `edit`, `edit_file`, `search_replace` |
| Execute | Run commands and perform system operations | `execute_command` |
| Image | Generate AI-powered images | `generate_image` |
| Workflow | Manage task flow and context | `ask_followup_question`, `attempt_completion`, `switch_mode`, `new_task`, `skill` |
---
## Example: Using Tools
Here's how a typical tool interaction works:
<img src="/img/how-tools-work/how-tools-work.png" alt="Tool approval interface showing Save and Reject buttons along with Auto-approve checkbox" width="600" />
_The tool approval interface shows Save/Reject buttons and Auto-approve options._
**User:** Create a file named `greeting.js` that logs a greeting message
**Roo Code:** (Proposes the `write_to_file` tool as shown in the image above)
```xml
<write_to_file>
<path>greeting.js</path>
<content>
function greet(name) {
console.log(`Hello, ${name}!`);
}
greet('World');
</content>
<line_count>5</line_count>
</write_to_file>
```
**User:** (Clicks "Save" in the interface)
**Roo Code:** (Confirms file creation)
---
## Tool Safety and Approval
Every tool use requires your explicit approval. When Roo proposes a tool, you'll see:
- A "Save" button to approve and execute the tool
- A "Reject" button to decline the proposed tool
- An optional "Auto-approve" setting for trusted operations
This safety mechanism ensures you maintain control over which files are modified, what commands are executed, and how your codebase is changed. Always review tool proposals carefully before saving them.
---
## Core Tools Reference
| Tool Name | Description | Category |
| :---------------------- | :--------------------------------------------------------- | :------- |
| `read_file` | Reads the content of a file with line numbers | Read |
| `search_files` | Searches for text or regex patterns across files | Read |
| `list_files` | Lists files and directories in a specified location | Read |
| `codebase_search` | Performs semantic search across your indexed codebase | Read |
| `read_command_output` | Retrieves truncated output from previous commands | Read |
| `write_to_file` | Creates new files or overwrites existing ones | Edit |
| `apply_diff` | Makes precise changes to specific parts of a file | Edit |
| `apply_patch` | Applies multi-file unified diff patches | Edit |
| `edit` | Search-and-replace (first occurrence by default) | Edit |
| `edit_file` | Search-and-replace (all occurrences with count validation) | Edit |
| `search_replace` | Search-and-replace (all occurrences, simple) | Edit |
| `execute_command` | Runs commands in the VS Code terminal | Execute |
| `generate_image` | Generates AI-powered images from text prompts | Image |
| `ask_followup_question` | Asks you a clarifying question | Workflow |
| `attempt_completion` | Indicates the task is complete | Workflow |
| `switch_mode` | Changes to a different operational mode | Workflow |
| `new_task` | Creates a new subtask with a specific starting mode | Workflow |
| `skill` | Loads and executes predefined skill instructions | Workflow |
---
## Learn More About Tools
For more detailed information about each tool, including complete parameter references and advanced usage patterns, see the [Tool Use Overview](/advanced-usage/available-tools/tool-use-overview) documentation.

69
apps/docs/docs/basic-usage/the-chat-interface.md Normal file
View file

@ -0,0 +1,69 @@
---
description: Learn how to use the Roo Code chat interface effectively. Understand the layout, features, and best practices for communicating with your AI coding assistant.
keywords:
- Roo Code chat interface
- AI assistant interaction
- chat features
- user interface
- VS Code extension
---
import KangarooIcon from '@site/src/components/KangarooIcon';
# The Chat Interface
The Roo Code chat interface is your primary way of interacting with it. It's located in the Roo Code panel, which you can open by clicking the Roo Code icon (<KangarooIcon />) in the VS Code Activity Bar.
---
## Components of the Chat Interface
The chat interface consists of the following main elements:
1. **Chat History:** This area displays the conversation history between you and Roo Code. It shows your requests, Roo Code's responses, and any actions taken (like file edits or command executions).
2. **Input Field:** This is where you type your tasks and questions for Roo Code. You can use plain English to communicate.
3. **Action Buttons:** These buttons appear above the input field and allow you to approve or reject Roo Code's proposed actions. The available buttons change depending on the context.
4. **Send Button:** This looks like a small plane and it's located to the far right of the input field. This sends messages to Roo after you've typed them.
5. **Plus Button:** The plus button is located at the top in the header. It switches to the Chat tab and focuses the input. To reset the session, start a new task or clear the current task.
6. **Settings Button:** The settings button is a gear, and it's used for opening the settings to customize features or behavior.
7. **Mode Selector:** The mode selector is a dropdown located to the left of the chat input field. It is used for selecting which mode Roo should use for your tasks. Its settings gear opens the Modes tab, not general settings.
<img src="/img/the-chat-interface/the-chat-interface-1.png" alt="Chat interface components labeled with numbered callouts" width="900" />
_Numbered interface elements showing the key components of the Roo Code chat interface._
---
## Tip: Using the Secondary Sidebar
For a better workflow, you can drag Roo Code to VS Code's [Secondary Sidebar](https://code.visualstudio.com/api/ux-guidelines/sidebars#secondary-sidebar). This allows you to keep Roo Code visible while still having access to the Explorer, Search, Source Control, and other panels in the primary sidebar.
To set this up:
1. Click and drag the Roo Code icon from the Activity Bar
2. Drop it on the right side of your editor to create a secondary sidebar
3. Now you can use both sidebars simultaneously!
For more productivity tips, check out our [Tips & Tricks](/tips-and-tricks) guide.
---
## Interacting with Messages
- **Clickable Links:** File paths, URLs, and other mentions in the chat history are clickable. Clicking a file path will open the file in the editor. Clicking a URL will open it in your default browser.
- **Copying Text:** You can copy text from the chat history by selecting it and using the standard copy command (Ctrl/Cmd + C). Some elements, like code blocks, have a dedicated "Copy" button.
- **Expanding and Collapsing**: Click on a message to expand or collapse it.
---
## Status Indicators
- **Loading Spinner:** When Roo Code is processing a request, you'll see a loading spinner.
- **Error Messages:** If an error occurs, a red error message will be displayed.
- **Success Messages:** Green messages indicate successful completion of actions.

69
apps/docs/docs/basic-usage/typing-your-requests.md Normal file
View file

@ -0,0 +1,69 @@
---
description: Learn how to effectively communicate with Roo Code using natural language. Best practices for typing requests, examples, and common pitfalls to avoid.
keywords:
- Roo Code requests
- natural language AI
- typing commands
- AI communication
- request examples
- best practices
---
# Typing Your Requests
Roo Code is designed to understand natural language. You don't need to use any special commands or syntax to communicate with it. Just type your request in plain English, as if you were talking to a human developer.
<img src="/img/typing-your-requests/naturally.gif" alt="Example of typing a request in Roo Code" width="600" />
---
## Effective Request Strategies
Clearly state what you want Roo Code to do. Avoid vague or ambiguous language.
| Strategy | Implementation |
| -------------------- | ------------------------------------------------------------------------------------------ |
| **Be specific** | "Fix the bug in `calculateTotal` that returns incorrect results" instead of "Fix the code" |
| **Provide context** | Use @ [Context Mentions](/basic-usage/context-mentions) for file and code references |
| **Break down tasks** | Submit complex tasks in smaller manageable steps |
| **Include examples** | Provide sample code when you need specific formatting or style |
---
## Example Requests
```
create a new file named `utils.py` and add a function called `add` that takes two numbers as arguments and returns their sum
```
```
in the file @src/components/Button.tsx, change the color of the button to blue
```
```
find all instances of the variable `oldValue` in @/src/App.js and replace them with `newValue`
```
```
run the command `npm install` in the terminal
```
```
explain the function `calculateTotal` in @/src/utils.ts
```
```
@problems address all detected problems
```
---
## Common Pitfalls to Avoid
| DON'T | DO |
| ------------------------------- | ----------------------------------------- |
| Vague requests | Specify exactly what needs to be done |
| Assuming context | Explicitly reference files and functions |
| Excessive technical jargon | Use clear, straightforward language |
| Multiple unrelated tasks | Submit one focused request at a time |
| Proceeding without confirmation | Check the code to make sure it's complete |

128
apps/docs/docs/basic-usage/using-modes.md Normal file
View file

@ -0,0 +1,128 @@
---
description: Learn how to use Roo Code's specialized modes for different tasks. Switch between Code, Ask, Architect, Debug, and Orchestrator modes for optimal AI assistance.
keywords:
- Roo Code modes
- Code mode
- Ask mode
- Architect mode
- Debug mode
- Orchestrator mode
- AI assistant modes
- mode switching
---
# Using Modes
Modes in Roo Code are specialized personas that tailor the assistant's behavior to your current task. Each mode offers different capabilities, expertise, and access levels to help you accomplish specific goals.
:::info Sticky Models & Mode Persistence
Each mode remembers your last-used model. When switching modes, Roo automatically selects that model—no manual selection needed. Assign different models to different modes (e.g., Gemini 2.5 Preview for `🏗️ Architect` mode, Claude Sonnet 3.7 for `💻 Code` mode) and Roo will switch models automatically when you change modes.
Additionally, your selected mode persists between sessions—Roo remembers which mode you were using when you return.
:::
---
## Why Use Different Modes?
- **Task specialization:** Get precisely the type of assistance you need for your current task
- **Safety controls:** Prevent unintended file modifications when focusing on planning or learning
- **Focused interactions:** Receive responses optimized for your current activity
- **Workflow optimization:** Seamlessly transition between planning, implementing, debugging, and learning
---
## Switching Between Modes
Four ways to switch modes:
1. **Dropdown menu:** Click the selector to the left of the chat input
<img src="/img/using-modes/using-modes.png" alt="Using the dropdown menu to switch modes" width="400" />
2. **Slash command:** Type `/architect`, `/ask`, `/debug`, `/code`, or `/orchestrator` at the beginning of your message. This will switch to that mode and clear the input field.
<img src="/img/using-modes/using-modes-1.png" alt="Using slash commands to switch modes" width="400" />
3. **Toggle command/Keyboard shortcut:** Use the keyboard shortcut below, applicable to your operating system. Each press cycles through the available modes in sequence, wrapping back to the first mode after reaching the end.
| Operating System | Shortcut |
| ---------------- | -------- |
| macOS | ⌘ + . |
| Windows | Ctrl + . |
| Linux | Ctrl + . |
4. **Accept suggestions:** Click on mode switch suggestions that Roo offers when appropriate
<img src="/img/using-modes/using-modes-2.png" alt="Accepting a mode switch suggestion from Roo" width="400" />
---
## Built-in Modes
### Code Mode (Default)
| Aspect | Details |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| **Name** | `💻 Code` |
| **Description** | A skilled software engineer with expertise in programming languages, design patterns, and best practices |
| **Tool Access** | Full access to all tool groups: `read`, `edit`, `command`, `mcp` |
| **Ideal For** | Writing code, implementing features, debugging, and general development |
| **Special Features** | No tool restrictions—full flexibility for all coding tasks |
### Ask Mode
| Aspect | Details |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `❓ Ask` |
| **Description** | A knowledgeable technical assistant focused on providing thorough and complete answers. It's less inclined to switch to implementing code unless explicitly requested and may use diagrams for clarification. |
| **Tool Access** | Limited access: `read`, `mcp` only (cannot edit files or run commands) |
| **Ideal For** | Code explanation, concept exploration, and technical learning |
| **Special Features** | Optimized for detailed, informative responses, often using diagrams for clarity, without modifying your project. |
### Architect Mode
| Aspect | Details |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| **Name** | `🏗️ Architect` |
| **Description** | An experienced technical leader and planner who helps design systems and create implementation plans |
| **Tool Access** | Access to `read`, `mcp`, and restricted `edit` (markdown files only) |
| **Ideal For** | System design, high-level planning, and architecture discussions |
| **Special Features** | Follows a structured approach from information gathering to detailed planning |
### Debug Mode
| Aspect | Details |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `🪲 Debug` |
| **Description** | An expert problem solver specializing in systematic troubleshooting and diagnostics |
| **Tool Access** | Full access to all tool groups: `read`, `edit`, `command`, `mcp` |
| **Ideal For** | Tracking down bugs, diagnosing errors, and resolving complex issues |
| **Special Features** | Uses a methodical approach of analyzing, narrowing possibilities, and fixing issues. Includes custom instructions to reflect, distill possibilities, add logs, and confirm before fixing. |
### Orchestrator Mode (aka Boomerang Mode)
| Aspect | Details |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | `🪃 Orchestrator` |
| **Description** | A strategic workflow orchestrator (aka Boomerang Mode) that breaks down complex tasks and delegates them to specialized modes. Learn more about [Boomerang Tasks](/features/boomerang-tasks). |
| **Tool Access** | No direct tool access (uses `new_task` tool to delegate work to other modes) |
| **Ideal For** | Managing multi-step projects, coordinating work across different modes, and automating complex workflows |
| **Special Features** | Uses the [`new_task`](/advanced-usage/available-tools/new-task) tool to delegate subtasks to other modes. |
---
## Customizing Modes
Tailor Roo Code's behavior by customizing existing modes or creating new specialized assistants. Define tool access, file permissions, and behavior instructions to enforce team standards or create purpose-specific assistants. See [Custom Modes documentation](/features/custom-modes) for setup instructions.
### Understanding Tool Groups
Each tool group provides specific capabilities:
- **`read`**: File reading, listing, and searching capabilities
- **`edit`**: File modification and creation capabilities
- **`command`**: Terminal command execution
- **`mcp`**: Model Context Protocol server interactions
For detailed information about available tools, see the [Available Tools documentation](/advanced-usage/available-tools/tool-use-overview).

210
apps/docs/docs/faq.md Normal file
View file

@ -0,0 +1,210 @@
---
description: Find answers to common questions about Roo Code, including setup, usage, troubleshooting, and advanced features. Get help with API keys, modes, and more.
keywords:
- Roo Code FAQ
- frequently asked questions
- troubleshooting
- API setup
- custom modes
- MCP
- local models
---
import KangarooIcon from '@site/src/components/KangarooIcon';
# Frequently Asked Questions
This page answers some common questions about Roo Code.
---
## General
### What is Roo Code?
Roo Code is an open-source AI coding agent for VS Code designed to take full advantage of advanced large-language models.
### How does Roo Code work?
Roo Code uses large language models (LLMs) to understand your requests and translate them into actions. It can:
- Read and write files in your project
- Execute shell commands
- Perform web browsing (if enabled)
- Use external tools via the Model Context Protocol (MCP)
You interact with Roo Code through a chat interface in the extension.
### What can Roo Code do?
Roo Code can help with a variety of coding tasks, including:
- Generating code from natural language descriptions.
- Refactoring existing code.
- Fixing bugs.
- Writing documentation.
- Explaining code.
- Answering questions about your codebase.
- Automating repetitive tasks.
- Creating new files and projects.
### Is Roo Code free to use?
The Roo Code extension is free and [open-source](https://github.com/RooCodeInc/Roo-Code/).
Roo Code relies on external LLM inference providers (like [Anthropic](providers/anthropic), [OpenAI](providers/openai), [OpenRouter](providers/openrouter), [Requesty](providers/requesty), etc.) for its AI capabilities.
These providers typically charge for API usage based on the number of tokens processed. You will need to create an account and obtain an API key from your chosen provider. Learn more [about providers and how to set them up](/providers/) for details.
### What are the risks of using Roo Code?
Roo Code is a powerful tool, and it's important to use it responsibly. Here are some things to keep in mind:
- **Roo Code can make mistakes.** Always review Roo Code's proposed changes carefully before approving them.
- **Roo Code can execute commands.** Be very cautious about allowing Roo Code to run commands, especially if you're using auto-approval.
- **Roo Code can access the internet.** If you're using a provider that supports web browsing, be aware that Roo Code could potentially access sensitive information.
---
## Setup & Installation
### How do I install Roo Code?
See the [Installation Guide](/getting-started/installing) for detailed instructions.
### Which API providers are supported?
See the [full list here](/providers/).
### How do I get an API key?
Each API provider has its own process for obtaining an API key. See the [Setting Up Your First AI Provider](/getting-started/connecting-api-provider) for links to the relevant documentation for each provider.
### Can I use Roo Code with local models?
Yes, Roo Code supports running models locally using [Ollama](/providers/ollama) and [LM Studio](/providers/lmstudio). See [Using Local Models](/advanced-usage/local-models) for instructions.
---
## Extension Usage
### How do I start a new task?
Open the Roo Code panel (<KangarooIcon />) and type your task in the chat box. Be clear and specific about what you want Roo Code to do. See [Typing Your Requests](/basic-usage/typing-your-requests) for best practices.
### What are modes in Roo Code?
[Modes](/basic-usage/using-modes) are different personas that Roo Code can adopt, each with a specific focus and set of capabilities. The built-in modes are:
- **Code:** For general-purpose coding tasks.
- **Architect:** For planning and technical leadership.
- **Ask:** For answering questions and providing information.
- **Debug:** For systematic problem diagnosis.
You can also create [Custom Modes](/features/custom-modes).
### How do I switch between modes?
Use the dropdown menu in the chat input area to select a different mode, or use the `/` command to switch to a specific mode.
### What are tools and how do I use them?
[Tools](/basic-usage/how-tools-work) are how Roo Code interacts with your system. Roo Code automatically selects and uses the appropriate tools to complete your tasks. You don't need to call tools directly. You will be prompted to approve or reject each tool use.
### What are context mentions?
[Context mentions](/basic-usage/context-mentions) are a way to provide Roo Code with specific information about your project, such as files, folders, or problems. Use the "@" symbol followed by the item you want to mention (e.g., `@/src/file.ts`, `@problems`).
### Can Roo Code access the internet?
Yes, if you are using a provider with a model that support web browsing. Be mindful of the security implications of allowing this.
### Can Roo Code run commands in my terminal?
Yes, Roo Code can execute commands in your VS Code terminal. You will be prompted to approve each command before it's executed, unless you've enabled auto-approval for commands. Be extremely cautious about auto-approving commands. If you're experiencing issues with terminal commands, see the [Shell Integration Guide](/features/shell-integration) for troubleshooting.
### How do I provide feedback to Roo Code?
You can provide feedback by approving or rejecting Roo Code's proposed actions. You can provide additional feedback by using the feedback field.
### Can I customize Roo Code's behavior?
Yes, you can customize Roo Code in several ways:
- **Custom Instructions:** Provide general instructions that apply to all modes, or mode-specific instructions.
- **Custom Modes:** Create your own modes with tailored prompts and some tool permissions.
- **`.roorules` Files:** Create `.roorules` files in your project to provide additional guidelines.
- **Settings:** Adjust various settings, such as auto-approval, diff editing, and more.
### Does Roo Code have any auto approval settings?
Yes, Roo Code has a few settings that when enabled will automatically approve actions. Find out more [here](/features/auto-approving-actions).
---
## Advanced Features
### Can I use Roo offline?
Yes, if you use a [local model](/advanced-usage/local-models).
### What is MCP (Model Context Protocol)?
[MCP](/features/mcp/overview) is a protocol that allows Roo Code to communicate with external servers, extending its capabilities with custom tools and resources.
### Can I create my own MCP servers?
Yes, you can create your own MCP servers to add custom functionality to Roo Code. See the [MCP documentation](https://github.com/modelcontextprotocol) for details.
### What is Codebase Indexing?
[Codebase Indexing](/features/codebase-indexing) creates a semantic search index of your project using AI embeddings. This enables Roo Code to better understand and navigate large codebases by finding relevant code based on meaning rather than just keywords.
### How much does Codebase Indexing cost?
Codebase Indexing requires an OpenAI API key for generating embeddings and a Qdrant vector database for storage. Costs depend on your project size and the embedding model used. Initial indexing is the most expensive part; subsequent updates are incremental and much cheaper.
---
## Troubleshooting
### Roo Code isn't responding. What should I do?
- Make sure your API key is correct and hasn't expired.
- Check your internet connection.
- Check the status of your chosen API provider.
- Try restarting VS Code.
- If the problem persists, report the issue on [GitHub](https://github.com/RooCodeInc/Roo-Code/issues) or [Discord](https://discord.gg/roocode).
### I'm seeing an error message. What does it mean?
The error message should provide some information about the problem. If you're unsure how to resolve it, seek help in [Discord](https://discord.gg/roocode).
### Roo Code made changes I didn't want. How do I undo them?
Roo Code uses VS Code's built-in file editing capabilities. You can use the standard "Undo" command (Ctrl/Cmd + Z) to revert changes. Also, if experimental checkpoints are enabled, Roo can revert changes made to a file.
### Roo Code can't write to markdown files. What's wrong?
If Roo Code fails to write to `.md` files with errors like "Failed to open diff editor" or "write_to_file tool failed", this is typically caused by VS Code extensions or settings that interfere with file editing:
**Common causes:**
- Extensions with "format on save" functionality
- VS Code settings that open markdown files in preview mode by default
- The Markdown Preview extension or similar markdown processing extensions
**Solutions:**
- Disable any extensions that automatically format files on save
- Remove these settings from your VS Code `settings.json`:
```json
"markdown.preview.openMarkdownLinks": "inPreview",
"workbench.editorAssociations": {
"*.md": "vscode.markdown.preview.editor"
}
```
- Temporarily disable markdown-related extensions to test if they're causing the issue
- Restart VS Code after making these changes
### How do I report a bug or suggest a feature?
Please report bugs or suggest features on the Roo Code [Issues page](https://github.com/RooCodeInc/Roo-Code/issues) and [Feature Requests page](https://github.com/RooCodeInc/Roo-Code/discussions/categories/feature-requests?discussions_q=is%3Aopen+category%3A%22Feature+Requests%22+sort%3Atop).

146
apps/docs/docs/features/api-configuration-profiles.mdx Normal file
View file

@ -0,0 +1,146 @@
---
description: Learn how to create and manage API configuration profiles to easily switch between different AI providers and models in Roo Code.
keywords:
- API configuration
- profiles
- AI providers
- model switching
- API management
---
# API Configuration Profiles
API Configuration Profiles allow you to create and switch between different sets of AI settings. Each profile can have different configurations for each mode, letting you optimize your experience based on the task at hand.
:::info
Having multiple configuration profiles lets you quickly switch between different AI providers, models, and settings without reconfiguring everything each time you want to change your setup.
:::
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/eEJErgZBqLE?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
<br />
---
## How It Works
Configuration profiles can have their own:
- API providers (OpenAI, Anthropic, OpenRouter, etc.)
- API keys and authentication details
- Model selections (o3-mini-high, Claude 3.7 Sonnet, DeepSeek R1, etc.)
- [Temperature settings](/features/model-temperature) for controlling response randomness
- Thinking budgets
- Provider-specific settings
- Diff editing configuration (see [`apply_diff`](/advanced-usage/available-tools/apply-diff))
- Rate limit settings
Note that available settings vary by provider and model. Each provider offers different configuration options, and even within the same provider, different models may support different parameter ranges or features.
---
## Creating and Managing Profiles
### Creating a Profile
1. Open Settings by clicking the gear icon <Codicon name="gear" /> → Providers
2. Click the "+" button next to the profile selector
<img src="/img/api-configuration-profiles/api-configuration-profiles-1.png" alt="Profile selector with plus button" width="550" />
3. Enter a name for your new profile
<img src="/img/api-configuration-profiles/api-configuration-profiles.png" alt="Creating a new profile dialog" width="550" />
4. Configure the profile settings:
- Select your API provider
<img src="/img/api-configuration-profiles/api-configuration-profiles-2.png" alt="Provider selection dropdown" width="550" />
- Enter API key
<img src="/img/api-configuration-profiles/api-configuration-profiles-3.png" alt="API key entry field" width="550" />
- Choose a model
<img src="/img/api-configuration-profiles/api-configuration-profiles-8.png" alt="Model selection interface" width="550" />
- Configure the **Rate Limit** for this profile:
- **Default is 0 (disabled), which is suitable for most users.** If needed, you can set a minimum time (in seconds) between API requests *for this profile* to help manage costs or avoid provider rate limits.
- A value of 0 disables rate limiting (default).
- Requests using other profiles follow their own rate limits.
<img src="/img/api-configuration-profiles/api-configuration-profiles-12.png" alt="Rate limit slider control within API profile settings" width="550" />
- Adjust model parameters (like [temperature](/features/model-temperature))
### Switching Profiles
Switch profiles in two ways:
1. From Settings panel: Select a different profile from the dropdown
<img src="/img/api-configuration-profiles/api-configuration-profiles-7.png" alt="Profile selection dropdown in Settings" width="550" />
2. During chat: Access the API Configuration dropdown in the chat interface
<img src="/img/api-configuration-profiles/api-configuration-profiles-6.png" alt="API Configuration dropdown in chat interface" width="550" />
### Pinning and Sorting Profiles
The API configuration dropdown now supports pinning your favorite profiles for quicker access:
1. Hover over any profile in the dropdown to reveal the pin icon
2. Click the pin icon to add the profile to your pinned list
3. Pinned profiles appear at the top of the dropdown, sorted alphabetically
4. Unpinned profiles appear below a separator, also sorted alphabetically
5. You can unpin a profile by clicking the same icon again
<img src="/img/api-configuration-profiles/api-configuration-profiles-4.png" alt="Pinning API configuration profiles" width="550" />
This feature makes it easier to navigate between commonly used profiles, especially when you have many configurations.
### Editing and Deleting Profiles
<img src="/img/api-configuration-profiles/api-configuration-profiles-10.png" alt="Profile editing interface" width="550" />
- Select the profile in Settings to modify any settings
- Click the pencil icon to rename a profile
- Click the trash icon to delete a profile (you cannot delete the only remaining profile)
---
## Linking Profiles to Modes
In the <Codicon name="notebook" /> Prompts tab, you can explicitly associate a specific Configuration Profile with each Mode. The system also automatically remembers which profile you last used with each mode, making your workflow more efficient.
<img src="/img/api-configuration-profiles/api-configuration-profiles-11.png" alt="Profile-Mode association interface in Prompts tab" width="550" />
---
## Per-Task Profile Persistence
Each task remembers which profile it started with. This "sticky" behavior means:
- **Reopening from history**: When you resume a task from history, it uses the same profile it had originally—even if you've since changed the global selection.
- **Multi-workspace consistency**: If you switch profiles in another workspace window, existing tasks in the first window keep their original profile.
- **Orchestrator subtasks**: Child tasks created by the orchestrator inherit the parent's profile and retain it for their lifetime.
This prevents unexpected model switches mid-task and keeps your conversation context consistent with the model that generated it.
---
## Security Note
API keys are stored securely in VSCode's Secret Storage and are never exposed in plain text.
---
## Related Features
- Works with [custom modes](/features/custom-modes) you create
- Integrates with [local models](/advanced-usage/local-models) for offline work
- Supports [temperature settings](/features/model-temperature) per mode
- Supports per-profile rate limits (configured here) and general [usage tracking/cost info](/advanced-usage/rate-limits-costs)
- Supports diff-based editing (see [`apply_diff`](/advanced-usage/available-tools/apply-diff)).

339
apps/docs/docs/features/auto-approving-actions.mdx Normal file
View file

@ -0,0 +1,339 @@
---
description: Learn how to configure auto-approval settings in Roo Code to speed up repetitive tasks while maintaining control over sensitive operations.
keywords:
- auto-approval
- Roo Code automation
- workflow optimization
- auto-approve settings
- safe operations
---
# Auto-Approving Actions
> ⚠️ **SECURITY WARNING:** Auto-approve settings bypass confirmation prompts, giving Roo direct access to your system. This can result in **data loss, file corruption, or worse**. Command line access is particularly dangerous, as it can potentially execute harmful operations that could damage your system or compromise security. Only enable auto-approval for actions you fully trust.
Auto-approve settings speed up your workflow by eliminating repetitive confirmation prompts, but they significantly increase security risks.
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/bWtIxGsl2cQ?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
<br />
---
## Quick Start Guide
1. Open the Auto-Approve dropdown next to the chat input
2. Toggle "Enabled" at the bottom-right of the dropdown to activate or pause auto-approval
3. Use the All/None chips to bulk-select or clear permissions, or select individual tiles; you can keep Enabled On with "None" selected
4. (Optional) Click the gear icon to open Settings for deeper per-permission controls
### Keyboard Shortcut and Command Palette
**Default shortcut:** `Cmd+Alt+A` (macOS) / `Ctrl+Alt+A` (Windows/Linux)
**Command Palette:** `roo-cline.toggleAutoApprove`
Quickly toggle auto-approve on/off without using the mouse. Both the keyboard shortcut and the Command Palette command toggle the global "Enabled" state while preserving your permission selections.
**Via Command Palette:**
1. Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Type "Toggle Auto-Approve" or search for `roo-cline.toggleAutoApprove`
3. Press Enter to toggle the auto-approve state
**To customize the shortcut:**
1. Open VS Code Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Search for "Preferences: Open Keyboard Shortcuts"
3. Search for the command name (varies by language):
- English: "Toggle Auto-Approve"
- Other languages: Look for the localized equivalent
4. Click the pencil icon next to the command
5. Press your desired key combination
6. Press Enter to save
**Note:** The command name appears in your VS Code interface language. If you're using a non-English locale, the command will be translated accordingly.
---
## Auto-Approve Dropdown
<img src="/img/auto-approving-actions/auto-approving-actions-20.png" alt="Auto-Approve dropdown with All/None chips and global Enabled toggle (bottom-right)" width="600" />
The dropdown shows a grid of permission tiles. Controls:
- Enabled (bottom-right): master pause/resume for auto-approval
- All / None (bottom-left): bulk select or clear permissions without changing Enabled
- Permission tiles: choose which actions can run without prompts; tiles disable only when Enabled is off. Some permissions take effect only if your model supports the capability.
### Available Permissions
| Permission | What it does | Risk level |
|------------|--------------|------------|
| **Read files and directories** | Lets Roo access files without asking | Medium |
| **Edit files** | Lets Roo modify files without asking | **High** |
| **Execute approved commands** | Runs whitelisted terminal commands automatically | **High** |
| **Use the browser** | Allows headless browser interaction | Medium |
| **Use MCP servers** | Lets Roo use configured MCP services | Medium-High |
| **Switch modes** | Changes between Roo modes automatically | Low |
| **Create & complete subtasks** | Manages subtasks without confirmation | Low |
| **Answer follow-up questions** | Selects default answer for follow-up questions| Low |
---
## Global Enabled Switch
<img src="/img/auto-approving-actions/auto-approving-actions-21.png" alt="Auto-Approve dropdown; Enabled at bottom-right and All/None chips at bottom-left" width="600" />
How it works:
- Enabled On — Auto-approval runs for the permissions you’ve selected
- Enabled Off — Pauses all auto-approvals; your per-permission selections persist
- All / None — Bulk adjust selections while Enabled remains unchanged
- Note: Auto-approve only runs if Enabled is On and at least one permission is selected.
When to toggle:
- Sensitive or production work → Off
- Rapid iteration and refactors → On
- Switching between exploration and editing tasks
---
## Advanced Settings Panel
The settings panel provides detailed control with important security context:
> **Allow Roo to automatically perform operations without requiring approval. Enable these settings only if you fully trust the AI and understand the associated security risks.**
To access these settings:
1. Click <Codicon name="gear" /> in the top-right of the dropdown
2. Navigate to Auto-Approve Settings
The settings panel mirrors the same permissions with additional context and safeguards.
#### Important behaviors
- Outside‑workspace reads/writes require the corresponding outside‑workspace flags in addition to the base permission.
- Auto‑approve for MCP tools requires both the global "Always approve MCP tools" and each tool's "Always allow". Resource access honors only the global setting.
- Mode switching is only auto‑approved when the mode-switch permission is enabled (covers switching to another mode and creating new modes).
- After auto‑writes, Roo waits using the global write‑delay control under Settings → Context Management → Diagnostics.
### Read Operations
:::info Read Operations (Risk: Medium)
<img src="/img/auto-approving-actions/auto-approving-actions-3.png" alt="Read-only operations setting" width="550" />
**Setting:** "Always approve read-only operations"
**Description:** "When enabled, Roo will automatically view directory contents and read files without requiring you to click the Approve button."
**Additional option:**
- **Include files outside workspace:** Allow Roo to read files outside the current workspace directory
**Risk level:** Medium
While this setting only allows reading files (not modifying them), it could potentially expose sensitive data. Still recommended as a starting point for most users, but be mindful of what files Roo can access.
#### Workspace Boundary Protection
By default, Roo can only read files within your current workspace directory. The "Include files outside workspace" option extends read access beyond the workspace boundary. Consider the security implications:
- **Default (unchecked)**: Roo can only read files in your project directory
- **Enabled**: Roo can read any file on your system that you have access to
- **Recommendation**: Keep disabled unless you specifically need Roo to access external files
:::
### Write Operations
:::caution Write Operations (Risk: High)
<img src="/img/auto-approving-actions/auto-approving-actions-16.png" alt="Write operations setting with delay slider" width="550" />
**Setting:** "Always approve write operations"
**Description:** "Automatically create and edit files without requiring approval"
**Write delay control:** Configured under Settings → Context Management → Diagnostics. See [Diagnostics Integration](/features/diagnostics-integration).
**Additional options:**
- **Include files outside workspace:** Allow Roo to modify files outside the current workspace directory
- **Include protected files:** Allow Roo to modify files protected by `.roo/` and `.rooignore` directory
**Risk level:** High
This setting allows Roo to modify your files without confirmation. The delay timer is crucial:
- Higher values (2000ms+): Recommended for complex projects where diagnostics take longer
- Default (1000ms): Suitable for most projects with active diagnostics
- 0ms: No delay - use when speed is critical
- Lower values: Use only when in a controlled environment
#### Security Boundaries
The write operations setting includes two important security controls:
1. **Workspace Boundary Protection**: By default, Roo can only modify files within your current workspace. Enable "Include files outside workspace" with extreme caution.
2. **Protected Files**: Roo blocks modification of:
- Files in the `.roo/` directory
- The `.rooignore` file
The "Include protected files" option bypasses this protection - use only when you specifically need to modify these files.
#### Write Delay & Problems Pane Integration
<img src="/img/auto-approving-actions/auto-approving-actions-5.png" alt="VSCode Problems pane showing diagnostic information" width="600" />
*VSCode Problems pane that Roo checks during the write delay*
When you enable auto-approval for writing files, Roo uses the global write-delay configured under Settings → Context Management → Diagnostics. The delay timer works with VSCode's Problems pane:
1. Roo makes a change to your file
2. VSCode's diagnostic tools analyze the change
3. The Problems pane updates with any errors or warnings
4. Roo notices these issues before continuing
This works like a human developer pausing to check for errors after changing code. You can adjust the delay time based on:
- Project complexity
- Language server speed
- How important error detection is for your workflow
:::
### MCP Tools
:::caution MCP Tools (Risk: Medium-High)
**Setting:** "Always approve MCP tools"
**Description:** "Enable auto-approval of individual MCP tools in the MCP Servers view (requires both this setting and the tool's individual 'Always allow' checkbox)"
**Risk level:** Medium-High (depends on configured MCP tools)
This setting requires a two-step permission process for security:
1. **Enable this global setting** - Acts as a master switch for all MCP tool auto-approval
2. **Enable individual tool permissions** - In the MCP Servers view, check "Always allow" for specific tools
**Important:** Both permissions must be active for a tool to auto-approve. This dual-permission system ensures you maintain granular control over which MCP tools can execute without confirmation. Resource retrieval (`access_mcp_resource`) honors only the global setting.
**Permission Storage:** Your MCP tool permissions are saved and will be remembered next time you use Roo Code.
Example workflow:
- Enable "Always approve MCP tools" in settings
- Navigate to MCP Servers view
- Find the specific tool (e.g., filesystem operations)
- Check its "Always allow" checkbox
- Only then will that specific tool auto-approve
:::
### Mode Switching
:::info Mode Switching (Risk: Low)
**Setting:** "Always approve mode switching"
**Description:** "Automatically switch between different modes without requiring approval"
**Risk level:** Low
Allows Roo to change between different modes (Code, Architect, etc.) without asking for permission. This primarily affects the AI's behavior rather than system access. Auto-approval also covers switching between modes and creating new modes when this permission is enabled.
:::
### Subtasks
:::info Subtasks (Risk: Low)
**Setting:** "Always approve creation & completion of subtasks"
**Description:** "Allow creation and completion of subtasks without requiring approval"
**Risk level:** Low
Enables Roo to create and complete subtasks automatically. This relates to workflow organization rather than system access.
:::
### Command Execution
:::caution Command Execution (Risk: High)
<img src="/img/auto-approving-actions/auto-approving-actions-18.png" alt="Command execution setting with whitelist interface" width="550" />
**Setting:** "Always approve allowed execute operations"
**Description:** "Automatically execute allowed terminal commands without requiring approval"
**Command management:** "Command prefixes that can be auto-executed when 'Always approve execute operations' is enabled. Add * to allow all commands (use with caution)."
**Risk level:** High
This setting allows terminal command execution with controls. Use an allowlist and a denylist together for defense-in-depth.
- Precedence: Deny rules take precedence when their matching prefix is equally or more specific than the allow match (longest-prefix wins).
- High-risk commands to deny by default:
- Unix/macOS: rm, sudo, dd, mkfs, diskutil eraseDisk, shutdown, reboot, chmod -R, chown -R, kill -9, curl | sh, wget | sh
- Git/Package: git push, npm publish, yarn publish, pnpm publish
- Windows/PowerShell: Remove-Item, Format-Volume, Stop-Process, shutdown, Set-ExecutionPolicy
- Production template:
- Deny all with "*" then allow specific safe prefixes like "git", "npm run", "echo".
- Dangerous substitution guard: Even allowed prefixes won’t auto-approve if the command contains dangerous parameter or process substitutions (e.g., `${var@P}`, subshells inserted into here-strings, zsh process substitution `=(...)`, zsh glob qualifiers with `e:...:`).
Configuration
- UI (recommended): Settings → Auto‑Approve → Execute → use "Allowed Commands" and "Denied Commands" editors to add/remove prefixes.
- Settings JSON (alternative):
```json
{
"roo-cline.allowedCommands": ["git", "npm run", "echo"],
"roo-cline.deniedCommands": ["git push", "npm publish", "rm", "sudo", "*"]
}
```
With both lists defined, the longest‑prefix rule applies; if deny is equally or more specific, it wins.
Examples of safe allow prefixes:
- `git`
- `npm run`
- `python -m pytest`
- `cargo test`
- `go test`
- `docker ps`
- `ls`
- `cat`
Security tip: Be specific with prefixes. Instead of allowing all `python` commands, limit to `python -m pytest` for test execution only.
:::
### Follow-Up Questions
:::info Follow-Up Questions (Risk: Low)
<img src="/img/auto-approving-actions/auto-approving-actions-15.png" alt="Follow-up question operations setting with timeout slider" width="550" />
**Setting:** `Always default answer for follow-up questions`
**Description:** Automatically selects the first AI-suggested answer for a follow-up question after a configurable timeout. This speeds up your workflow by letting Roo proceed without manual intervention.
**Timeout slider:** Use the slider to set the wait time from 1 to 300 seconds (Default: 60 seconds)
**How it works:**
- After the configured timeout, the first suggestion is automatically selected
- Any user action (choosing a different suggestion, editing, or typing your own response) cancels auto-selection
**Override options:** You can cancel auto-selection at any time by:
- Clicking a different suggestion
- Editing any suggestion
- Typing your own response
**Risk level:** Low
**Use cases:**
- Overnight runs where you want Roo to continue working
- Repetitive tasks where the default suggestions are usually correct
- Testing workflows where interaction isn't critical
:::

118
apps/docs/docs/features/boomerang-tasks.mdx Normal file
View file

@ -0,0 +1,118 @@
---
description: Learn how to use Boomerang Tasks (Orchestrator mode) to automate complex workflows by delegating subtasks to specialized modes.
keywords:
- Boomerang Tasks
- Orchestrator mode
- workflow automation
- task delegation
- automated workflows
sidebar_label: 'Boomerang Tasks'
---
# Boomerang Tasks: Orchestrate Complex Workflows
Boomerang Tasks (also known as subtasks or task orchestration) allow you to break down complex projects into smaller, manageable pieces using the built-in **`🪃 Orchestrator` Mode (aka Boomerang Mode)**. Think of it like delegating parts of your work to specialized assistants. Each subtask runs in its own context, often using a different Roo Code mode tailored for that specific job (like [`💻 Code`](/basic-usage/using-modes#code-mode-default), [`🏗️ Architect`](/basic-usage/using-modes#architect-mode), or [`🪲 Debug`](/basic-usage/using-modes#debug-mode)). The Orchestrator mode manages this process.
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/RX862U09fnE?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
<br />
:::info Orchestrator Mode is Built-In
The `🪃 Orchestrator` mode (previously achieved via a custom "Boomerang Mode") is now a built-in mode specifically designed to orchestrate workflows by breaking down tasks and delegating them to other modes. You no longer need to create a custom mode for this functionality.
Learn more about [Built-in Modes](/basic-usage/using-modes#built-in-modes).
:::
---
## Why Use Boomerang Tasks?
- **Tackle Complexity:** Break large, multi-step projects (e.g., building a full feature) into focused subtasks (e.g., design, implementation, documentation).
- **Use Specialized Modes:** Automatically delegate subtasks to the mode best suited for that specific piece of work, leveraging specialized capabilities for optimal results.
- **Maintain Focus & Efficiency:** Each subtask operates in its own isolated context with a separate conversation history. This prevents the parent (orchestrator) task from becoming cluttered with the detailed execution steps (like code diffs or file analysis results), allowing it to focus efficiently on the high-level workflow and manage the overall process based on concise summaries from completed subtasks.
- **Streamline Workflows:** Results from one subtask can be automatically passed to the next, creating a smooth flow (e.g., architectural decisions feeding into the coding task).
---
## How It Works
1. When in the [`🪃 Orchestrator`](/basic-usage/using-modes#orchestrator-mode-aka-boomerang-mode) mode (aka Boomerang Mode), Roo analyzes a complex task and suggests breaking it down into a subtask[^1].
2. The parent task (in Orchestrator mode) pauses, and the new subtask begins in a different, specialized mode[^2].
3. When the subtask's goal is achieved, Roo signals completion.
4. The parent task resumes with only the summary[^3] of the subtask. The parent uses this summary to continue the main workflow.
---
## Key Considerations
- **Approval Required:** By default, you must approve the creation and completion of each subtask. This can be automated via the [Auto-Approving Actions](/features/auto-approving-actions#subtasks) settings if desired.
- **Context Isolation and Transfer:** Each subtask operates in complete isolation with its own conversation history. It does not automatically inherit the parent's context. Information must be explicitly passed:
* **Down:** Via the initial instructions provided when the subtask is created.
* **Up:** Via the final summary provided when the subtask finishes. Be mindful that only this summary returns to the parent.
- **Navigation:** Roo's interface helps you see the hierarchy of tasks (which task is the parent, which are children). You can typically navigate between active and paused tasks.
Boomerang Tasks provide a powerful way to manage complex development workflows directly within Roo Code, leveraging specialized modes for maximum efficiency.
:::tip Keep Tasks Focused
Use subtasks (delegated via Orchestrator mode) to maintain clarity. If a request significantly shifts focus or requires a different expertise (mode), consider creating a subtask rather than overloading the current one.
:::
---
## Frequently Asked Questions
### Why can't Orchestrator mode read files, write files, call MCPs, or run commands?
The Orchestrator mode is intentionally limited to focus on high-level workflow management. Giving it the ability to read files by default causes the context to become filled with file reads, hampering its ability to remain focused on orchestration. The design philosophy is that subtasks should handle the detailed work and return only the necessary information (via their completion summaries) for the orchestrator to delegate further tasks effectively.
This limitation helps prevent [context poisoning](/advanced-usage/context-poisoning), where irrelevant or excessive information contaminates the model's active context, leading to degraded performance and task deviation.
### How can I override Orchestrator mode's limitations?
You can [customize the Orchestrator mode](/features/custom-modes) to add capabilities like file reading by following the [configuration precedence](/features/custom-modes#configuration-precedence) system:
1. Open the Command Palette and select **"Edit Global Modes"**
2. Copy and paste this configuration:
```json
{
"customModes": [
{
"slug": "orchestrator",
"name": "🪃 Orchestrator",
"roleDefinition": "You are Roo, a strategic workflow orchestrator who coordinates complex tasks by delegating them to appropriate specialized modes. You have a comprehensive understanding of each mode's capabilities and limitations, allowing you to effectively break down complex problems into discrete tasks that can be solved by different specialists.",
"customInstructions": "Your role is to coordinate complex workflows by delegating tasks to specialized modes. As an orchestrator, you should:\n\n1. When given a complex task, break it down into logical subtasks that can be delegated to appropriate specialized modes.\n\n2. For each subtask, use the `new_task` tool to delegate. Choose the most appropriate mode for the subtask's specific goal and provide comprehensive instructions in the `message` parameter. These instructions must include:\n * All necessary context from the parent task or previous subtasks required to complete the work.\n * A clearly defined scope, specifying exactly what the subtask should accomplish.\n * An explicit statement that the subtask should *only* perform the work outlined in these instructions and not deviate.\n * An instruction for the subtask to signal completion by using the `attempt_completion` tool, providing a concise yet thorough summary of the outcome in the `result` parameter, keeping in mind that this summary will be the source of truth used to keep track of what was completed on this project. \n * A statement that these specific instructions supersede any conflicting general instructions the subtask's mode might have.\n\n3. Track and manage the progress of all subtasks. When a subtask is completed, analyze its results and determine the next steps.\n\n4. Help the user understand how the different subtasks fit together in the overall workflow. Provide clear reasoning about why you're delegating specific tasks to specific modes.\n\n5. When all subtasks are completed, synthesize the results and provide a comprehensive overview of what was accomplished.\n\n6. Ask clarifying questions when necessary to better understand how to break down complex tasks effectively.\n\n7. Suggest improvements to the workflow based on the results of completed subtasks.\n\nUse subtasks to maintain clarity. If a request significantly shifts focus or requires a different expertise (mode), consider creating a subtask rather than overloading the current one.",
"groups": [
"read"
],
"source": "global"
}
]
}
```
3. Save the file. Your global Orchestrator mode will now have read capabilities.
:::warning
Adding capabilities to the Orchestrator mode should be done thoughtfully. The limited default capabilities help maintain focus on orchestration rather than implementation details.
:::
[^1]: This context is passed via the `message` parameter of the [`new_task`](/advanced-usage/available-tools/new-task) tool when the Orchestrator mode delegates the task.
[^2]: The mode for the subtask is specified via the `mode` parameter of the [`new_task`](/advanced-usage/available-tools/new-task) tool during initiation by the Orchestrator mode.
[^3]: This summary is passed via the `result` parameter of the [`attempt_completion`](/advanced-usage/available-tools/attempt-completion) tool when the subtask finishes.

289
apps/docs/docs/features/checkpoints.mdx Normal file
View file

@ -0,0 +1,289 @@
---
description: Learn how to use checkpoints in Roo Code to save your progress, revert changes, and manage your coding workflow with confidence.
keywords:
- checkpoints
- save progress
- version control
- undo changes
- restore state
- workflow management
---
# Checkpoints
Checkpoints automatically version your workspace files during Roo Code tasks, enabling non-destructive exploration of AI suggestions and easy recovery from unwanted changes.
Checkpoints let you:
- Safely experiment with AI-suggested changes
- Easily recover from undesired modifications
- Compare different implementation approaches
- Revert to previous project states without losing work
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe title="Checkpoints Tutorial Video"
src="https://www.youtube.com/embed/Ho30nyY332E?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
<div style={{ marginTop: '20px' }}></div>
:::info Important Notes
- **Checkpoints are enabled by default.**
- **Git must be installed** for checkpoints to function - [see installation instructions](#git-installation)
- No GitHub account or repository is required
- No Git personal information configuration is needed
- The shadow Git repository operates independently from your project's existing Git configuration
:::
---
## Configuration Options
Access checkpoint settings in Roo Code settings under the "Checkpoints" section:
1. Open Settings by clicking the gear icon <Codicon name="gear" /> → Checkpoints
2. Configure checkpoint behavior:
- Check or uncheck the "Enable automatic checkpoints" checkbox
- Adjust the "Checkpoint initialization timeout" (10-60 seconds, default: 30s)
<img src="/img/checkpoints/checkpoints.png" alt="Checkpoint settings in Roo Code configuration" width="500" />
#### Checkpoint Initialization Timeout
Controls how long the system waits for checkpoint initialization to complete before showing a warning. If your project has many files or is on slower storage, increasing this timeout can prevent premature warnings.
- **Range**: 10-60 seconds
- **Default**: 30 seconds
- **When to increase**: Large projects, slow disk I/O, or network-mounted directories
- **Location**: Settings → Checkpoints → "Checkpoint initialization timeout"
---
## How Checkpoints Work
Roo Code captures snapshots of your project's state using a shadow Git repository, separate from your main version control system. These snapshots, called checkpoints, are automatically created **before** file modifications occur, ensuring you can always undo unwanted changes. Checkpoints are recorded when tasks begin and before file modifications. They are not automatically created before command execution.
Checkpoints are stored as Git commits in the shadow repository, capturing:
- File content changes
- New files added
- Deleted files
- Renamed files
- Binary file changes
---
## Working with Checkpoints
Checkpoints are integrated directly into your workflow through the chat interface.
Checkpoints appear directly in your chat history:
- **Task checkpoint** marks your starting project state
<img src="/img/checkpoints/checkpoints-1.png" alt="Task checkpoint indicator in chat" width="500" />
- **Regular checkpoints** are created before file modifications, allowing easy undo of any changes
<img src="/img/checkpoints/checkpoints-2.png" alt="Regular checkpoint indicator in chat" width="500" />
Each checkpoint provides two primary functions that are always available in both the chat history and checkpoint menu:
### Viewing Differences
To compare your current workspace with a previous checkpoint:
1. Locate the checkpoint in your chat history or open the checkpoint menu
2. Click the checkpoint's `View Differences` button
<img src="/img/checkpoints/checkpoints-6.png" alt="View Differences button interface" width="100" />
3. Review the differences in the comparison view:
- Added lines are highlighted in green
- Removed lines are highlighted in red
- Modified files are listed with detailed changes
- Renames may not always be detected; diffs reflect per-file changes between commits
- New or deleted files are clearly marked
<img src="/img/checkpoints/checkpoints-3.png" alt="View differences option for checkpoints" width="800" />
### Restoring Checkpoints
Restore options are always visible in checkpoint buttons and dialogs, regardless of whether changes are detected. This ensures you can always revert to any checkpoint state.
To restore a project to a previous checkpoint state:
1. Locate the checkpoint in your chat history or checkpoint menu
2. Click the checkpoint's `Restore Checkpoint` button (always visible)
<img src="/img/checkpoints/checkpoints-7.png" alt="Restore checkpoint button interface" width="100" />
3. Choose one of these restoration options:
<img src="/img/checkpoints/checkpoints-4.png" alt="Restore checkpoint option" width="300" />
- **Restore Files Only** - Reverts only workspace files to checkpoint state without modifying conversation history. Ideal for comparing alternative implementations while maintaining chat context, allowing you to seamlessly switch between different project states. This option does not require confirmation and lets you quickly switch between different implementations.
- **Restore Files & Task** - Reverts both workspace files AND removes all subsequent conversation messages. Use when you want to completely reset both your code and conversation back to the checkpoint's point in time. This option requires confirmation in a dialog as it cannot be undone.
<img src="/img/checkpoints/checkpoints-9.png" alt="Confirmation dialog for restoring checkpoint with files & task" width="300" />
### Limitations and Considerations
- **Scope**: Checkpoints only capture changes made during active Roo Code tasks
- **External changes**: Modifications made outside of tasks (manual edits, other tools) aren't included
- **Large files**: Very large binary files may impact performance
- **Unsaved work**: Restoration will overwrite any unsaved changes in your workspace
- **Timing**: Checkpoints are created before changes are applied, providing a safety net for all modifications
---
## Technical Implementation
### Checkpoint Architecture
The checkpoint system consists of:
1. **Shadow Git Repository**: A separate Git repository created specifically for checkpoint tracking that functions as the persistent storage mechanism for checkpoint state.
2. **Checkpoint Service**: Handles Git operations and state management through:
- Repository initialization
- Checkpoint creation and storage
- Diff computation
- State restoration
3. **UI Components**: Interface elements displayed in the chat that enable interaction with checkpoints.
### Restoration Process
When restoration executes, Roo Code:
- Performs a hard reset to the specified checkpoint commit
- Copies all files from the shadow repository to your workspace
- Updates internal checkpoint tracking state
### Storage Type
Checkpoints are task-scoped, meaning they are specific to a single task.
### Diff Computation
Checkpoint comparison uses Git's underlying diff capabilities to produce structured file differences:
- Modified files show line-by-line changes
- Binary files are properly detected and handled
- Rename detection may be limited; diffs focus on file content changes between checkpoints
- File creation and deletion are clearly identified
### File Exclusion and Ignore Patterns
The checkpoint system uses intelligent file exclusion to track only relevant files:
#### Built-in Exclusions
The system has comprehensive built-in exclusion patterns that automatically ignore:
- Build artifacts and dependency directories (`node_modules/`, `dist/`, `build/`)
- Media files and binary assets (images, videos, audio)
- Cache and temporary files (`.cache/`, `.tmp/`, `.bak`)
- Configuration files with sensitive information (`.env`)
- Large data files (archives, executables, binaries)
- Database files and logs
These patterns are written to the shadow repository's `.git/info/exclude` file during initialization.
#### .gitignore Support
The checkpoint system respects `.gitignore` patterns in your workspace:
- Files excluded by `.gitignore` won't trigger checkpoint creation
- Excluded files won't appear in checkpoint diffs
- Standard Git ignore rules apply when staging file changes
#### Git LFS Patterns
Patterns defined in your workspace's `.gitattributes` for Git LFS are read and added to checkpoint exclusions. This helps avoid tracking large LFS-managed assets in the shadow repository.
#### .rooignore Behavior
The `.rooignore` file (which controls AI access to files) is separate from checkpoint tracking:
- Files excluded by `.rooignore` but not by `.gitignore` will still be checkpointed
- Changes to AI-inaccessible files can still be restored through checkpoints
This separation is intentional, as `.rooignore` limits which files the AI can access, not which files should be tracked for version history.
#### Nested Git Repositories
If nested Git repositories are detected in your workspace, checkpoints are disabled. You'll receive a clear notification when checkpoint initialization fails due to nested repositories. Remove or relocate nested repositories to enable checkpoints.
### Concurrency Control
The extension prevents duplicate checkpointing within a single streaming operation. There is no dedicated Git operation queue.
---
## Git Installation
Checkpoints require Git to be installed on your system. The implementation uses the `simple-git` library, which relies on Git command-line tools to create and manage shadow repositories.
### macOS
1. **Install with Homebrew (recommended)**:
```
brew install git
```
2. **Alternative: Install with Xcode Command Line Tools**:
```
xcode-select --install
```
3. **Verify installation**:
- Open Terminal
- Type `git --version`
- You should see a version number like `git version 2.40.0`
### Windows
1. **Download Git for Windows**:
- Visit https://git-scm.com/download/win
- The download should start automatically
2. **Run the installer**:
- Accept the license agreement
- Choose installation location (default is recommended)
- Select components (default options are typically sufficient)
- Choose the default editor
- Choose how to use Git from the command line (recommended: Git from the command line and also from 3rd-party software)
- Configure line ending conversions (recommended: Checkout Windows-style, commit Unix-style)
- Complete the installation
3. **Verify installation**:
- Open Command Prompt or PowerShell
- Type `git --version`
- You should see a version number like `git version 2.40.0.windows.1`
### Linux
**Debian/Ubuntu**:
```
sudo apt update
sudo apt install git
```
**Fedora**:
```
sudo dnf install git
```
**Arch Linux**:
```
sudo pacman -S git
```
**Verify installation**:
- Open Terminal
- Type `git --version`
- You should see a version number

178
apps/docs/docs/features/code-actions.mdx Normal file
View file

@ -0,0 +1,178 @@
---
description: Access Roo Code's AI assistance directly in your editor with Code Actions. Get instant fixes, explanations, and improvements through VSCode's lightbulb system.
keywords:
- code actions
- quick fixes
- lightbulb menu
- AI assistance
- VSCode integration
- code improvements
- error fixes
---
# Code Actions
Code Actions provide instant access to Roo Code's AI assistance directly within your code editor through VSCode's lightbulb (quick fix) system. This context-aware feature automatically detects relevant code situations and offers appropriate AI-powered actions without requiring you to switch to the chat interface.
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/_Op3VfLPEu8?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
<div style={{ marginTop: '20px' }}></div>
---
## What are Code Actions?
Code Actions appear as a lightbulb icon (💡) in the editor gutter (the area to the left of the line numbers). They can also be accessed via the right-click context menu, or via keyboard shortcut. They are triggered when:
* You select a range of code.
* Your cursor is on a line with a problem (error, warning, or hint).
* You invoke them via command.
Clicking the lightbulb, right-clicking and selecting "Roo Code", or using the keyboard shortcut (`Ctrl+.` or `Cmd+.` on macOS, by default), displays a menu of available actions.
---
## Roo Code's Code Actions
Roo Code provides 5 code actions, though their availability varies by context:
### Context Menu Actions (Right-Click)
* **Add to Context:** Quickly adds the selected code to your chat with Roo, including the filename and line numbers so Roo knows exactly where the code is from. It's listed first in the menu for easy access.
* **Explain Code:** Asks Roo Code to explain the selected code.
* **Improve Code:** Asks Roo Code to suggest improvements to the selected code.
### Additional Actions
* **Fix Code:** Available through the lightbulb menu and command palette (but not the right-click menu). Asks Roo Code to fix problems in the selected code.
* **New Task:** Creates a new task with the selected code. Available through the command palette.
### Context-Aware Actions
The lightbulb menu intelligently shows different actions based on your code's current state:
**For Code with Problems** (when VSCode shows red/yellow squiggles):
- **Fix Code** - Get step-by-step guidance to resolve the specific error or warning
- **Add to Context** - Add the problematic code to Roo's context for discussion
**For Clean Code** (no diagnostics):
- **Explain Code** - Get detailed explanations of what the code does
- **Improve Code** - Receive optimization suggestions and best practices
- **Add to Context** - Add the code to Roo's context for further work
For more details on how diagnostics are integrated with Code Actions, see [Diagnostics Integration](/features/diagnostics-integration).
### Add to Context Deep Dive
The **Add to Context** action is listed first in the Code Actions menu so you can quickly add code snippets to your conversation. When you use it, Roo Code includes the filename and line numbers along with the code.
This helps Roo understand the exact context of your code within the project, allowing it to provide more relevant and accurate assistance.
Tip: Use macOS Cmd+K Cmd+A or Windows/Linux Ctrl+K Ctrl+A to add the selection to context quickly. See [Keyboard Shortcuts](/features/keyboard-shortcuts).
**Example Chat Input:**
```
Can you explain this function?
@myFile.js:15:25
```
*(Where `@myFile.js:15:25` represents the code added via "Add to Context")*
---
## Using Code Actions
There are three main ways to use Roo Code's Code Actions:
### 1. From the Lightbulb (💡)
1. **Select Code:** Select the code you want to work with. You can select a single line, multiple lines, or an entire block of code.
2. **Look for the Lightbulb:** A lightbulb icon will appear in the gutter next to the selected code (or the line with the error/warning).
3. **Click the Lightbulb:** Click the lightbulb icon to open the Code Actions menu.
4. **Choose an Action:** Select the desired Roo Code action from the menu.
5. **Review and Approve:** Roo Code will propose a solution in the chat panel. Review the proposed changes and approve or reject them.
### 2. From the Right-Click Context Menu
1. **Select Code:** Select the code you want to work with.
2. **Right-Click:** Right-click on the selected code to open the context menu.
3. **Choose "Roo Code":** Select the "Roo Code" option from the context menu. A submenu will appear with the available Roo Code actions.
4. **Choose an Action:** Select the desired action from the submenu.
5. **Review and Approve:** Roo Code will propose a solution in the chat panel. Review the proposed changes and approve or reject them.
### 3. From the Command Palette
1. **Select Code:** Select the code you want to work with.
2. **Open the Command Palette:** Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS).
3. **Type a Command:** Type "Roo Code" to filter the commands, then choose the relevant code action (e.g., "Roo Code: Explain Code"). The action will apply in the most logical context (usually the current active chat task, if one exists).
4. **Review and Approve:** Roo Code will propose a solution in the chat panel. Review the proposed changes and approve or reject them.
---
## Terminal Actions
Roo Code also provides similar actions for terminal output:
* **Terminal: Add to Context:** Adds selected terminal output to your chat
* **Terminal: Fix Command:** Asks Roo Code to fix a failed terminal command
* **Terminal: Explain Command:** Asks Roo Code to explain terminal output or commands
These actions are available when you select text in the terminal and right-click.
---
## Disabling/Enabling Code Actions
You can control Code Actions through VSCode settings:
### Enable/Disable Code Actions
- **Setting**: [`roo-cline.enableCodeActions`](vscode://settings/roo-cline.enableCodeActions)
- **Default**: Enabled
- **Description**: Controls whether Roo Code quick fix options appear in the editor
To access this setting:
1. Open VSCode Settings (`Ctrl/Cmd + ,`)
2. Search for "enableCodeActions"
3. Toggle the checkbox to enable or disable
---
## Customizing Code Action Prompts
You can customize the prompts used for each Code Action by modifying the "Support Prompts" in the **Prompts** tab. This allows you to fine-tune the instructions given to the AI model and tailor the responses to your specific needs.
1. **Open the Prompts Tab:** Click the <Codicon name="notebook" /> icon in the Roo Code top menu bar.
2. **Find "Support Prompts":** You will see the support prompts, including "Enhance Prompt", "Explain Code", "Improve Code", and "Fix Code".
3. **Edit the Prompts:** Modify the text in the text area for the prompt you want to customize. The prompts use placeholders in the format `${placeholder}`:
- `${filePath}` - The path of the current file
- `${selectedText}` - The currently selected text
- `${diagnostics}` - Any error or warning messages (for Fix Code) - see [Diagnostics Integration](/features/diagnostics-integration) for details
4. **Click "Done":** Save your changes.
### Example Prompt Template
```
Please explain the following code from ${filePath}:
${selectedText}
```
By using Roo Code's Code Actions, you can quickly get AI-powered assistance directly within your coding workflow. This can save you time and help you write better code.
---
## Related Features
- [Diagnostics Integration](/features/diagnostics-integration) - Learn how Roo Code integrates with VSCode's Problems panel
- [Context Mentions](/basic-usage/context-mentions) - Discover other ways to provide context to Roo Code

367
apps/docs/docs/features/codebase-indexing.mdx Normal file
View file

@ -0,0 +1,367 @@
---
description: Learn how Codebase Indexing helps Roo Code understand large projects using AI embeddings and semantic search. Setup guide for OpenAI and Qdrant integration.
keywords:
- codebase indexing
- semantic search
- AI embeddings
- OpenAI
- Qdrant
- large projects
- code search
---
import Codicon from '@site/src/components/Codicon';
# Codebase Indexing
Codebase Indexing transforms how Roo Code understands your project by creating a semantic search index using AI embeddings. Instead of searching for exact text matches, it understands the *meaning* of your queries, helping Roo find relevant code even when you don't know specific function names or file locations.
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/r1bpod1VWhg?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
title="Codebase Indexing Setup Tutorial"
></iframe>
</div>
<br />
---
## What It Does
When enabled, the indexing system:
1. **Parses your code** using Tree-sitter to identify semantic blocks (functions, classes, methods)
2. **Creates embeddings** of each code block using AI models
3. **Stores vectors** in a Qdrant database for fast similarity search
4. **Provides the [`codebase_search`](/advanced-usage/available-tools/codebase-search) tool** to Roo for intelligent code discovery
This enables natural language queries like "user authentication logic" or "database connection handling" to find relevant code across your entire project.
---
## Quick Start Guide
:::tip 💰 Completely Free Setup Available
You can set up codebase indexing at **zero cost** by using:
- **Qdrant Cloud** (free tier) or **Docker Qdrant** (completely free)
- **Google Gemini** (currently free)
This gives you professional-grade semantic search without any subscription fees!
:::
### Step 1: Choose Your Setup
Before enabling codebase indexing, you'll need two components:
1. **An Embedding Provider** - to convert code into searchable vectors
2. **A Vector Database** - to store and search those vectors
### Step 2: Set Up Qdrant (Vector Database)
#### Option A: Cloud Setup (Recommended for Getting Started) - **FREE**
1. Sign up at [Qdrant Cloud](https://cloud.qdrant.io/) (free tier available)
2. Create a cluster
3. Copy your URL and API key
#### Option B: Local Setup - **FREE**
Using Docker:
```bash
docker run -d \
--name qdrant \
--restart unless-stopped \
-p 6333:6333 \
-v qdrant_data:/qdrant/storage \
qdrant/qdrant
```
Using Docker Compose:
```yaml
services:
qdrant:
image: qdrant/qdrant
ports:
- "6333:6333"
volumes:
- qdrant_storage:/qdrant/storage
volumes:
qdrant_storage:
```
### Step 3: Set Up an Embedding Provider
#### Google Gemini Setup (Recommended) - **FREE**
1. Get an API key from [Google AI Studio](https://aistudio.google.com/apikey) (currently free)
2. In Roo Code settings:
- Provider: **Google Gemini**
- API Key: Your Google AI Studio key
:::info Other Providers Available
While this guide focuses on Google Gemini since it's currently free, Roo Code also supports OpenAI, Ollama, OpenAI-compatible, Mistral, Vercel AI Gateway, Bedrock, and OpenRouter providers. You can explore these options in the configuration dropdown.
:::
### Step 4: Save
1. Click **Save** and **Start Indexing**
The status indicator will show:
- **Yellow (Indexing)**: Currently processing files
- **Green (Indexed)**: Ready for searches
- **Red (Error)**: Check troubleshooting section
---
## Managing and Configuring the Indexer
You can monitor the status and manage all configuration for the codebase indexer directly from the Roo Code chat interface.
### The Status Icon
At the bottom-right corner of the chat input, you'll find the **Codebase Indexing status icon**. This icon provides a quick, at-a-glance overview of the indexer's current state.
<img src="/img/codebase-indexing/codebase-indexing-1.png" alt="Codebase Indexing Status Icon" />
The color of the icon indicates the state:
- 🟢 **Green**: **Indexed**. The index is up-to-date and ready for search.
- 🟡 **Yellow**: **Indexing**. The system is actively processing files. Searches can still be performed, but results may be incomplete.
- 🔴 **Red**: **Error**. An issue has occurred (e.g., failed to connect to Qdrant or the embedding provider). See the Troubleshooting section for help.
- ⚪ **Gray**: **Standby**. The indexer is waiting for configuration or has been disabled.
**Multi-Folder Workspaces**: In multi-folder workspaces, each folder maintains its own indexing status and configuration. The status icon reflects the combined state of all workspace folders.
### The Configuration Popover
Clicking the status icon opens the main configuration popover. Here, you can view the detailed status and manage all settings.
<img src="/img/codebase-indexing/codebase-indexing-2.png" alt="Codebase Indexing Popover" />
- **Status**: A detailed message showing the current state, such as "Indexed - File watcher started" or the progress of an ongoing scan.
- **Setup**: Contains the primary fields for connecting to your embedding provider and vector database.
- **Advanced Configuration**: Allows you to fine-tune search parameters like the similarity threshold.
- **Clear Index Data**: Deletes all data from the Qdrant collection and clears the local file cache. Use this when you want to re-index your entire project from scratch. **This action cannot be undone.**
- **Save**: Applies your configuration changes. If a critical setting (like an API key or a model) is changed, the indexer will automatically restart.
### Detailed Configuration Fields
This guide explains each setting available in the configuration popover.
<img src="/img/codebase-indexing/codebase-indexing-3.png" alt="Codebase Indexing Configuration Details" />
#### **Setup Fields**
- **Embedder Provider**
- **Purpose**: To select your source for generating AI embeddings.
- **Behavior**: This dropdown menu determines which configuration fields are shown. Your options are **OpenAI**, **Google Gemini**, **Ollama**, **OpenAI Compatible**, **Mistral**, **Vercel AI Gateway**, **Bedrock**, and **OpenRouter**.
- **API Key** (for OpenAI, Gemini, OpenAI Compatible)
- **Purpose**: The secret key to authenticate with your chosen provider.
- **Behavior**: This input is required for all cloud-based providers and is stored securely in your VS Code secret storage.
- **Base URL** (for Ollama, OpenAI Compatible)
- **Purpose**: The endpoint for connecting to the provider's API.
- **Behavior**: For **Ollama**, this is typically `http://localhost:11434`. For **OpenAI Compatible** providers like Azure, this is the full deployment URL.
- **Model**
- **Purpose**: To select the specific embedding model you want to use.
- **Behavior**: The list of available models changes based on the selected provider. The model's vector dimension (e.g., `1536 dimensions`) is displayed, as changing dimensions requires a full re-index.
- **Qdrant URL**
- **Purpose**: The connection endpoint for your Qdrant vector database.
- **Behavior**: This must be a valid URL pointing to your local or cloud-based Qdrant instance (e.g., `http://localhost:6333`).
- **Qdrant API Key**
- **Purpose**: The authentication key for a secured Qdrant instance.
- **Behavior**: This field is optional and should only be used if your Qdrant deployment requires an API key.
#### **Advanced Configuration Fields**
- **Search Score Threshold**
- **Purpose**: Controls the minimum similarity score required for a code snippet to be considered a match.
- **Behavior**: Use the slider to set a value between 0.0 and 1.0. A lower value returns more (but potentially less relevant) results, while a higher value returns fewer, more precise results.
- **Recommended Settings**:
- **Low (0.15-0.3)**: Broader results, good for exploration
- **Medium (0.4-0.5)**: Balanced precision and recall (default: 0.4)
- **High (0.6-0.8)**: Precise matches only
- **Maximum Search Results**
- **Purpose**: Sets the maximum number of code snippets returned by a single `codebase_search`.
- **Behavior**: Use the slider to adjust the limit. This helps control the amount of context provided to the AI.
---
## Key Benefits
- **Semantic Search**: Find code by meaning, not just keywords
- **Enhanced AI Understanding**: Roo can better comprehend and work with your codebase
- **Cross-Project Discovery**: Search across all files, not just what's open
- **Pattern Recognition**: Locate similar implementations and code patterns
---
## How Files Are Processed
### Smart Code Parsing
The system uses a sophisticated parsing strategy:
1. **Tree-sitter First**: For supported languages, it uses AST parsing to identify semantic code blocks (functions, classes, methods)
2. **Markdown Support**: Indexes Markdown files by treating headers as semantic entry points
3. **Intelligent Fallback**: For unsupported file types, it falls back to line-based chunking
**Block Sizing**:
- Minimum: 100 characters
- Maximum: 1,000 characters
- Large functions are split intelligently at logical boundaries
### File Filtering
The indexer respects your project's ignore patterns:
- Files matching `.gitignore` patterns
- Files matching `.rooignore` patterns
- Binary files and images
- Files larger than 1MB
**Important**: Ensure your `.gitignore` includes common dependency folders like `node_modules`, `vendor`, `target`, etc., as the system relies exclusively on these patterns for filtering.
### Incremental Updates
- **File Watching**: Monitors your workspace for changes in real-time
- **Smart Updates**: Only reprocesses modified files
- **Branch Aware**: Automatically handles Git branch switches
- **Hash-based Caching**: Avoids reprocessing unchanged content
- **Multi-Folder Workspaces**: Each folder in a multi-folder workspace maintains its own index with separate settings and status
---
## Best Practices
### Writing Effective Queries
Instead of searching for exact syntax:
- ❌ `const getUser`
- ✅ `function to fetch user from database`
Use natural language descriptions:
- "authentication middleware"
- "error handling for API requests"
- "database connection setup"
### Security Considerations
- **API Keys**: Stored securely in VS Code's encrypted storage
- **Code Privacy**: Only small code snippets sent for embedding
- **Local Processing**: All parsing happens locally
- **Access Control**: Respects file permissions and ignore patterns
---
## Troubleshooting
### Connection Issues
**"Connection to Qdrant failed"**
- Ensure Qdrant is running (`docker ps` to check)
- Verify URL matches (default: `http://localhost:6333`)
- Check firewall/network policies
- For cloud instances, confirm URL and API key
**"Invalid API Key" or "401 Unauthorized"**
- Double-check your API key is correct
- Ensure the key has necessary permissions
- For Ollama, verify the service is running
### API Key Format Errors (“ByteString conversion”)
- Symptom: Error mentions "ByteString conversion" during indexing or when saving settings
- Likely cause: Your embedding provider API key contains invalid/special characters or hidden whitespace
- Fix:
- Regenerate a fresh API key from your provider dashboard
- Paste the key again, ensuring no leading/trailing spaces or hidden characters
- Roo will display a clear validation message if the key is invalid
### Model Issues
**"Model Not Found"**
- For Google Gemini: Ensure the model name is correct (e.g., `gemini-embedding-001`)
- For other providers: Consult their documentation for available models and proper naming
### Indexing Issues
**"Stuck in Error State"**
1. Check connection issues first
2. Click "Clear Index & Re-index" in settings
3. This resolves corrupted cache or collection issues
**"Indexing Taking Too Long"**
- Normal for large codebases (10k+ files)
- Check `.gitignore` includes large directories
- Consider adding patterns to `.rooignore`
---
## Using the Search Feature
Once indexed, Roo can use the [`codebase_search`](/advanced-usage/available-tools/codebase-search) tool:
**Example Natural Language Queries**:
- "How is user authentication handled?"
- "Database connection setup"
- "Error handling patterns"
- "API endpoint definitions"
- "Component state management"
The tool provides:
- Relevant code snippets
- File paths with line numbers
- Similarity scores
- Direct navigation links
---
## Privacy & Data Security
**Your code stays private**:
- Only small code chunks (100-1000 chars) sent for embedding
- Embeddings are one-way mathematical representations
- Local parsing means full files never leave your machine
- Use Ollama for completely offline operation
**Data Storage**:
- Vectors stored in your chosen Qdrant instance
- You control where data lives (local/cloud)
- Easy to delete: just clear the index
---
## Current Limitations
- **File Size**: 1MB maximum per file
- **External Dependencies**: Requires embedding provider + Qdrant
- **Language Support**: Best results with Tree-sitter supported languages
---
## Future Enhancements
Planned improvements:
- Additional embedding providers
- Multi-workspace indexing
- Enhanced filtering options
- Team collaboration features
- VS Code native search integration
- Incremental re-indexing optimizations

78
apps/docs/docs/features/concurrent-file-reads.md Normal file
View file

@ -0,0 +1,78 @@
---
description: Learn how Roo Code's Concurrent File Reads feature speeds up development by reading up to 100 files simultaneously for better context understanding.
keywords:
- concurrent file reads
- multi-file reads
- batch file reading
- context loading
- workspace efficiency
- file operations
sidebar_label: "Multi-File Reads"
---
# Concurrent File Reads (AKA Multi-File Reads)
The Concurrent File Reads feature allows Roo to read multiple files from your workspace in a single step. This significantly improves efficiency when working on tasks that require context from several files, as Roo can gather all the necessary information at once instead of reading files one by one.
### Key Features
- Read up to 100 files in a single request.
- Enabled by default for a faster, more streamlined workflow.
- Configurable limit from 1 to 100 files (setting to 1 effectively disables concurrent reads).
---
## Benefits
- **Increased Speed**: Reduces the time it takes for Roo to understand your code by minimizing the number of back-and-forth steps.
- **Better Context**: Allows Roo to build a more complete mental model of your code, leading to more accurate and relevant responses.
- **Improved Workflow**: Streamlines tasks that require information from multiple files, making you more productive.
---
## Why This Matters
**Faster Context Building**: Previously, when Roo needed to understand your project, you'd see multiple requests like:
- "Can I read `src/app.js`?" → You approve
- "Now can I read `src/utils.js`?" → You approve
- "And can I read `src/config.json`?" → You approve
**With concurrent file reads**: Roo asks once to read all related files together, getting the full picture immediately and providing better assistance faster.
---
## How it Works
When you ask Roo to perform a task that involves multiple files, it will automatically identify the relevant files and read them together. This is especially useful for:
- Understanding the overall structure of a component that is split across multiple files.
- Refactoring code that has dependencies in other parts of the codebase.
- Answering questions that require a broad understanding of your project.
Roo is instructed to use this feature efficiently by prioritizing the most critical files and reading them in a single batch. The [`read_file`](/advanced-usage/available-tools/read-file) tool automatically accepts multiple files in a single request.
When Roo requests to read multiple files, you'll see a batch approval interface that displays:
- List of all files to be read
- File paths with line range indicators (if specified)
- Clickable file headers to open files in your editor
- **Approve All** and **Deny All** buttons for quick decisions
<img src="/img/concurrent-file-reads/concurrent-file-reads-2.png" alt="Batch approval interface for reading multiple files" width="600" />
---
## Configuration
You can configure the Multi-File Read feature by clicking the <Codicon name="gear" /> icon and navigating to the "Context" section of the settings.
<img src="/img/concurrent-file-reads/concurrent-file-reads-1.png" alt="Concurrent file reads settings showing limit slider" width="600" />
1. **Concurrent File Reads Limit**:
- **Setting**: `Concurrent file reads limit`
- **Description**: This setting determines the maximum number of files that Roo can read in a single request. The default is 5, with a range of 1-100 files. Higher values can speed up tasks involving many small files but may use more memory. Setting the value to 1 effectively disables concurrent reads, reverting to single-file reads.
:::note
The per‑request file limit is configured in the UI (default 5, up to 100). The backend [`read_file`](/advanced-usage/available-tools/read-file) tool doesn’t hard‑enforce a cap; actual behavior may also depend on the selected model/tool.
:::

344
apps/docs/docs/features/custom-instructions.md Normal file
View file

@ -0,0 +1,344 @@
---
description: Learn how to use custom instructions to tailor Roo Code's behavior to your preferences, coding style, and project requirements.
keywords:
- custom instructions
- personalization
- AI customization
- coding preferences
- project rules
---
# Custom Instructions
Custom Instructions allow you to personalize how Roo behaves, providing specific guidance that shapes responses, coding style, and decision-making processes.
:::info Instruction File Locations
You can provide custom instructions using global rules (applied across all projects), workspace rules (project-specific), or through the Prompts tab interface.
**Global Rules Directory:** Apply to all projects automatically.
- **Linux/macOS:** `~/.roo/rules/` and `~/.roo/rules-{modeSlug}/`
- **Windows:** `%USERPROFILE%\.roo\rules\` and `%USERPROFILE%\.roo\rules-{modeSlug}\`
**Workspace Rules:** Apply only to the current project and take precedence over global rules when they conflict.
- **Preferred Method: Directory (`.roo/rules/`)**
```
.
├── .roo/
│ └── rules/ # Workspace-wide rules
│ ├── 01-general.md
│ └── 02-coding-style.txt
└── ... (other project files)
```
- **Fallback Method: Single File (`.roorules`)**
```
.
├── .roorules # Workspace-wide rules (single file)
└── ... (other project files)
```
**Mode-Specific Instructions:** Apply only to a specific mode (e.g., `code`).
- **Preferred Method: Directory (`.roo/rules-{modeSlug}/`)**
```
.
├── .roo/
│ └── rules-code/ # Rules for "code" mode
│ ├── 01-js-style.md
│ └── 02-ts-style.md
└── ... (other project files)
```
- **Fallback Method: Single File (`.roorules-{modeSlug}`)**
```
.
├── .roorules-code # Rules for "code" mode (single file)
└── ... (other project files)
```
Rules are loaded in order: Global rules first, then workspace rules. If there's a conflict, workspace rules take precedence. See [Global Rules Directory](#global-rules-directory) for details.
:::
---
## What Are Custom Instructions?
Custom Instructions define specific behaviors, preferences, and constraints beyond Roo's basic role definition. Examples include coding style, documentation standards, testing requirements, and workflow guidelines.
---
## Setting Custom Instructions
### Global Custom Instructions
These instructions apply across all workspaces and maintain your preferences regardless of which project you're working on.
**How to set them:**
<img src="/img/custom-instructions/custom-instructions.png" alt="Roo Code Prompts tab showing global custom instructions interface" width="600" />
1. **Open Prompts Tab:** Click the <Codicon name="notebook" /> icon in the Roo Code top menu bar
2. **Find Section:** Find the "Custom Instructions for All Modes" section
3. **Enter Instructions:** Enter your instructions in the text area
4. **Save Changes:** Click "Done" to save your changes
### Global Rules Directory
The Global Rules Directory feature provides reusable rules and custom instructions that automatically apply across all your projects. This system supports both global configurations and project-specific overrides.
#### Key Benefits
**Without Global Rules**: You had to maintain separate rule files in each project:
- Copy the same rules to every new project
- Update rules manually across multiple projects
- No consistency between projects
**With Global Rules**: Create rules once and use them everywhere:
- Set up your preferred coding standards globally
- Customize specific rules per project when needed
- Maintain consistency across all your work
- Easy to update rules for all projects at once
#### Directory Structure
The global rules directory location is fixed and cannot be customized:
**Linux/macOS:**
```
~/.roo/ # Your global Roo configuration
├── rules/ # General rules applied to all projects
│ ├── coding-standards.md
│ ├── formatting-rules.md
│ └── security-guidelines.md
├── rules-code/ # Rules specific to Code mode
│ ├── typescript-rules.md
│ └── testing-requirements.md
├── rules-docs-extractor/ # Rules for documentation extraction
│ └── documentation-style.md
└── rules-{mode}/ # Rules for other specific modes
└── mode-specific-rules.md
```
**Windows:**
```
%USERPROFILE%\.roo\ # Your global Roo configuration
├── rules\ # General rules applied to all projects
│ ├── coding-standards.md
│ ├── formatting-rules.md
│ └── security-guidelines.md
├── rules-code\ # Rules specific to Code mode
│ ├── typescript-rules.md
│ └── testing-requirements.md
└── rules-{mode}\ # Rules for other specific modes
└── mode-specific-rules.md
```
#### Setting Up Global Rules
1. **Create Global Rules Directory:**
```bash
# Linux/macOS
mkdir -p ~/.roo/rules
# Windows
mkdir %USERPROFILE%\.roo\rules
```
2. **Add General Rules** (`~/.roo/rules/coding-standards.md`):
```markdown
# Global Coding Standards
1. Always use TypeScript for new projects
2. Write unit tests for all new functions
3. Use descriptive variable names
4. Add JSDoc comments for public APIs
```
3. **Add Mode-Specific Rules** (`~/.roo/rules-code/typescript-rules.md`):
```markdown
# TypeScript Code Mode Rules
1. Use strict mode in tsconfig.json
2. Prefer interfaces over type aliases for object shapes
3. Always specify return types for functions
```
#### Available Rule Directories
| Directory | Purpose |
| ----------------------- | ----------------------------------- |
| `rules/` | General rules applied to all modes |
| `rules-code/` | Rules specific to Code mode |
| `rules-docs-extractor/` | Rules for documentation extraction |
| `rules-architect/` | Rules for system architecture tasks |
| `rules-debug/` | Rules for debugging workflows |
| `rules-{mode}/` | Rules for any custom mode |
#### Rule Loading Order
Rules are loaded in this order:
1. **Global Rules** (from `~/.roo/`)
2. **Project Rules** (from `project/.roo/`) - take precedence over global rules when they conflict
3. [Generic only] **Legacy Files** (workspace root `.roorules`, `.clinerules`) - used only if no generic rules directory content was loaded
Within each level, mode-specific rules are loaded before general rules.
### Workspace-Level Instructions
These instructions only apply within your current workspace, allowing you to customize Roo Code's behavior for specific projects.
#### Workspace-Wide Instructions via Files/Directories
Workspace-wide instructions apply to all modes within the current project and can be defined using files:
- **Preferred Method: Directory-Based (`.roo/rules/`)**
- Create a directory named `.roo/rules/` in your workspace root.
- Place instruction files (e.g., `.md`, `.txt`) inside. Roo Code reads files recursively (including subdirectories), appending their content to the system prompt in **alphabetical order** based on filename.
- When this directory exists and contains files, its contents are loaded along with any global rules directories.
- Note: If the `.roo/rules/` directory exists but is empty, Roo Code will fall back to using the `.roorules` file instead.
- **Fallback Method: File-Based (`.roorules`)**
- If `.roo/rules/` doesn't exist or is empty, Roo Code looks for a single `.roorules` file in the workspace root.
- If found, its content is loaded.
#### Mode-Specific Instructions
Mode-specific instructions can be set in two independent ways that can be used simultaneously:
1. **Using the Prompts Tab:**
<img src="/img/custom-instructions/custom-instructions-2.png" alt="Roo Code Prompts tab showing mode-specific custom instructions interface" width="600" />
* **Open Tab:** Click the <Codicon name="notebook" /> icon in the Roo Code top menu bar
* **Select Mode:** Under the Modes heading, click the button for the mode you want to customize
* **Enter Instructions:** Enter your instructions in the text area under "Mode-specific Custom Instructions (optional)"
* **Save Changes:** Click "Done" to save your changes
:::info Global Mode Rules
If the mode itself is global (not workspace-specific), any custom instructions you set for it will also apply globally for that mode across all workspaces.
:::
2. **Using Rule Files/Directories:** Provide mode-specific instructions via files:
- **Preferred Method: Directory-Based (`.roo/rules-{modeSlug}/`)**
- Create a directory named `.roo/rules-{modeSlug}/` (e.g., `.roo/rules-docs-writer/`) in your workspace root.
- Place instruction files inside (recursive loading, including subdirectories). Files are read and appended to the system prompt in **alphabetical order** by filename.
- This method takes precedence over the fallback file method for the specific mode if the directory exists and contains files.
- **Fallback Method: File-Based (`.roorules-{modeSlug}`)**
- If `.roo/rules-{modeSlug}/` doesn't exist or is empty, Roo Code looks for a single `.roorules-{modeSlug}` file (e.g., `.roorules-code`) in the workspace root.
- If found, its content is loaded for that mode.
Instructions from the Prompts tab, global rules, workspace rules, and mode-specific rules are all combined. See the section below for the exact order.
---
## How Instructions are Combined
Instructions are placed in the system prompt in this exact format:
```
====
USER'S CUSTOM INSTRUCTIONS
The following additional instructions are provided by the user, and should be followed to the best of your ability without interfering with the TOOL USE guidelines.
Language Preference:
[Language preference if set]
Global Instructions:
[Global Instructions from Prompts Tab]
Mode-specific Instructions:
[Mode-specific Instructions from Prompts Tab for the current mode]
Rules:
# Rules from rules-{modeSlug} directories:
[Contents of ALL files from ~/.roo/rules-{modeSlug}/ AND .roo/rules-{modeSlug}/ if they exist]
# Rules from .roorules-{modeSlug}:
[Contents of .roorules-{modeSlug} file if no mode-specific directories have files]
# Rules from .rooignore:
[.rooignore-related instructions if applicable]
# Agent Rules Standard (AGENTS.md):
[Contents of AGENTS.md or AGENT.md from workspace root if present and enabled]
# Rules from rules directories:
[Contents of ALL files from ~/.roo/rules/ AND .roo/rules/ if they exist]
# Rules from .roorules:
[Contents of .roorules file if no general rules directories have files]
====
```
_Note: The system loads rules from ALL applicable directories (both global `~/.roo/` and workspace `.roo/`), not just the first one with files. Mode-specific rules appear before general rules. Directory-based rules take precedence over file-based fallbacks only when determining which method to use, but all applicable directories are read._
---
## Rules about .rules files
- **File Location:** The preferred method uses directories within `.roo/` (`.roo/rules/` and `.roo/rules-{modeSlug}/`). The fallback method uses single files (`.roorules` and `.roorules-{modeSlug}`) located directly in the workspace root.
- **Recursive Reading:** Rules directories are read recursively, including all files in subdirectories
- **File Filtering:** System automatically excludes cache and temporary files (`.DS_Store`, `*.bak`, `*.cache`, `*.log`, `*.tmp`, `Thumbs.db`, etc.)
- **Empty Files:** Empty or missing rule files are silently skipped
- **Source Headers:** Directory-based rules include per-file headers `# Rules from {absolute path}:`, while file-based rules include `# Rules from {filename}:` headers
- **Aggregation:** Both global and workspace rules directories are aggregated for mode-specific and generic rules (not either-or)
- **Sorting:** Files are sorted by basename only, case-insensitive
- **Header Paths:** Header paths are absolute and follow symlinks
- **Rule Interaction:** Mode-specific rules complement global rules rather than replacing them
- **Symbolic Links:** Fully supported for both files and directories, with a maximum resolution depth of 5 to prevent infinite loops
---
## AGENTS.md Support
Roo Code also supports loading rules from an `AGENTS.md` (or `AGENT.md` as fallback) file in your workspace root:
- **Purpose:** Provides agent-specific rules and guidelines for AI behavior
- **Location:** Must be in the workspace root directory
- **Loading:** Automatically loaded by default. To disable AGENTS.md loading, set `"roo-cline.useAgentRules": false` in your VSCode settings
- **Setting:** `roo-cline.useAgentRules` (default: true)
- **Preference:** If both exist, `AGENTS.md` is preferred over `AGENT.md`
- **Priority:** Loaded after mode-specific rules and `.rooignore`, before generic rules from both `~/.roo/rules` and `.roo/rules`
- **Header:** Added to system prompt with header `# Agent Rules Standard (AGENTS.md):` or `(AGENT.md):` accordingly
- **Empty Files:** Empty or whitespace-only `AGENTS.md` is ignored
- **Symbolic Links:** Symbolic links to files or directories are resolved before reading
This feature allows teams to maintain standardized AI agent behavior rules that can be version-controlled alongside the project code.
---
## Examples of Custom Instructions
- "Always use spaces for indentation, with a width of 4 spaces"
- "Use camelCase for variable names"
- "Write unit tests for all new functions"
- "Explain your reasoning before providing code"
- "Focus on code readability and maintainability"
- "Prioritize using the most common library in the community"
- "When adding new features to websites, ensure they are responsive and accessible"
:::tip Pro Tip: Team Standardization
For team environments, consider these approaches:
**Project Standards**: Use workspace `.roo/rules/` directories under version control to standardize Roo's behavior for specific projects. This ensures consistent code style and development workflows across team members.
**Organization Standards**: Use global rules (`~/.roo/rules/`) to establish organization-wide coding standards that apply to all projects. Team members can set up identical global rules for consistency across all work.
**Hybrid Approach**: Combine global rules for organization standards with project-specific workspace rules for project-specific requirements. When rules conflict, workspace rules take precedence.
The directory-based approach offers better organization than single `.roorules` files and supports both global and project-level customization.
:::
---
## Combining with Custom Modes
For advanced customization, combine with [Custom Modes](/features/custom-modes) to create specialized environments with specific tool access, file restrictions, and tailored instructions.

663
apps/docs/docs/features/custom-modes.mdx Normal file
View file

@ -0,0 +1,663 @@
---
description: Learn how to create custom modes in Roo Code to tailor AI behavior for specific tasks. Configure tool access, file permissions, and specialized instructions.
keywords:
- custom modes
- Roo Code customization
- AI assistant configuration
- mode creation
- tool permissions
- file restrictions
---
# Customizing Modes
Roo Code allows you to create **custom modes** to tailor Roo's behavior to specific tasks or workflows. Custom modes can be either **global** (available across all projects) or **project-specific** (defined within a single project).
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/iiAv1eKOaxk?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
title="Custom Modes Overview Video"
></iframe>
</div>
<br />
:::tip Sticky Models for Efficient Workflow
Each mode—including custom ones—features **Sticky Models**. This means Roo Code automatically remembers and selects the last model you used with a particular mode. This lets you assign different preferred models to different tasks without constant reconfiguration, as Roo switches between models when you change modes.
:::
:::info Discover Community Modes
Looking for ready-to-use custom modes? Visit the [Roo Code Marketplace](/features/marketplace) to browse and install community-contributed modes with a single click. The marketplace offers specialized modes for various tasks like React development, documentation writing, testing, and more—all created and shared by the Roo Code community.
:::
---
## Why Use Custom Modes?
* **Specialization:** Create modes optimized for specific tasks, like "Documentation Writer," "Test Engineer," or "Refactoring Expert."
* **Safety:** Restrict a mode's access to sensitive files or commands. For example, a "Review Mode" could be limited to read-only operations.
* **Experimentation:** Safely experiment with different prompts and configurations without affecting other modes.
* **Team Collaboration:** Share custom modes with your team to standardize workflows.
<img src="/img/custom-modes/custom-modes-3.png" alt="Overview of custom modes interface" width="500" />
*Roo Code's interface for creating and managing custom modes.*
---
## What's Included in a Custom Mode?
Custom modes are defined by several key properties. Understanding these concepts will help you tailor Roo's behavior effectively.
| UI Field / YAML Property | Conceptual Description |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Slug (`slug`) | A **unique internal identifier** for the mode. It's used by Roo Code to reference the mode, especially for associating [mode-specific instruction files](#mode-specific-instructions-via-filesdirectories). |
| Name (`name`) | The **display name** for the mode as it appears in the Roo Code user interface. This should be human-readable and descriptive. |
| Description (`description`) | A **short, user-friendly summary** of the mode's purpose displayed in the mode selector UI.<br />- This text appears below the mode's name in the redesigned mode selector, offering users a quick understanding of the mode's function.<br />- Keep this concise and focused on what the mode does for the user. |
| Role Definition (`roleDefinition`) | Defines the **core identity and expertise** of the mode. This text is placed at the beginning of the system prompt.<br />- Its primary function is to define Roo's personality and behavior when this mode is active.<br />- With the introduction of the `description` field, the `roleDefinition` should provide a detailed description of the mode's identity, while the `description` field handles the short summary for the UI.<br />- The `whenToUse` property now takes precedence for summarization in automated contexts like task orchestration. |
| Available Tools (`groups`) | Defines the **allowed toolsets and file access permissions** for the mode.<br />- In the UI, this corresponds to selecting which general categories of tools (like reading files, editing files, browsing, or executing commands) the mode can use.<br />- The UI shows which files can be edited in the 'Allowed files' section under each mode.<br />- File type restrictions for the "edit" group are typically managed via manual YAML/JSON configuration or by asking Roo to set them up, as detailed in the [Property Details for `groups`](#groups). |
| When to Use (optional) (`whenToUse`) | (Optional) Provides **guidance for Roo's automated decision-making**, particularly for mode selection and task orchestration.<br />- This text is used by Roo, particularly the [`🪃 Orchestrator`](/basic-usage/using-modes#orchestrator-mode-aka-boomerang-mode) mode, for [orchestrating tasks](/features/boomerang-tasks) (e.g., via the [`new_task`](/advanced-usage/available-tools/new-task) tool).<br />- It also helps Roo decide which mode is appropriate when [switching modes](/basic-usage/using-modes#switching-between-modes) (e.g., via the [`switch_mode`](/advanced-usage/available-tools/switch-mode) tool).<br />- This field is **not displayed in the mode selector UI** - that's handled by the `description` field. |
| Custom Instructions (optional) (`customInstructions`) | **Specific behavioral guidelines** or rules for the mode.<br />- These instructions are added near the end of the system prompt to further refine Roo's behavior beyond the `roleDefinition`.<br />- This can be provided directly in the configuration or via separate instruction files. |
---
## Import/Export Modes
Easily share, back up, and template your custom modes. This feature lets you export any mode—and its associated rules—into a single, portable YAML file that you can import into any project.
### Key Features
- **Shareable Setups**: Package a mode and its rules into one file to easily share with your team.
- **Easy Backups**: Save your custom mode configurations so you never lose them.
- **Project Templates**: Create standardized mode templates for different types of projects.
- **Simple Migration**: Move modes between your global settings and specific projects effortlessly.
- **Flexible Slug Changes**: Change mode slugs in exported files without manual path editing.
---
### Use Case
**Before**: Manually recreating custom modes and copying `.roo/rules-{slug}/` folders for each new project or team member. Changing slugs required manual path updates in the YAML file.
**With this feature**: A single click exports a mode and all its rules to a YAML file. Another click imports it, setting everything up automatically. You can now change the slug in the exported file and the import process handles all path updates automatically.
### How it Works
The import/export functionality is managed from the **Modes** view.
![Mode Export and Import Buttons](/img/custom-modes/custom-modes-5.png)
#### Exporting a Mode
1. Navigate to the **Modes** view.
2. Select the mode you wish to export.
3. Click the **Export Mode** button (the download icon).
4. Choose a location to save the `.yaml` file.
Roo packages the mode's configuration and any rules found in the project's `.roo/rules-{slug}/` directory into the YAML file.
#### Importing a Mode
1. Click the **Import Mode** button (the upload icon) in the **Modes** view.
2. Select the mode's YAML file.
3. Choose the import level in the dialog that appears:
![Import Level Dialog](/img/custom-modes/custom-modes-6.png)
- **Project**: The mode is available only in the current workspace. It's added to the `.roomodes` file, and its rules are saved to the `.roo/rules-{slug}/` directory within the project.
- **Global**: The mode is available in all your projects. It's added to your global settings, and its rules are stored in your system's global Roo configuration directory (e.g., `~/.roo/rules-{slug}/`).
**Note:** When exporting modes with rules, all file paths are normalized to use forward slashes for cross-platform compatibility. This ensures modes can be shared between team members using different operating systems.
---
### Exported YAML file format:
```yaml
customModes:
- slug: "my-custom-mode"
name: "My Custom Mode"
roleDefinition: "You are a helpful assistant."
groups: ["read", "edit"]
rulesFiles:
- relativePath: "rules-my-custom-mode/rules.md"
content: "These are the rules for my custom mode."
```
### Changing Slugs on Import
When importing modes, you can change the slug in the exported YAML file before importing:
1. **Export a mode** with slug `original-mode`
2. **Edit the YAML file** and change the slug to `new-mode`
3. **Import the file** - the import process will:
- Create the new mode with the updated slug
- Update rule file paths to match the new slug
Note: The automatic slug change handling during import ensures that rule file paths are updated correctly when you change the mode slug in the exported file.
---
### FAQ
**"What happens if I import a mode that has the same 'slug' as an existing one?"**
- The existing mode will be overwritten with the configuration from the imported file.
**"What's the main difference between a Global and Project import?"**
- **Global** modes are available across all your VS Code projects. **Project** modes are specific to the workspace where they are imported and are stored in a `.roomodes` file at the root of your project.
**"Can I export built-in modes like Code or Architect?"**
- Yes. If you have customized a built-in mode (e.g., by changing its instructions), you can export it to save your customizations.
**"What if I import a mode with rules at the Global level?"**
- The rules are still preserved. They are stored in a global `rules-{slug}` folder in your user home directory (e.g., `~/.roo/rules-my-custom-mode/`) instead of the project-specific `.roo` folder.
**"How does the slug change feature work?"**
- When you change the slug in an exported YAML file before importing, the import process updates the rule file paths to match the new slug. This ensures the mode works correctly with its new identity.
---
## Methods for Creating and Configuring Custom Modes
You can create and configure custom modes in several ways:
To configure modes, open the Roo Code panel, click the Mode menu under the chatbox, then click the <Codicon name="settings-gear" />. From there, use "Edit Global Modes" to open settings/custom_modes.yaml, or "Edit Project Modes (.roomodes)" to open your workspace-level configuration.
### 1. Ask Roo! (Recommended)
You can quickly create a basic custom mode by asking Roo Code to do it for you. For example:
```
Create a new mode called "Documentation Writer". It should only be able to read files and write Markdown files.
```
Roo Code will guide you through the process, prompting for necessary information for the properties described in the [What's Included in a Custom Mode?](#whats-included-in-a-custom-mode) table. Roo will create the mode using the preferred YAML format. For fine-tuning or making specific adjustments later, you can use the Modes page or manual configuration.
### 2. Using the Modes Page
1. **Open the Modes page:** Open the Roo Code panel, click the Mode menu under the chatbox, then click the <Codicon name="settings-gear" />.
2. **Create New Mode:** Click the <Codicon name="add" /> button to the right of the Modes heading.
3. **Fill in Fields:**
<img src="/img/custom-modes/custom-modes-4.png" alt="Custom mode creation interface on the Modes page" width="600" />
*The custom mode creation interface showing fields for name, slug, description, save location, role definition, available tools, custom instructions.*
The interface provides fields for `Name`, `Slug`, `Description`, `Save Location`, `Role Definition`, `When to Use (optional)`, `Available Tools`, and `Custom Instructions`. After filling these, click the "Create Mode" button. Roo Code will save the new mode in YAML format.
*Refer to the [What's Included in a Custom Mode?](#whats-included-in-a-custom-mode) table for conceptual explanations of each property. File type restrictions for the "edit" tool group can be added by asking Roo or through manual YAML/JSON configuration.*
### 3. Manual Configuration (YAML & JSON)
You can directly edit the configuration files to create or modify custom modes. This method offers the most control over all properties. Roo Code now supports both YAML (preferred) and JSON formats.
* **Global Modes:** Edit the `custom_modes.yaml` (preferred) or `custom_modes.json` file. From the Modes page, click "Edit Global Modes" to open `settings/custom_modes.yaml`.
* **Project Modes:** Edit the `.roomodes` file (which can be YAML or JSON) in your project root. From the Modes page, click "Edit Project Modes (.roomodes)" to open or create the workspace file.
These files define an array/list of custom modes.
**YAML Example (`custom_modes.yaml` or `.roomodes`):**
```yaml
customModes:
- slug: docs-writer
name: 📝 Documentation Writer
description: A specialized mode for writing and editing technical documentation.
roleDefinition: You are a technical writer specializing in clear documentation.
whenToUse: Use this mode for writing and editing documentation.
customInstructions: Focus on clarity and completeness in documentation.
groups:
- read
- - edit # First element of tuple
- fileRegex: \.(md|mdx)$ # Second element is the options object
description: Markdown files only
- slug: another-mode
name: Another Mode
# ... other properties
```
**JSON Alternative (`custom_modes.json` or `.roomodes`):**
```json
{
"customModes": [
{
"slug": "docs-writer",
"name": "📝 Documentation Writer",
"description": "A specialized mode for writing and editing technical documentation.",
"roleDefinition": "You are a technical writer specializing in clear documentation.",
"whenToUse": "Use this mode for writing and editing documentation.",
"customInstructions": "Focus on clarity and completeness in documentation.",
"groups": [
"read",
["edit", { "fileRegex": "\\.(md|mdx)$", "description": "Markdown files only" }]
]
},
{
"slug": "another-mode",
"name": "Another Mode"
}
]
}
```
### YAML/JSON Property Details
##### `slug`
* **Purpose:** A unique identifier for the mode.
* **Format:** Must match the pattern `/^[a-zA-Z0-9-]+$/` (only letters, numbers, and hyphens).
* **Usage:** Used internally and in file/directory names for mode-specific rules (e.g., `.roo/rules-{slug}/`).
* **Recommendation:** Keep it short and descriptive.
* **Note:** The `source` property is automatically added by the system and shouldn't be manually set.
* *YAML Example:* `slug: docs-writer`
* *JSON Example:* `"slug": "docs-writer"`
##### `name`
* **Purpose:** The display name shown in the Roo Code UI.
* **Format:** Can include spaces and proper capitalization.
* *YAML Example:* `name: 📝 Documentation Writer`
* *JSON Example:* `"name": "Documentation Writer"`
##### `description`
* **Purpose:** A short, user-friendly summary displayed below the mode name in the mode selector UI.
* **Format:** Keep this concise and focused on what the mode does for the user.
* **UI Display:** This text appears in the redesigned mode selector, offering users a quick understanding of the mode's function.
* *YAML Example:* `description: A specialized mode for writing and editing technical documentation.`
* *JSON Example:* `"description": "A specialized mode for writing and editing technical documentation."`
##### `roleDefinition`
* **Purpose:** Detailed description of the mode's role, expertise, and personality.
* **Placement:** This text is placed at the beginning of the system prompt when the mode is active.
* **Updated Role:** With the introduction of the `description` field, the `roleDefinition` should provide a detailed description of the mode's identity, while the `description` field handles the short summary for the UI. The `whenToUse` property now takes precedence for summarization in automated contexts.
* *YAML Example (multi-line):*
```yaml
roleDefinition: >-
You are a test engineer with expertise in:
- Writing comprehensive test suites
- Test-driven development
```
* *JSON Example:* `"roleDefinition": "You are a technical writer specializing in clear documentation."`
##### `groups`
* **Purpose:** Array/list defining which tool groups the mode can access and any file restrictions.
* **Available Tool Groups (Strings):** `"read"`, `"edit"`, `"command"`, `"mcp"`.
* **Structure:** The `groups` property uses a specific structure:
* Simple string for unrestricted access: `"edit"`
* Tuple (two-element array) for restricted access: `["edit", { fileRegex: "pattern", description: "optional" }]`
* **File Restrictions for "edit" group:**
* To apply file restrictions, the "edit" entry becomes a tuple (YAML list or JSON array) where the first element is `"edit"` and the second is a map/object defining the restrictions.
* `fileRegex`: A regular expression string to control which files the mode can edit.
* In YAML, typically use single backslashes for regex special characters (e.g., `\.md$`).
* In JSON, backslashes must be double-escaped (e.g., `\\.md$`).
* `description`: An optional string describing the restriction.
* For more complex patterns, see [Understanding Regex in Custom Modes](#understanding-regex-in-custom-modes).
* *YAML Example:*
```yaml
groups:
- read
- - edit # First element of tuple
- fileRegex: \.(js|ts)$ # Second element is the options object
description: JS/TS files only
- command
```
* *JSON Example:*
```json
"groups": [
"read",
["edit", { "fileRegex": "\\.(js|ts)$", "description": "JS/TS files only" }],
"command"
]
```
##### `whenToUse`
* **Purpose:** (Optional) Provides guidance for Roo's automated decision-making, particularly for mode selection and task orchestration.
* **Format:** A string describing ideal scenarios or task types for this mode.
* **Usage:** This field is used by Roo for automated decisions and is **not displayed in the mode selector UI** - that's handled by the `description` field. If populated, Roo uses this description for orchestration and mode switching; otherwise, the first sentence of `roleDefinition` is used.
* *YAML Example:* `whenToUse: This mode is best for refactoring Python code.`
* *JSON Example:* `"whenToUse": "This mode is best for refactoring Python code."`
##### `customInstructions`
* **Purpose:** A string containing additional behavioral guidelines for the mode.
* **Placement:** This text is added near the end of the system prompt.
* **Supplementing:** Can be supplemented by [Mode-Specific Instructions via Files/Directories](#mode-specific-instructions-via-filesdirectories).
* *YAML Example (multi-line):*
```yaml
customInstructions: |-
When writing tests:
- Use describe/it blocks
- Include meaningful descriptions
```
* *JSON Example:* `"customInstructions": "Focus on explaining concepts and providing examples."`
### Benefits of YAML Format
YAML is now the preferred format for defining custom modes due to several advantages over JSON:
* **Readability:** YAML's indentation-based structure is often easier for humans to read and understand complex configurations.
* **Comments:** YAML allows for comments (lines starting with `#`), making it possible to annotate your mode definitions.
```yaml
customModes:
- slug: security-review
name: 🔒 Security Reviewer
# This mode is restricted to read-only access
roleDefinition: You are a security specialist reviewing code for vulnerabilities.
whenToUse: Use for security reviews and vulnerability assessments.
# Only allow reading files, no editing permissions
groups:
- read
```
* **Multi-line Strings:** YAML provides cleaner syntax for multi-line strings (e.g., for `roleDefinition` or `customInstructions`) using `|` (literal block) or `>` (folded block).
```yaml
customModes:
- slug: test-engineer
name: 🧪 Test Engineer
roleDefinition: >-
You are a test engineer with expertise in:
- Writing comprehensive test suites
- Test-driven development
- Integration testing
- Performance testing
customInstructions: |-
When writing tests:
- Use describe/it blocks
- Include meaningful descriptions
- Test edge cases
- Ensure proper coverage
# ... other properties
```
* **Less Punctuation:** YAML generally requires less punctuation (like commas and braces) compared to JSON, reducing syntax errors.
* **Editor Support:** Most modern code editors provide excellent syntax highlighting and validation for YAML files, further enhancing readability and reducing errors.
While JSON is still fully supported and won't be deprecated, new modes created via the UI or by asking Roo will default to YAML. Both `.roomodes` files and global configuration files can be either YAML or JSON format.
#### Tips for Working with YAML
When editing YAML manually, keep these points in mind:
* **Indentation is Key:** YAML uses indentation (spaces, not tabs) to define structure. Incorrect indentation is the most common source of errors. Ensure consistent spacing for nested elements.
* **Colons for Key-Value Pairs:** Keys must be followed by a colon and a space (e.g., `slug: my-mode`).
* **Hyphens for List Items:** List items start with a hyphen and a space (e.g., `- read`).
* **Validate Your YAML:** If you encounter issues, use an online YAML validator or your editor's built-in validation to check for syntax errors.
### Migration to YAML Format
* **Global Modes:** The automatic migration from `custom_modes.json` to `custom_modes.yaml` happens only for global modes when Roo Code starts up, under these conditions:
1. Roo Code starts up.
2. A `custom_modes.json` file exists.
3. No `custom_modes.yaml` file exists yet.
The migration process reads the existing JSON file, converts it to YAML format, creates a new `custom_modes.yaml` file, and preserves the original JSON file (e.g., by renaming it) for rollback purposes. If `custom_modes.yaml` already exists, it will be used, and no automatic migration of `custom_modes.json` will occur.
* **Project Modes (`.roomodes`):**
* **No automatic startup migration:** Unlike global modes, project-specific `.roomodes` files are not automatically converted from JSON to YAML when Roo Code starts. Manual conversion is required for existing JSON `.roomodes` files.
* **Format Detection:** Roo Code can read `.roomodes` files in either YAML or JSON format. Roo Code automatically detects the format of `.roomodes` files by attempting to parse them as YAML first.
* **Conversion on UI Edit:** If you edit a project-specific mode through the Roo Code UI (e.g., via the Modes page), and the existing `.roomodes` file is in JSON format, Roo Code will save the changes in YAML format. This effectively converts the file to YAML. The original JSON content will be overwritten with YAML.
* **Manual Conversion:** If you want to convert an existing `.roomodes` JSON file to YAML without making UI edits, you'll need to do this manually. You can:
1. Open your existing JSON `.roomodes` file.
2. Convert its content to YAML (you can ask Roo to help with this, or use an online converter).
3. Replace the content of your `.roomodes` file with the new YAML content, or rename the old file (e.g., `.roomodes.json.bak`) and save the new content into a file named `.roomodes`.
Ensure the resulting YAML is valid.
:::tip
For manual conversions of `.roomodes` files, you can use online JSON to YAML converters or ask Roo to help reformat a specific mode configuration from JSON to YAML. Always validate your YAML before saving.
:::
---
## Mode-Specific Instructions via Files/Directories
:::info Mode-Specific Instruction File Locations
You can provide instructions for custom modes using dedicated files or directories within your workspace. This allows for better organization and version control compared to only using the `customInstructions` property.
**Preferred Method: Directory (`.roo/rules-{mode-slug}/`)**
```
.
├── .roo/
│ └── rules-docs-writer/ # Example for mode slug "docs-writer"
│ ├── 01-style-guide.md
│ └── 02-formatting.txt
└── ... (other project files)
```
**Fallback Method: Single File (`.roorules-{mode-slug}`)**
```
.
├── .roorules-docs-writer # Example for mode slug "docs-writer"
└── ... (other project files)
```
**Legacy Fallback: `.clinerules-{mode-slug}`**
For backward compatibility, the system also checks for `.clinerules-{mode-slug}` files as an additional fallback, though this is not recommended for new projects.
The directory method takes precedence if it exists and contains files.
**Rules Directory Scope:**
- **Global modes:** Rules are stored in `~/.roo/rules-{slug}/` (note the trailing slash)
- **Project modes:** Rules are stored in `{workspace}/.roo/rules-{slug}/` (note the trailing slash)
:::
In addition to the `customInstructions` property, you can provide mode-specific instructions via files in your workspace. This is particularly useful for:
* Organizing lengthy or complex instructions into multiple, manageable files.
* Managing instructions easily with version control.
* Allowing non-technical team members to modify instructions without editing YAML/JSON.
There are two ways Roo Code loads these instructions, with a clear preference for the newer directory-based method:
**1. Preferred Method: Directory-Based Instructions (`.roo/rules-{mode-slug}/`)**
* **Structure:** Create a directory named `.roo/rules-{mode-slug}/` in your workspace root. Replace `{mode-slug}` with your mode's slug (e.g., `.roo/rules-docs-writer/`).
* **Content:** Place one or more files (e.g., `.md`, `.txt`) containing your instructions inside this directory. You can organize instructions further using subdirectories. Files within the `.roo/rules-{mode-slug}/` directory are read recursively and appended in alphabetical order based on filename (case-insensitive).
* **Loading:** All instruction files found within this directory structure will be loaded and applied to the specified mode. System files (`.DS_Store`, `.swp`, etc.) and cache files are automatically excluded.
* **Advanced Features:** The system supports symbolic links with cycle detection for advanced file organization.
**2. Fallback (Backward Compatibility): File-Based Instructions (`.roorules-{mode-slug}`)**
* **Structure:** If the `.roo/rules-{mode-slug}/` directory **does not exist or is empty**, Roo Code will look for a single file named `.roorules-{mode-slug}` in your workspace root (e.g., `.roorules-docs-writer`).
* **Loading:** If found, the content of this single file will be loaded as instructions for the mode.
**Precedence:**
* The **directory-based method (`.roo/rules-{mode-slug}/`) takes precedence**. If this directory exists and contains files, any corresponding root-level `.roorules-{mode-slug}` file will be **ignored** for that mode.
* This ensures that projects migrated to the new directory structure behave predictably, while older projects using the single-file method remain compatible.
**Combining with `customInstructions`:**
* Instructions loaded from either the directory or the fallback file are combined with the `customInstructions` property defined in the mode's configuration.
* Typically, the content from the files/directories is appended after the content from the `customInstructions` property.
---
## Configuration Precedence
Mode configurations are applied in this order:
1. Project-level mode configurations (from `.roomodes` - YAML or JSON)
2. Global mode configurations (from `custom_modes.yaml`, then `custom_modes.json` if YAML not found)
3. Default mode configurations
**Important:** When modes with the same slug exist in both `.roomodes` and global settings, the `.roomodes` version completely overrides the global one. This applies to ALL properties, not just some. For instance, if you have a global 'code' mode and a project-specific 'code' mode in `.roomodes`, the project version will be used when working in that project, and all properties from the global version are ignored.
You can override any default mode by including a mode with the same slug in your global or project-specific configuration.
* **Note on Instruction Files:** Within the loading of mode-specific instructions from the filesystem, the directory `.roo/rules-{mode-slug}/` takes precedence over the single file `.roorules-{mode-slug}` found in the workspace root.
---
## Overriding Default Modes
You can override Roo Code's built-in modes (like `💻 Code`, `🪲 Debug`, `❓ Ask`, `🏗️ Architect`, `🪃 Orchestrator`) with customized versions. This is done by creating a custom mode with the same slug as a default mode (e.g., `code`, `debug`).
### Overriding Modes Globally
To customize a default mode across all your projects:
1. **Open the Modes page:** Open the Roo Code panel, click the Mode menu under the chatbox, then click the <Codicon name="settings-gear" />.
2. **Edit Global Modes:** Click "Edit Global Modes" to open `settings/custom_modes.yaml` (or `custom_modes.json`).
3. **Add Your Override:**
**YAML Example:**
```yaml
customModes:
- slug: code # Matches the default 'code' mode slug
name: 💻 Code (Global Override) # Custom display name
roleDefinition: You are a software engineer with global-specific constraints.
whenToUse: This globally overridden code mode is for JS/TS tasks.
customInstructions: Focus on project-specific JS/TS development.
groups:
- read
- - edit
- fileRegex: \.(js|ts)$
description: JS/TS files only
```
**JSON Alternative:**
```json
{
"customModes": [{
"slug": "code",
"name": "💻 Code (Global Override)",
"roleDefinition": "You are a software engineer with global-specific constraints",
"whenToUse": "This globally overridden code mode is for JS/TS tasks.",
"customInstructions": "Focus on project-specific JS/TS development",
"groups": [
"read",
["edit", { "fileRegex": "\\.(js|ts)$", "description": "JS/TS files only" }]
]
}]
}
```
This example replaces the default `💻 Code` mode with a version restricted to JavaScript and TypeScript files.
### Project-Specific Mode Override
To override a default mode for just one project:
1. **Open the Modes page:** Open the Roo Code panel, click the Mode menu under the chatbox, then click the <Codicon name="settings-gear" />.
2. **Edit Project Modes (.roomodes):** Click "Edit Project Modes (.roomodes)" to open or create the workspace file.
3. **Add Your Override:**
**YAML Example:**
```yaml
customModes:
- slug: code # Matches the default 'code' mode slug
name: 💻 Code (Project-Specific) # Custom display name
roleDefinition: You are a software engineer with project-specific constraints for this project.
whenToUse: This project-specific code mode is for Python tasks within this project.
customInstructions: Adhere to PEP8 and use type hints.
groups:
- read
- - edit
- fileRegex: \.py$
description: Python files only
- command
```
**JSON Alternative:**
```json
{
"customModes": [{
"slug": "code",
"name": "💻 Code (Project-Specific)",
"roleDefinition": "You are a software engineer with project-specific constraints for this project.",
"whenToUse": "This project-specific code mode is for Python tasks within this project.",
"customInstructions": "Adhere to PEP8 and use type hints.",
"groups": [
"read",
["edit", { "fileRegex": "\\.py$", "description": "Python files only" }],
"command"
]
}]
}
```
Project-specific overrides take precedence over global overrides.
### Common Use Cases for Overriding Default Modes
* **Restricting file access:** Limit a mode to specific file types.
* **Specializing behavior:** Customize expertise for your tech stack.
* **Adding custom instructions:** Integrate project standards.
* **Changing available tools:** Remove tools to prevent unwanted operations.
:::tip
When overriding default modes, test carefully. Consider backing up configurations before major changes.
:::
---
## Understanding Regex in Custom Modes
Regular expressions (`fileRegex`) offer fine-grained control over file editing permissions.
:::tip
**Let Roo Build Your Regex Patterns**
Instead of writing complex regex manually, ask Roo:
```
Create a regex pattern that matches JavaScript files but excludes test files
```
Roo will generate the pattern. Remember to adapt it for YAML (usually single backslashes) or JSON (double backslashes).
:::
When you specify `fileRegex`, you're creating a pattern that file paths must match.
**Important Rules for `fileRegex`:**
* **Escaping in JSON:** In JSON strings, backslashes (`\`) must be double-escaped (e.g., `\\.md$`).
* **Escaping in YAML:** In unquoted or single-quoted YAML strings, a single backslash is usually sufficient for regex special characters (e.g., `\.md$`). However, YAML regex patterns in quoted strings may need double escaping similar to JSON.
* **Path Matching:** Patterns match against the full relative file path from your workspace root (e.g., `src/components/button.js`).
* **Case Sensitivity:** Regex patterns are case-sensitive by default.
* **Validation:** Invalid regex patterns are rejected with an "Invalid regular expression pattern" error message.
**Common Pattern Examples:**
In the table below, the 'Pattern (Conceptual / YAML-like)' column shows patterns as they would appear in YAML. For JSON, remember to double-escape backslashes.
| Pattern (Conceptual / YAML-like) | JSON `fileRegex` Value | Matches | Doesn't Match |
| -------------------------------- | ------------------------------- | ----------------------------------------- | ------------------------------------- |
| `\.md$` | `"\\.md$"` | `readme.md`, `docs/guide.md` | `script.js`, `readme.md.bak` |
| `^src/.*` | `"^src/.*"` | `src/app.js`, `src/components/button.tsx` | `lib/utils.js`, `test/src/mock.js` |
| `\.(css|scss)$` | "\\.(css|scss)$" | `styles.css`, `theme.scss` | `styles.less`, `styles.css.map` |
| `docs/.*\.md$` | `"docs/.*\\.md$"` | `docs/guide.md`, `docs/api/reference.md` | `guide.md`, `src/docs/notes.md` |
| `^(?!.*(test\|spec))\.(js\|ts)$` | `"^(?!.*(test\|spec))\\.(js\|ts)$"` | `app.js`, `utils.ts` | `app.test.js`, `utils.spec.js`, `app.jsx` |
**Key Regex Building Blocks:**
* `\.`: Matches a literal dot. (YAML: `\.`, JSON: `\\.`)
* `$`: Matches the end of the string.
* `^`: Matches the beginning of the string.
* `.*`: Matches any character (except newline) zero or more times.
* `(a|b)`: Matches either "a" or "b". (e.g., `\.(js|ts)$`)
* `(?!...)`: Negative lookahead.
**Testing Your Patterns:**
1. Test on sample file paths. Online regex testers are helpful.
2. Remember the escaping rules for JSON vs. YAML.
3. Start simple and build complexity.
:::info Error Handling
When a mode attempts to edit a file that doesn't match its `fileRegex` pattern, you'll see a `FileRestrictionError` that includes:
- The mode name
- The allowed file pattern
- The description (if provided)
- The attempted file path
- The tool that was blocked
This information helps you understand why your operation was blocked and what file types are allowed for the current mode.
:::
---
## Additional Features
### Built-in Mode Customization
When exporting built-in modes (like Code, Architect, Ask, Debug), any customizations you've made are included in the export. This allows you to share your personalized versions of built-in modes with others.
### Mode Deletion and Rules
When deleting a mode through the UI, Roo Code will prompt you about deleting the associated rules folder, showing the exact path before deletion. This helps prevent accidental loss of custom instructions.
### Global Rules Directory
In addition to mode-specific rules directories, there's also a generic `.roo/rules/` directory (without mode suffix) that can be used for shared rules across all modes.
### Troubleshooting
**Common Issues:**
- **Mode not appearing:** After creating or importing a mode, you may need to reload the VS Code window for it to appear in the mode selector.
- **Invalid regex patterns:** If your `fileRegex` pattern is invalid, you'll receive an error message. Test your patterns using online regex testers before applying them.
- **Precedence confusion:** Remember that project modes completely override global modes with the same slug - no properties are merged.

183
apps/docs/docs/features/diagnostics-integration.md Normal file
View file

@ -0,0 +1,183 @@
---
description: Leverage Roo Code's integration with VSCode's Problems panel to automatically detect, understand, and fix code errors, warnings, and linting issues.
keywords:
- diagnostics integration
- error detection
- problems panel
- code fixes
- linting
- language server
- automatic error fixing
---
# Diagnostics Integration
Roo Code provides intelligent integration with VSCode's Problems panel, allowing the AI assistant to understand and help fix code errors, warnings, and other issues detected by language servers, linters, and other diagnostic providers.
---
## Overview
The diagnostics feature seamlessly integrates with VSCode's diagnostic system to provide context-aware assistance for code issues. When you make edits or encounter problems in your code, Roo Code can automatically detect and help resolve them.
### Key Capabilities
- **Automatic Error Detection**: Captures new errors introduced during code edits
- **Context-Aware Fixes**: Provides targeted fixes based on diagnostic information
- **Workspace Problems Mention**: Access all workspace diagnostics through a simple mention
- **Smart Filtering**: Uses predefined severity levels for different contexts
---
## Key Features
### 1. Automatic Error Detection
When Roo Code makes edits to files, it automatically:
- Captures diagnostics before editing
- Waits for diagnostics to update after editing
- Detects new problems introduced by the changes
- Only reports new errors (not pre-existing ones)
This ensures you're immediately aware of any issues introduced by code changes, allowing for quick resolution.
### 2. Workspace Problems Mention
Users can include `@problems` in their messages to:
- Get a complete list of workspace errors and warnings
- Provide context for debugging tasks
- Request fixes for specific issues
Example usage:
```
@problems Fix all TypeScript errors in my project
```
For more details on using `@problems`, see [Context Mentions](/basic-usage/context-mentions#problems-mention).
### 3. Code Actions Integration
When diagnostics exist at a cursor position:
- "Fix with Roo Code" action appears in quick fix menu
- Includes diagnostic details in the fix request
- Provides targeted solutions based on error context
Learn more about this integration in [Code Actions](/features/code-actions#context-aware-actions).
### 4. Smart Severity Filtering
Different features use different severity filters to provide the most relevant information:
- **Workspace Problems mention**: Shows errors and warnings
- **Automatic detection**: Shows only errors (to avoid distraction)
- **Context-Aware**: Different features use different hardcoded severity filters
---
## Severity Levels
The diagnostics system recognizes four severity levels from VSCode:
| Level | Value | Description | Workspace Problems | Auto-detection |
| ----------- | ----- | --------------------------------------------------- | ------------------ | --------------- |
| Error | 0 | Syntax errors, type errors, breaking issues | ✅ Included | ✅ Included |
| Warning | 1 | Code quality issues, deprecations, style violations | ✅ Included | ❌ Not included |
| Information | 2 | Suggestions, hints, informational messages | ❌ Not included | ❌ Not included |
| Hint | 3 | Minor suggestions, refactoring opportunities | ❌ Not included | ❌ Not included |
### Why Different Filters?
- **Workspace Problems (`@problems`)**: Includes both errors and warnings to give you a complete picture of code health when explicitly requested
- **Automatic Detection**: Only includes errors to avoid interrupting your workflow with non-critical issues
---
## Using Diagnostics Effectively
### For Debugging Sessions
When starting a debugging session, include `@problems` to give Roo Code full context:
```
@problems Help me debug why my application is crashing
```
### For Code Reviews
Use diagnostics to ensure code quality:
```
@problems Review my code and fix any linting issues
```
### For Refactoring
Let diagnostics guide safe refactoring:
```
I want to refactor this function. @problems shows current issues to address.
```
---
## Integration with Other Features
### Code Actions
Diagnostics power the context-aware [Code Actions](/features/code-actions) that appear in VSCode's lightbulb menu. When errors are present, you'll see "Fix Code" options that include the specific diagnostic information.
### Context Mentions
The [`@problems` mention](/basic-usage/context-mentions#problems-mention) provides a convenient way to include all workspace diagnostics in your conversation without manually copying error messages.
### Automatic Error Reporting
When Roo Code edits files, any new errors introduced are automatically reported in the response, helping maintain code quality throughout the editing process.
---
## Best Practices
1. **Use `@problems` for Context**: When debugging, always include `@problems` to give Roo Code full visibility into current issues
2. **Address Errors First**: Focus on fixing errors before warnings, as errors typically prevent code from running
3. **Leverage Code Actions**: Use the quick fix menu for targeted fixes to specific diagnostics
4. **Monitor Auto-Detection**: Pay attention to new errors reported after edits to catch issues early
5. **Combine with Other Tools**: Use diagnostics alongside other Roo Code features like codebase search and file mentions for comprehensive problem-solving
---
## Troubleshooting
### Diagnostics Not Appearing
- Ensure your language server or linter is properly configured and running
- Check that the file type is supported by your diagnostic providers
- Verify that VSCode's Problems panel shows the issues
### `@problems` Shows Nothing
- Confirm there are actually problems in the Problems panel
- Check that you're in the correct workspace
- Some diagnostic providers may take time to initialize
### Auto-Detection Missing Errors
- Only new errors (introduced by edits) are reported
- Pre-existing errors won't be shown in auto-detection
- Use `@problems` to see all current issues
---
## Related Features
- [Context Mentions](/basic-usage/context-mentions) - Learn about all mention types including `@problems`
- [Code Actions](/features/code-actions) - Discover how diagnostics integrate with quick fixes
- [Codebase Search](/features/codebase-indexing) - Find code related to specific errors

149
apps/docs/docs/features/enhance-prompt.md Normal file
View file

@ -0,0 +1,149 @@
---
description: Improve your AI interactions with Roo Code's Enhance Prompt feature. Automatically refine prompts for clarity, context, and better results with one click.
keywords:
- enhance prompt
- prompt optimization
- AI prompts
- prompt engineering
- chat enhancement
- prompt refinement
- wand icon
---
# Enhance Prompt
The "Enhance Prompt" feature in Roo Code helps you improve the quality and effectiveness of your prompts before sending them to the AI model. By clicking the wand icon in the chat input, you can automatically refine your initial request, making it clearer, more specific, and more likely to produce the desired results.
---
## Why Use Enhance Prompt?
- **Improved Clarity:** Roo Code can rephrase your prompt to make it more understandable for the AI model.
- **Added Context:** The enhancement process can add relevant context to your prompt, such as the current file path or selected code.
- **Better Instructions:** Roo Code can add instructions to guide the AI towards a more helpful response (e.g., requesting specific formatting or a particular level of detail).
- **Reduced Ambiguity:** Enhance Prompt helps to eliminate ambiguity and ensure that Roo Code understands your intent.
- **Consistency**: Roo will consistently format prompts the same way to the AI.
- **Context-Aware Suggestions:** When enabled, uses your recent conversation history to generate more relevant and accurate enhancements.
---
## How to Use Enhance Prompt
1. **Type your initial prompt:** Enter your request in the Roo Code chat input box as you normally would. This can be a simple question, a complex task description, or anything in between.
2. **Click the Wand Icon:** Instead of pressing Enter, click the wand icon located in the top right corner of the chat input box. While Roo processes your enhancement request, the wand icon will spin to indicate it's working.
3. **Review the Enhanced Prompt:** Roo Code will replace your original prompt with an enhanced version. Review the enhanced prompt to make sure it accurately reflects your intent. You can further refine the enhanced prompt before sending. Changed your mind? You can undo the enhancement using Ctrl+Z (Cmd+Z on Mac) to restore your original prompt.
4. **Send the Enhanced Prompt:** Press Enter or click the Send icon (<Codicon name="send" />) to send the enhanced prompt to Roo Code.
---
## Special Behaviors
### Empty Prompt Enhancement
If you click the enhance button with an empty prompt, Roo will show you a helpful message explaining how the feature works. This is a great way to learn about the enhancement feature if you're new to it.
### Message Queueing Support
The enhance button remains enabled even when message sending is disabled. This allows you to enhance prompts that will be queued for later sending.
---
## Customizing the Enhancement Process
The "Enhance Prompt" feature uses a customizable prompt template. You can modify this template to tailor the enhancement process to your specific needs.
### Accessing Prompts Settings
1. **Open Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel or use the settings command.
2. **Navigate to Prompts:** Go to the "Prompts" tab in the settings.
3. **Select "ENHANCE":** From the dropdown menu, select "ENHANCE" to view and edit the enhancement prompt.
### Editing the Enhancement Prompt
The default enhancement prompt template is:
```
Generate an enhanced version of this prompt (reply with only the enhanced prompt - no conversation, explanations, lead-in, bullet points, placeholders, or surrounding quotes):
${userInput}
```
The `${userInput}` placeholder will be replaced with your original prompt. You can modify this template to fit your needs and the model's prompt format.
### Testing Your Custom Prompt
The Prompts settings include a test area where you can preview how your custom enhancement prompt works:
1. After editing your enhancement prompt, look for the "Test Enhancement" section
2. Enter a sample prompt to test
3. Click "Test" to see how your custom prompt would enhance it
4. Adjust your enhancement prompt as needed based on the results
---
## API Configuration
The API configuration used for Enhance Prompt is, by default, the same one that is selected for Roo Code tasks, but it can be changed:
1. **Open Settings:** Navigate to Roo Code settings
2. **Go to Prompts Tab:** Select the "Prompts" tab
3. **Select "ENHANCE":** Choose "ENHANCE" from the dropdown
4. **Configure API:** You'll see an "API Configuration" dropdown where you can choose an existing configuration. Future Enhance Prompt requests will be sent to that configured provider/model.
---
## Context-Aware Enhancement
The Enhance Prompt feature can now use your conversation history to generate more relevant suggestions. This helps reduce hallucinations and provides more accurate enhancements based on what you've been working on.
### How It Works
When enabled, the enhancement process includes your last 10 messages from the current conversation as context. This allows the AI to:
- Understand what you've been working on
- Maintain consistency with previous discussions
- Avoid suggesting unrelated or incorrect enhancements
- Provide more targeted and useful prompt improvements
### Enabling Task History Context
To enable or disable the use of conversation history in prompt enhancement:
1. **Open Settings:** Navigate to Roo Code settings
2. **Go to Prompts Tab:** Select the "Prompts" tab
3. **Select "ENHANCE":** Choose "ENHANCE" from the dropdown
4. **Toggle History Option:** Check or uncheck "Include task history in enhancement" for better context
When disabled, the enhancement will only consider your current prompt without any conversation context.
---
## Visual Feedback and UI Elements
### Button Appearance
- The wand icon appears semi-transparent (60% opacity) by default
- Becomes fully opaque (100%) when you hover over it
- Located in the top-right corner of the chat input box
- Has a focus ring for keyboard accessibility
### Loading State
- While processing your enhancement request, the wand icon spins
- This provides clear visual feedback that Roo is working on your prompt
### Tooltip
- Hovering over the button shows: "Enhance prompt with additional context"
- Helps new users understand the button's purpose
---
## Limitations and Best Practices
- **Experimental Feature:** Prompt enhancement is an experimental feature. The quality of the enhanced prompt may vary depending on the complexity of your request and the capabilities of the underlying model.
- **Review Carefully:** Always review the enhanced prompt before sending it. Roo Code may make changes that don't align with your intentions.
- **Iterative Process:** You can use the "Enhance Prompt" feature multiple times to iteratively refine your prompt.
- **Not a Replacement for Clear Instructions:** While "Enhance Prompt" can help, it's still important to write clear and specific prompts from the start.
By using the "Enhance Prompt" feature, you can improve the quality of your interactions with Roo Code and get more accurate and helpful responses.

138
apps/docs/docs/features/experimental/background-editing.md Normal file
View file

@ -0,0 +1,138 @@
---
description: Learn about the experimental Background Editing setting that allows uninterrupted coding while Roo Code makes file edits in the background.
keywords:
- experimental features
- editor focus
- diff views
- background editing
- workflow optimization
- uninterrupted coding
---
# Background Editing
Work without interruption while Roo Code edits files in the background—no more losing focus from automatic diff views.
:::warning Experimental Feature
This is an experimental feature that changes how file edits are displayed. While it can significantly improve workflow, you'll need to manually review changes through source control or file history.
:::
---
## Overview
The "Background Editing" setting is an experimental feature that disables automatic diff view displays when Roo Code edits files. Instead of switching your editor focus to show diffs, Roo works silently in the background, allowing you to continue coding without interruption. This feature affects all file editing operations including write, apply diff, search/replace, insert content, and multi-file apply diff tools.
### Key Benefits
- **Uninterrupted Focus**: Stay in your current file while Roo makes changes
- **Smoother Workflow**: No context switching between files
- **Background Processing**: File edits happen silently
- **Reduced Distractions**: Maintain your coding flow
- **Performance**: Faster file operations without UI updates
- **Batch Operations**: Ideal for large refactoring or multiple file updates
### Trade-offs
- **No Visual Confirmation**: You won't see diffs as changes are made
- **Manual Review Required**: Check changes through Git or file history
- **Less Immediate Feedback**: Changes aren't immediately visible
- **Silent Changes**: Files change without visual notification - check Git status regularly
- **Limited Environment Context**: Roo won't see recently edited files as open tabs in its environment details since they're not visually opened
---
## Enabling the Feature
To enable Background Editing:
1. Open Roo Code settings (gear icon in the top right)
2. Navigate to the "Experimental" tab
3. Find "Background editing" in the list
4. Toggle the setting to enable it
<img src="/img/background-editing/background-editing.png" alt="Background editing setting in Roo Code experimental features" width="400" />
---
## How It Works
### Default Behavior (Feature Disabled)
Without this feature, when Roo edits a file:
1. The file opens in your editor
2. A diff view appears showing changes
3. Your focus shifts to the modified file
4. You review and potentially adjust changes
### With Feature Enabled
When enabled, Roo's file edits:
1. Happen silently in the background
2. Don't open new editor tabs
3. Don't show diff views
4. Don't interrupt your current work
5. Still open files in memory for diagnostic detection (not visible)
### What Still Happens
Even with the feature enabled:
- Files are still modified on disk
- Changes appear in source control
- File watchers and build tools detect changes
- Roo's chat shows what files were edited
- Error detection and diagnostics continue to work normally
- Files are opened in memory for diagnostic purposes (not visible in editor)
- Write delays for diagnostic detection are still respected
---
## Best Use Cases
This feature is particularly beneficial for:
- **Large Refactoring Operations**: When Roo needs to update many files
- **Batch File Updates**: Making similar changes across multiple files
- **Performance-Sensitive Tasks**: When UI updates would slow down operations
- **Focused Coding Sessions**: When you want to avoid context switches
- **Automated Workflows**: Running multiple file operations in sequence
---
## Best Practices
When using this feature:
1. **Use Version Control**: Regularly check Git status to track changes
2. **Review Periodically**: Don't let too many changes accumulate without review
3. **Enable Selectively**: Consider enabling for specific task types
4. **Monitor Chat**: Pay attention to Roo's messages about file modifications
5. **Check Diagnostics**: Ensure your editor's problems panel stays visible
---
## FAQ
**Q: Can I still see what files Roo edited?**
A: Yes, Roo's chat messages list all modified files, and changes appear in source control.
**Q: What if I need to see a specific change immediately?**
A: You can manually open the file and use source control to view the diff.
**Q: Does this affect Roo's ability to edit files?**
A: No, Roo can still make all the same edits; only the display behavior changes. All file editing tools (write, apply diff, search/replace, insert content, and multi-file apply diff) respect this setting.
**Q: Can I enable this for specific projects only?**
A: Currently, this is a global setting that affects all projects.
**Q: What happens to approval dialogs?**
A: File edit approvals still appear if you haven't auto-approved them; only the diff display is suppressed.
**Q: Do diagnostics and error detection still work?**
A: Yes, files are opened in memory for diagnostic detection, so error checking continues to function normally even though files aren't displayed.
**Q: How does this feature appear in the settings?**
A: In the Experimental tab, it's labeled as "Background editing" with a description about preventing editor focus disruption.

127
apps/docs/docs/features/experimental/concurrent-file-edits.md Normal file
View file

@ -0,0 +1,127 @@
---
sidebar_label: "Multi-File Edits"
description: "Speed up refactoring and multi-file changes with Roo Code's Concurrent File Edits feature. Edit multiple files in a single operation with batch approval."
keywords:
- concurrent file edits
- multi-file edits
- batch editing
- refactoring
- apply_diff
- "batch approval"
---
# Concurrent File Edits (AKA Multi-File Edits)
:::note
Multi-file edits have graduated from experimental status and are now enabled by default. You no longer need to enable this feature in settings.
:::
Edit multiple files in a single operation, dramatically speeding up refactoring and multi-file changes.
---
## What It Does
<img src="/img/concurrent-file-edits/concurrent-file-edits-1.png" alt="Batch diff approval interface showing multiple file changes" width="800" />
Concurrent File Edits allows Roo to modify multiple files in your workspace within a single request. Instead of approving each file edit individually, you review and approve all changes at once through a unified batch approval interface.
---
## Why Use It
**Traditional approach**: Sequential file edits requiring individual approvals
- Edit file A → Approve
- Edit file B → Approve
- Edit file C → Approve
**With Concurrent File Edits**: All changes presented together
- Review all proposed changes across files A, B, and C
- Approve once to apply all changes
This reduces interruptions and speeds up complex tasks like:
- Refactoring functions across multiple files
- Updating configuration values throughout your codebase
- Renaming components and their references
- Applying consistent formatting or style changes
---
## Availability
Multi-file edits are now available by default in Roo Code. The feature has graduated from experimental status and no longer requires manual activation in settings.
---
## Using the Feature
When enabled, Roo automatically uses concurrent edits when appropriate. You'll see a "Batch Diff Approval" interface showing:
- All files to be modified
- Proposed changes for each file
- Options to approve all changes or review individually
### Example Workflow
1. Ask Roo to "Update all API endpoints to use the new authentication method"
2. Roo analyzes your codebase and identifies all affected files
3. You receive a single batch approval request showing changes across:
- `src/api/users.js`
- `src/api/products.js`
- `src/api/orders.js`
- `src/middleware/auth.js`
4. Review all changes in the unified diff view
5. Approve to apply all changes simultaneously
---
## Technical Details
This feature leverages the [`apply_diff`](/advanced-usage/available-tools/apply-diff) tool's multi-file capabilities. For detailed information about the implementation and diff format, see the [apply_diff documentation](/advanced-usage/available-tools/apply-diff).
---
## Best Practices
- Use with capable AI models (Claude 3.5 Sonnet, GPT-4, etc.) for best results
- Review all proposed changes carefully before approving
- For very large batch operations, consider breaking the task into smaller chunks
---
## Limitations
- **Model dependent**: Works best with more capable AI models
- **Token usage**: Initial requests may use more tokens due to larger context
- **Complexity**: Very large batch operations might be harder to review
---
## Troubleshooting
### Changes Not Batching
- Check that your model supports multi-file operations
- Ensure files aren't restricted by `.rooignore`
### Approval UI Not Appearing
- Update to the latest version of Roo Code
- Check VS Code's output panel for errors
- Try disabling and re-enabling the feature
### Performance Issues
- For very large batches, consider breaking the task into smaller chunks
- Monitor token usage if working with limited API quotas
---
## See Also
- [`apply_diff` Tool Documentation](/advanced-usage/available-tools/apply-diff) - Detailed technical information
- [Experimental Features](/features/experimental/experimental-features) - Other experimental capabilities
- [`.rooignore` Configuration](/features/rooignore) - File access restrictions

188
apps/docs/docs/features/experimental/custom-tools.md Normal file
View file

@ -0,0 +1,188 @@
---
description: Define TypeScript/JavaScript tools that extend Roo's capabilities beyond built-in tools, with npm dependency support and per-tool environment variables.
keywords:
- experimental features
- custom tools
- TypeScript tools
- JavaScript tools
- tool extension
- defineCustomTool
- workflow automation
- npm dependencies
- environment variables
---
# Custom Tools
Define TypeScript or JavaScript tools that Roo can call like built-in tools—standardize team workflows instead of re-prompting the same steps every task.
:::warning Experimental Feature
Custom tools is an experimental feature. Custom tools are **automatically approved** when enabled—Roo won't ask for permission before running them. Only enable this feature if you trust your tool code.
:::
---
## What it does
Custom tools let you codify project-specific actions into TypeScript/JavaScript files that Roo calls like [`read_file()`](/basic-usage/how-tools-work) or [`execute_command()`](/basic-usage/how-tools-work). Ship tool schemas alongside your repo so teammates don't need to keep re-explaining the same workflow steps. Tools are validated with Zod and automatically transpiled from TypeScript.
---
## How to create a tool
Tools live in `.roo/tools/` (project-specific) or `~/.roo/tools/` (global) as `.ts` or `.js` files. Tools from later directories can override earlier ones.
#### Basic structure
```typescript
import { parametersSchema as z, defineCustomTool } from "@roo-code/types"
export default defineCustomTool({
name: "tool_name",
description: "What the tool does (shown to AI)",
parameters: z.object({
param1: z.string().describe("Parameter description"),
param2: z.number().describe("Another parameter"),
}),
async execute(args, context) {
// args are type-safe and validated
// context provides: mode, task
return "Result string shown to AI"
},
})
```
#### What you define
- **`name`**: Tool name Roo sees in its available tools list
- **`description`**: Shown to the AI so it knows when to call the tool
- **`parameters`**: Zod schema converted to JSON Schema for validation
- **`execute`**: Async function returning a string result to Roo
Tools are dynamically loaded and transpiled with esbuild. Automatic reload on file changes isn't reliable—use the **Refresh Custom Tools** command to pick up changes immediately.
---
## Enabling the feature
1. Open Roo Code settings (gear icon in top right)
2. Go to the "Experimental" tab
3. Toggle "Enable custom tools"
<img src="/img/custom-tools/custom-tools.png" alt="Enable custom tools toggle in experimental settings" width="400" />
**Critical:** When enabled, custom tools are **auto-approved**—Roo runs them without asking. Disable if you don't trust the tool code.
---
## Tool directories
- **`.roo/tools/`** in your workspace: project-specific tools shared with your team
- **`~/.roo/tools/`** in your home folder: personal tools across all projects
Tools from both directories are loaded. Tools with the same name in `.roo/tools/` override those in `~/.roo/tools/`.
---
## Using npm Dependencies
Custom tools can use npm packages. Install dependencies in the same folder as your tool, and imports will resolve normally.
```bash
# From your tool directory
cd .roo/tools/
npm init -y
npm install axios lodash
```
Then import in your tool:
```typescript
import { parametersSchema as z, defineCustomTool } from "@roo-code/types"
import axios from "axios"
export default defineCustomTool({
name: "fetch_api",
description: "Fetch data from an API endpoint",
parameters: z.object({
url: z.string().describe("API endpoint URL"),
}),
async execute({ url }) {
const response = await axios.get(url)
return JSON.stringify(response.data, null, 2)
},
})
```
---
## Per-Tool Environment Variables
Roo copies `.env` and `.env.*` files from your tool directory into the tool's cache folder so your tool can load them at runtime. **Roo does not automatically inject these variables into `process.env`**—your tool must load them itself.
**Setup:**
1. Create a `.env` file next to your tool:
```
.roo/tools/
├── my-tool.ts
├── .env # Copied to cache dir at load time
└── package.json
```
2. Add your secrets:
```bash
# .roo/tools/.env
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/XXX
API_SECRET=your-secret-key
```
3. Load the `.env` in your tool using `dotenv` and `__dirname`:
```typescript
import { parametersSchema as z, defineCustomTool } from "@roo-code/types"
import dotenv from "dotenv"
import path from "path"
// Load .env from the tool's cache directory
dotenv.config({ path: path.join(__dirname, ".env") })
export default defineCustomTool({
name: "notify_slack",
description: "Send a notification to Slack",
parameters: z.object({
message: z.string().describe("Message to send"),
}),
async execute({ message }) {
const webhookUrl = process.env.SLACK_WEBHOOK_URL
if (!webhookUrl) {
return "Error: SLACK_WEBHOOK_URL not set in .env"
}
const response = await fetch(webhookUrl, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ text: message }),
})
return response.ok ? "Message sent" : `Failed: ${response.status}`
},
})
```
**Why `__dirname`?** Roo copies your `.env` files into a cache directory alongside the transpiled tool. Using `__dirname` ensures your tool finds the `.env` in the correct location regardless of where the tool was originally defined.
**Security:** Ensure your `.env` file is ignored by version control to keep secrets safe.
---
## Limits
- **No approval prompts**: Tools are auto-approved when the feature is enabled—security trade-off for convenience
- **String-only results**: Tools must return strings (Roo's protocol constraint)
- **No interactive input**: Tools can't prompt the user mid-execution
- **Cache invalidation**: Tool updates may require reloading the window
**vs. MCP:** [MCP](/features/mcp/overview) is for external services (search, APIs). Custom tools are for in-repo logic you control directly. MCP is more extensible; custom tools are lighter weight for project-specific actions.

44
apps/docs/docs/features/experimental/experimental-features.md Normal file
View file

@ -0,0 +1,44 @@
---
description: "Explore Roo Code's experimental features. Enable advanced capabilities that are still under development."
keywords:
- experimental features
- "Roo Code beta"
- "advanced features"
- "concurrent file edits"
- "feature flags"
---
# Experimental Features
Roo Code includes experimental features that are still under development. These features may be unstable, change significantly, or be removed in future versions. Use them with caution and be aware that they may not work as expected.
**Warning:** Experimental features may have unexpected behavior, including potential data loss or security vulnerabilities. Enable them at your own risk.
---
## Enabling Experimental Features
To enable or disable experimental features:
1. Open the Roo Code settings (`<Codicon name="gear" />` icon in the top right corner).
2. Go to the "Advanced Settings" section.
3. Find the "Experimental Features" section.
---
## Current Experimental Features
The following experimental features are currently available:
- [Custom Tools](/features/experimental/custom-tools) - Define TypeScript/JavaScript tools that Roo can call like built-in tools
- [Background Editing](/features/experimental/background-editing) - Work uninterrupted while Roo edits files in the background
- [Image Generation](/features/image-generation) - Generate images from text prompts and save them to your workspace
- [Run Slash Command](/advanced-usage/available-tools/run-slash-command) - Execute predefined slash commands for templated instructions and workflow automation
---
## Providing Feedback
If you encounter any issues with experimental features, or if you have suggestions for improvements, please report them on the [Roo Code GitHub Issues page](https://github.com/RooCodeInc/Roo-Code/issues).
Your feedback is valuable and helps us improve Roo Code!

148
apps/docs/docs/features/image-generation.md Normal file
View file

@ -0,0 +1,148 @@
---
description: Generate new images from text prompts or edit existing images in Roo Code using OpenRouter API. Transform, enhance, and save AI-processed images to your workspace with preview support.
keywords:
- image generation
- image editing
- text to image
- image transformation
- OpenRouter
- AI images
- experimental feature
- image creation
- prompt to image
- watercolor
- upscaling
- style transfer
---
# Image Generation
Generate new images from text prompts or edit existing images in your workspace. Save results to your project with preview in chat. This experimental feature requires an OpenRouter API key.
:::warning Experimental Feature
Image Generation is an experimental feature that requires enabling in settings and configuring an OpenRouter API key.
:::
---
## Key Features
- Create new images from text prompts using natural language
- Edit and transform existing images in your workspace
- Saves to your workspace at a path you choose; appropriate extension (.png or .jpg) is auto-added if missing
- Shows a preview of the generated/edited image in the conversation
- Currently uses Gemini 2.5 Flash Image Preview models via OpenRouter
- Simple on/off toggle under Experimental settings
---
## Use Cases
### Image Generation
**Before:** You had to copy prompts to an external site, download the result, then move it into your workspace.
**With this feature:** Ask Roo to generate an image, approve, pick a save location, and continue editing with the image already in your project.
### Image Editing
**Before:** Export image, upload to external editor, make changes, download, import back to project.
**With this feature:** Ask Roo to transform your existing image directly - it reads the file, applies your edits, and saves the result in your project.
---
## How It Works
When enabled, Roo sends your prompt (and optionally an existing image) to an image-capable model through OpenRouter. The generated or edited image returned by OpenRouter is saved to the path you specify inside your current workspace. Roo shows a preview in the chat and the file appears in your file explorer.
---
## Requirements
- OpenRouter account and API key
- Internet access
- An open, writable workspace folder
---
## Configuration
### 1. Enable Image Generation (Experimental)
- **Purpose:** Turns the feature on so Roo can create images on request
- **Default:** Off
- **Location:** Settings > Experimental
### 2. OpenRouter API Key
- **Purpose:** Authorizes image generation requests
- **Default:** Empty (required)
- **Get your key:** [https://openrouter.ai/keys](https://openrouter.ai/keys)
### 3. Image Generation Model
- **Purpose:** Selects which model to use for generation
- **Default:** Gemini 2.5 Flash Image Preview
- **Available Models:** Currently limited to Gemini 2.5 Flash Image Preview and its free variant
---
## Using Image Generation
1. In chat, ask Roo to generate an image and describe what you want (subject, style, lighting, composition).
2. Confirm the action when prompted. Roo may ask you to choose a save path (for example: `images/sunset.png`).
3. Roo generates the image and saves it. If you don't include an extension, the appropriate extension (.png or .jpg) is added based on the output format.
4. See the image preview in the chat and locate the file in your workspace.
---
## Editing Existing Images
Roo can also transform and edit existing images in your workspace:
1. Ask Roo to edit an image, describing the transformation you want
2. Specify both the input image path and where to save the result
3. Roo will apply your requested edits to the existing image
**Supported Input Formats**: PNG, JPG, JPEG, GIF, WEBP
**Example Requests**:
- "Transform `photos/portrait.jpg` into a watercolor painting and save as `art/watercolor-portrait.png`"
- "Upscale and enhance `images/logo.png` to higher resolution"
- "Apply a vintage filter to `screenshots/app.png`"
**Note**: Both the input image path and output path must be accessible (not blocked by `.rooignore`)
---
## Tips for Better Results
### Be Specific
Include these elements in your prompts:
- **Style:** artistic medium, art movement, or specific artist style
- **Mood:** emotional tone, atmosphere
- **Color palette:** specific colors or color schemes
- **Camera/lighting:** angle, perspective, lighting conditions
- **Aspect ratio:** dimensions or orientation
---
## Limitations
- Experimental feature; availability and model list are limited
- Currently limited to Gemini 2.5 Flash Image Preview models
- One image is produced per request
- Output formats supported: PNG or JPG
- Supported input formats for editing: PNG, JPG, JPEG, GIF, WEBP only
- Image paths must be accessible (not blocked by `.rooignore` restrictions)
- Usage may be subject to your OpenRouter plan limits and costs
---
## Status
This feature is experimental and may change or be removed in future versions. Provide feedback through [GitHub Issues](https://github.com/RooCodeInc/Roo-Code/issues).

77
apps/docs/docs/features/index.md Normal file
View file

@ -0,0 +1,77 @@
---
description: "Explore all Roo Code features including AI-powered coding assistance, multi-file editing, codebase indexing, MCP integration, custom modes, and experimental capabilities."
keywords:
- Roo Code features
- AI coding assistant
- code editing
- developer tools
- VS Code extension
- MCP integration
- custom modes
- experimental features
sidebar_label: "Features Overview"
---
# Roo Code Features
Discover the powerful features that make Roo Code your ultimate AI-powered coding assistant. From intelligent code editing to advanced integrations, Roo Code enhances your development workflow.
## Core Features
### Code Editing & Navigation
- [**Concurrent File Reads**](/features/concurrent-file-reads) - Read multiple files simultaneously for better context
- [**Code Actions**](/features/code-actions) - Quick fixes and refactoring suggestions
- [**Diagnostics Integration**](/features/diagnostics-integration) - Real-time error detection and resolution
### AI Enhancements
- [**Codebase Indexing**](/features/codebase-indexing) - Semantic search across your entire codebase
- [**Enhance Prompt**](/features/enhance-prompt) - Automatically improve your prompts for better results
- [**Suggested Responses**](/features/suggested-responses) - Context-aware follow-up suggestions
- [**Model Temperature**](/features/model-temperature) - Fine-tune AI creativity and consistency
### Workflow Management
- [**Task Todo List**](/features/task-todo-list) - Track progress on complex multi-step tasks
- [**Checkpoints**](/features/checkpoints) - Save and restore conversation states
- [**Boomerang Tasks**](/features/boomerang-tasks) - Reusable task templates
- [**Custom Modes**](/features/custom-modes) - Create specialized AI assistants for specific workflows
### Configuration & Customization
- [**API Configuration Profiles**](/features/api-configuration-profiles) - Manage multiple API configurations
- [**Custom Instructions**](/features/custom-instructions) - Personalize AI behavior
- [**Skills**](/features/skills) - Create reusable task-specific instruction packages
- [**Settings Management**](/features/settings-management) - Fine-tune Roo Code to your preferences
- [**.rooignore**](/features/rooignore) - Control file access and visibility
### Integration Features
- [**MCP (Model Context Protocol)**](/features/mcp/overview) - Connect to external tools and services
- [**Shell Integration**](/features/shell-integration) - Seamless terminal command execution
- [**Marketplace**](/features/marketplace) - Discover and share custom modes
### Productivity Tools
- [**Auto-Approving Actions**](/features/auto-approving-actions) - Streamline repetitive approvals
- [**Keyboard Shortcuts**](/features/keyboard-shortcuts) - Speed up common actions
- [**Intelligent Context Condensing**](/features/intelligent-context-condensing) - Optimize token usage
## Experimental Features
Push the boundaries with cutting-edge capabilities:
- [**Custom Tools**](/features/experimental/custom-tools) - Define TypeScript/JavaScript tools that Roo can call
- [**Concurrent File Edits**](/features/experimental/concurrent-file-edits) - Edit multiple files in a single operation
- [**More Experimental Features**](/features/experimental/experimental-features) - Explore features under development
## Additional Resources
- [**More Features**](/features/more-features) - Discover additional capabilities
- [**Tips & Tricks**](/tips-and-tricks) - Get the most out of Roo Code
- [**FAQ**](/faq) - Common questions answered
---
Ready to explore? Start with our [Getting Started Guide](/getting-started/installing) or dive into any feature that interests you!

173
apps/docs/docs/features/intelligent-context-condensing.mdx Normal file
View file

@ -0,0 +1,173 @@
---
description: Learn how Intelligent Context Condensing helps manage long conversations by summarizing earlier dialogue to prevent information loss when approaching context limits.
keywords:
- context condensing
- context window
- conversation management
- token optimization
- AI summarization
sidebar_label: 'Intelligent Context Condensing'
---
import Codicon from '@site/src/components/Codicon';
# Intelligent Context Condensing
The Intelligent Context Condensing feature helps manage long conversations by summarizing earlier parts of the dialogue. This prevents important information from being lost when the context window nears its limit. This feature is **enabled by default**.
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/9k8OAXlszak?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
<br />
---
## How It Works
As your conversation with Roo Code grows, it might approach the context window limit of the underlying AI model. When this happens, older messages would typically be removed to make space. Intelligent Context Condensing aims to prevent this abrupt loss by:
1. **Summarizing:** Using an AI model, it condenses earlier parts of the conversation.
2. **Retaining Essentials:** The goal is to reduce the overall token count while keeping the key information from the summarized messages.
3. **Maintaining Flow:** This allows the AI to have a more coherent understanding of the entire conversation, even very long ones.
4. **Slash command continuity:** Slash commands included in the first message are preserved across condensations.
**Important Considerations:**
* **Summarization Impact:** While original messages are preserved if you use [Checkpoints](/features/checkpoints) to rewind, the summarized version is what's used in ongoing LLM calls to keep the context manageable.
* **Cost:** The AI call to perform the summarization incurs a cost. This cost is included in the context condensing metrics displayed in the UI.
---
## Configuration
Intelligent Context Condensing is **enabled by default** and offers several configuration options:
1. Open Roo Code settings (<Codicon name="gear" /> icon in the top right corner of the Roo Code panel).
2. Navigate to the **Context Management** settings section.
3. Configure the available options:
- **Automatically trigger intelligent context condensing**: Enabled by default, this controls whether condensing happens automatically (found in "Context" settings)
- **Threshold to trigger intelligent context condensing**: A percentage slider (default 100%) that determines when condensing activates based on context window usage (found in "Context" settings)
- **Custom Context Condensing Prompt**: Customize the prompt Roo uses when condensing (found in "Context Management" settings)
<img src="/img/intelligent-context-condensing/intelligent-context-condensing.png" alt="Settings for Intelligent Context Condensing" width="600" />
*Intelligent Context Condensing configuration options: automatic triggering toggle, threshold slider, and custom prompt customization.*
---
## Controlling and Understanding Context Condensing
Roo Code provides several ways to control and understand the Intelligent Context Condensing feature:
#### Controlling context condensing
* **Automatic Threshold:** The threshold slider in "Context" settings allows you to define a percentage (e.g., 80%) of context window usage. Roo Code will attempt to condense the context automatically when the conversation reaches this level of capacity.
* **Custom Prompt:** Modify the prompt used for condensing to better suit your workflow or emphasize what should be preserved.
* **Manual Trigger:** A **Condense Context** button is available at the top of the task, positioned to the right of the context bar. This allows you to initiate the context condensing process at any time.
<img src="/img/intelligent-context-condensing/intelligent-context-condensing-1.png" alt="Manual Condense Context button in expanded task view" width="600" />
*The Manual Condense Context button (highlighted with a yellow arrow) is easily accessible for manual control.*
#### Understanding context condensing activity
* **Context Condensing Metrics:** When context condensing occurs, Roo Code displays:
* The context token counts before and after context condensing.
* The cost associated with the context condensing AI call.
* An expandable summary detailing what was condensed (this information is part of the `ContextCondenseRow` component visible in the chat history).
<img src="/img/intelligent-context-condensing/intelligent-context-condensing-2.png" alt="A completed context condense row showing token counts and cost" width="600" />
*Why this view matters: it’s your audit trail for what changed, how much it cost, and what Roo will carry forward.*
* **Visual Indicators:**
* A progress indicator ("Condensing context...") is shown in the chat interface while context condensing is active.
* The task header also displays the current context condensing status.
* The `ContextWindowProgress` bar offers a visual representation of token distribution, including current usage, space reserved for the AI's output, available space, and raw token numbers.
* **Interface Clarity:** The "Condense Context" button includes a tooltip explaining its function, available in all supported languages.
---
## Tips for Effective Context Condensing
#### Customizing the context condensing prompt
You can customize the context reduction prompt to better suit your specific domain or use case. This is particularly useful if you find that the default condensing process loses important information specific to your workflow.
To customize the prompt:
1. Go to Roo Code settings (<Codicon name="gear" /> icon)
2. Open **Context Management**
3. Find the **Custom Context Condensing Prompt** editor
4. Enter your custom prompt that instructs Roo on what must be preserved
For example, if you're working on a complex debugging session, you might add instructions like:
- "Always preserve error messages and stack traces in full"
- "Maintain all variable names and their last known values"
- "Keep track of all attempted solutions and their outcomes"
This customization ensures that the context condensing process retains the information most critical to your specific use case.
---
## Automatic Error Recovery
When Roo Code encounters context window limit errors, it now automatically recovers to keep your work flowing:
#### How error recovery works
1. **Error Detection**: Roo Code detects context window errors from multiple providers (OpenAI, Anthropic, and others)
2. **Automatic Truncation**: The system automatically reduces the context by 25%
3. **Retry Mechanism**: After truncation, Roo Code retries your request (up to the built-in retry limit)
4. **Continuation**: Roo retries without manual intervention
This automatic recovery ensures that:
- You don't lose work due to context limit errors
- Long conversations can continue smoothly
- The system intelligently manages context without requiring manual restarts
#### When recovery triggers
The automatic recovery activates when:
- The API returns a context window exceeded error
- The conversation approaches the maximum token limit
- Multiple providers report similar context-related errors
This feature works alongside Intelligent Context Condensing to provide multiple layers of context management, ensuring your conversations can continue even in challenging scenarios.
---
## Technical Implementation
#### Token counting
Roo Code uses a sophisticated token counting system that:
- Employs native token counting endpoints when available (e.g., Anthropic's API)
- Falls back to tiktoken estimation if API calls fail
- Provides accurate counting for different content types:
- Text content: Uses word-based estimation with punctuation and newline overhead
- Image content: Uses a conservative estimate of 300 tokens per image
- System prompts: Includes additional overhead for structural elements
#### Context window management
- By default, 30% of the context window is reserved (20% for model output and 10% as a safety buffer), leaving 70% available for conversation history.
- This reservation can be overridden by model-specific settings
- The system automatically calculates available space while maintaining this reservation
#### Error handling strategy
#### Why you can't use a different model/provider for condensing (and why that's good)
Condensing always uses your active conversation provider/model.
Using a different model to condense can degrade summary quality when the history includes tool calls, tool results, or other structured content. Keeping condensing on the same model/provider avoids "translation" errors between different tool/format expectations.
#### How the custom condense prompt is stored (advanced)
Your custom condense prompt is stored using the same support-prompt override mechanism as other prompt templates: `customSupportPrompts.CONDENSE`.
- If you had a legacy `customCondensingPrompt`, Roo migrates it into this location automatically.
- **Reset** clears the override so Roo falls back to the built-in default condense prompt.

259
apps/docs/docs/features/keyboard-shortcuts.md Normal file
View file

@ -0,0 +1,259 @@
---
description: Master keyboard navigation in Roo Code with customizable shortcuts, command execution, and prompt history navigation for efficient coding workflows.
keywords:
- keyboard shortcuts
- keyboard navigation
- roo-cline.acceptInput
- prompt history
- accessibility
- vim compatibility
sidebar_label: Keyboard Navigation
---
# Keyboard Navigation
The Roo Code interface supports keyboard navigation and shortcuts to streamline your workflow and reduce dependence on mouse interactions.
---
## Available Keyboard Commands
Roo Code offers keyboard commands to enhance your workflow. This page focuses on the `roo-cline.acceptInput` command, but here's a quick reference to all keyboard commands:
| Command | Description | Default Shortcut |
| ------------------------ | -------------------------------------------- | ------------------------------------------------ |
| `roo-cline.acceptInput` | Submit text or accept the primary suggestion | None (configurable) |
| `roo-cline.focusInput` | Focus the Roo input box | None (configurable) |
| `roo-cline.openInNewTab` | Open Roo Code in a new editor tab | None (via Command Palette) |
| Add to Context | Add selected code to Roo's context | macOS: Cmd+K Cmd+A; Windows/Linux: Ctrl+K Ctrl+A |
| Arrow Up/Down | Navigate through prompt history | Built-in |
### Key Benefits of Keyboard Commands
- **Keyboard-Driven Interface**: Submit text or select the primary suggestion button without mouse interaction
- **Improved Accessibility**: Essential for users with mobility limitations or those who experience discomfort with mouse usage
- **Vim/Neovim Compatibility**: Supports seamless transitions for developers coming from keyboard-centric environments
- **Workflow Efficiency**: Reduces context switching between keyboard and mouse during development tasks
---
## roo-cline.acceptInput Command
The `roo-cline.acceptInput` command lets you submit text or accept suggestions with keyboard shortcuts instead of clicking buttons or pressing Enter in the input area.
### What It Does
The `roo-cline.acceptInput` command is a general-purpose input submission command. When triggered, it:
- Submits your current text or image input when in the text input area (equivalent to pressing Enter)
- Clicks the primary (first) button when action buttons are visible (such as confirm/cancel buttons or any other action buttons)
### Detailed Setup Guide
#### Method 1: Using the VS Code UI
1. Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P` on Mac)
2. Type "Preferences: Open Keyboard Shortcuts"
3. In the search box, type "roo-cline.acceptInput"
4. Locate "Roo: Accept Input/Suggestion" in the results
5. Click the + icon to the left of the command
6. Press your desired key combination (e.g., `Ctrl+Enter` or `Alt+Enter`)
7. Press Enter to confirm
#### Method 2: Editing keybindings.json directly
1. Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P` on Mac)
2. Type "Preferences: Open Keyboard Shortcuts (JSON)"
3. Add the following entry to the JSON array:
```json
{
"key": "ctrl+enter", // or your preferred key combination
"command": "roo-cline.acceptInput",
"when": "view == roo-cline.SidebarProvider || activeWebviewPanelId == roo-cline.TabPanelProvider"
}
```
Scoped examples:
- Sidebar Roo view only:
```json
{
"key": "ctrl+enter",
"command": "roo-cline.acceptInput",
"when": "view == roo-cline.SidebarProvider"
}
```
- Editor Roo tab only:
```json
{
"key": "ctrl+enter",
"command": "roo-cline.acceptInput",
"when": "activeWebviewPanelId == roo-cline.TabPanelProvider"
}
```
#### Recommended Key Combinations
Choose a key combination that doesn't conflict with existing VS Code shortcuts:
- `Alt+Enter` - Easy to press while typing
- `Ctrl+Space` - Familiar for those who use autocomplete
- `Ctrl+Enter` - Intuitive for command execution
- `Alt+A` - Mnemonic for "Accept"
## Add to Context Shortcut
- Default: macOS: Cmd+K Cmd+A; Windows/Linux: Ctrl+K Ctrl+A
- Requires: when condition `editorTextFocus && editorHasSelection`
- Focus does not change automatically. To continue typing immediately, use "Roo: Focus Input" (`roo-cline.focusInput`) or click into the Roo panel.
:::note Redo Shortcut Restored
The standard Redo shortcut (macOS: Cmd+Y; Windows/Linux: Ctrl+Y) remains unchanged and is available for its usual function in VS Code.
:::
### Practical Use Cases
#### Quick Development Workflows
- **Text Submission**: Send messages to Roo without moving your hands from the keyboard
- **Action Confirmations**: Accept operations like saving files, running commands, or applying diffs
- **Multi-Step Processes**: Move quickly through steps that require confirmation or input
- **Consecutive Tasks**: Chain multiple tasks together with minimal interruption
#### Keyboard-Centric Development
- **Vim/Neovim Workflows**: If you're coming from a Vim/Neovim background, maintain your keyboard-focused workflow
- **IDE Integration**: Use alongside other VS Code keyboard shortcuts for a seamless experience
- **Code Reviews**: Quickly accept suggestions when reviewing code with Roo
- **Documentation Writing**: Submit text and accept formatting suggestions when generating documentation
#### Accessibility Use Cases
- **Hand Mobility Limitations**: Essential for users who have difficulty using a mouse
- **Repetitive Strain Prevention**: Reduce mouse usage to prevent or manage repetitive strain injuries
- **Screen Reader Integration**: Works well with screen readers for visually impaired users
- **Voice Control Compatibility**: Can be triggered via voice commands when using voice control software
### Accessibility Benefits
The `roo-cline.acceptInput` command was designed with accessibility in mind:
- **Reduced Mouse Dependence**: Complete entire workflows without reaching for the mouse
- **Reduced Physical Strain**: Helps users who experience discomfort or pain from mouse usage
- **Alternative Input Method**: Supports users with mobility impairments who rely on keyboard navigation
- **Workflow Optimization**: Particularly valuable for users coming from keyboard-centric environments like Vim/Neovim
### Keyboard-Centric Workflows
Here are some complete workflow examples showing how to effectively use keyboard shortcuts with Roo:
#### Development Workflow Example
1. Open VS Code and navigate to your project
2. Open Roo via the sidebar
3. Type your request: "Create a REST API endpoint for user registration"
4. When Roo asks for framework preferences, use your `roo-cline.acceptInput` shortcut to select the first suggestion
5. Continue using the shortcut to accept code generation suggestions
6. When Roo offers to save the file, use the shortcut again to confirm
7. Use VS Code's built-in shortcuts to navigate through the created files
#### Code Review Workflow
1. Select code you want to review and use VS Code's "Copy" command
2. Ask Roo to review it: "Review this code for security issues"
3. As Roo asks clarifying questions about the code context, use your shortcut to accept suggestions
4. When Roo provides improvement recommendations, use the shortcut again to accept implementation suggestions
### Troubleshooting
| Issue | Solution |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shortcut doesn't work | Ensure Roo is focused (click in the Roo panel first) |
| Wrong suggestion selected | The command always selects the first (primary) button; use mouse if you need a different option |
| Conflicts with existing shortcuts | Try a different key combination in VS Code keyboard settings |
| No visual feedback when used | This is normal - the command silently activates the function without visual confirmation |
| Shortcut works inconsistently | Make sure the `when` clause is properly configured (use `view == roo-cline.SidebarProvider` or `activeWebviewPanelId == roo-cline.TabPanelProvider`) |
### Technical Implementation
The `roo-cline.acceptInput` command is implemented as follows:
- Command registered as `roo-cline.acceptInput` with display title "Roo: Accept Input/Suggestion" in the command palette
- When triggered, it sends an "acceptInput" message to the active Roo webview
- The webview determines the appropriate action based on the current UI state:
- Clicks the primary action button if action buttons are visible and enabled
- Sends the message if the text area is enabled and contains text/images
- No default key binding - users assign their preferred shortcut
### Limitations
- Works only when the Roo interface is active
- Has no effect if no inputs or suggestions are currently available
- Prioritizes the primary (first) button when multiple options are shown
---
## Command Line Style Prompt History Navigation
Navigate your prompt history with a terminal-like experience using the arrow keys. This feature makes it easy to reuse and refine previous prompts, whether from your current conversation or past tasks.
### Key Features
- **Up/Down Arrows**: Cycle through previous prompts.
- **Context-Aware**: Switches between conversation and task history.
- **Preserves Input**: Remembers what you were typing.
### Why This Matters
**Before**: Reusing a prompt meant scrolling up, copying, and pasting.
- Tedious and slow
- Easy to lose your place
- Interrupted your workflow
**With Prompt History Navigation**: Quickly access past prompts without leaving the keyboard.
### How it Works
The navigation is designed to be intuitive and adapt to your current context.
#### In an Active Conversation
- **Arrow Up**: Shows the last prompt you sent. Keep pressing to go further back in the conversation.
- **Arrow Down**: Moves forward through the conversation history, eventually returning to the text you were typing.
#### Starting a New Chat
- **Arrow Up**: Shows the most recent prompt from your task history in the current workspace.
- **Arrow Down**: Moves forward through your task history.
#### Edge Cases
- If you start typing while navigating, the history is dismissed, and your new text is preserved.
- Navigation only works when your cursor is on the first or last line of the input box to avoid interfering with multi-line editing.
### Configuration
This feature is enabled by default. There are no settings to configure.
### Benefits
- **Faster Workflow**: Reuse prompts without using the mouse.
- **Better Context**: Easily access and build upon previous interactions.
- **Less Interruption**: Stay focused on the task at hand.
### Common Questions
**"Why doesn't anything happen when I press the up arrow?"**
- You might be in the middle of a multi-line prompt. The cursor must be on the first line.
- There might be no history available for the current context.
**"What's the difference between conversation and task history?"**
- **Conversation history** includes prompts from your current, active chat session.
- **Task history** includes the initial prompts from all previous tasks in your current workspace.

175
apps/docs/docs/features/marketplace.mdx Normal file
View file

@ -0,0 +1,175 @@
---
description: Discover and install community-contributed MCP servers and custom modes from the Roo Code Marketplace to extend your AI coding assistant's capabilities.
keywords:
- Roo Code Marketplace
- MCP servers
- custom modes
- extensions
- community tools
- AI integrations
---
import Codicon from '@site/src/components/Codicon';
# Roo Code Marketplace
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/WatooxMlW0U?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
<div style={{ marginTop: '20px' }}></div>
---
## Overview
The Roo Code Marketplace is a central hub for discovering and installing community-contributed extensions, known as MCPs (Model Context Protocol) and Modes. It allows you to easily extend the functionality of Roo Code to fit your specific needs and workflows.
### Key Features
- **Discoverability**: Browse a curated list of MCPs and Modes.
- **Simple Installation**: Install and remove items with a single click.
- **Community-Driven**: Access a growing collection of extensions from the Roo Code community.
- **Project & Global Scopes**: Install items for a specific project or for all your projects.
---
## Getting Started
The Roo Code Marketplace is available directly within the Roo Code extension in VS Code. Access it by clicking the marketplace icon <Codicon name="extensions" /> in the top menu bar.
---
## Marketplace Items
The marketplace offers two types of items:
### MCPs (Model Context Protocol)
MCPs allow Roo Code to connect to and interact with various AI models, APIs, and other external tools. By installing an MCP, you can configure Roo Code to use different language models (like those from OpenAI, Anthropic, or others) or to integrate with other services. Learn more about [What is MCP?](/features/mcp/what-is-mcp) and [how to use MCP in Roo Code](/features/mcp/using-mcp-in-roo).
<img src="/img/marketplace/marketplace-1.png" alt="MCP tab showing available MCPs with install and remove buttons" width="500" />
### Modes
Modes are custom sets of instructions and rules that tailor Roo Code's behavior for specific tasks. For example, you might find a "React Component" mode that is optimized for creating React components, or a "Documentation Writer" mode for writing technical documentation. Learn more about [using modes](/basic-usage/using-modes) and [creating custom modes](/features/custom-modes).
<img src="/img/marketplace/marketplace-4.png" alt="Modes tab showing available modes" width="500" />
---
## Installation Scope
When you install an item from the marketplace, you can choose to install it at the project level or the global level.
### Project Installation
- **Scope**: The item is only available within the current VS Code workspace (your project).
- **Configuration File**:
- **MCPs**: [`.roo/mcp.json`](/features/mcp/using-mcp-in-roo#configuring-mcp-servers) in the root of your project.
- **Modes**: [`.roomodes`](/features/custom-modes#3-manual-configuration-yaml--json) in the root of your project.
- **Use Case**: This is useful when an item is specific to a particular project's needs or when you want to share a project-specific configuration with your team.
### Global Installation
- **Scope**: The item is available across all your VS Code workspaces.
- **Configuration File**:
- **MCPs**: [`mcp_settings.json`](/features/mcp/using-mcp-in-roo#configuring-mcp-servers) in the Roo Code extension's global settings directory.
- **Modes**: [`custom_modes.yaml`](/features/custom-modes) in the Roo Code extension's global settings directory.
- **Use Case**: This is ideal for items that you want to use in all your projects, such as a favorite Mode or a commonly used MCP.
---
## Using the Marketplace
### Browsing and Filtering
You can browse all available items in the marketplace view. To find specific items:
- **Search**: Use the search bar to find items by name or description.
- **Filter by Type**: Show only MCPs or only Modes.
- **Filter by Tags**: Find items related to specific technologies or tasks.
- **Show Installed Only**: Use the "Installed" checkbox to filter the view to show only items you've already installed, making it easier to manage and review your installed extensions.
The "Show installed only" filter is particularly useful when:
- You want to quickly see what MCPs or modes you have installed
- You need to manage or remove installed items
- You're reviewing your project or global configurations
### Installing an Item
1. Find the item you want to install.
2. Click the "Install" button.
3. Choose whether to install it for the current **Project** or **Globally**.
#### Installing MCPs
<img src="/img/marketplace/marketplace-3.png" alt="MCP installation modal showing installation scope and method options" width="500" />
For MCPs, you may also need to:
- Select an installation method (NPX or Docker)
- Provide additional parameters when prompted (see [Parameterized MCPs](#parameterized-mcps))
#### Installing Modes
<img src="/img/marketplace/marketplace-5.png" alt="Mode installation modal showing installation scope options" width="500" />
For Modes, simply select the installation scope and click Install.
5. Roo Code automatically adds the item to the appropriate configuration file. If the file doesn't exist, Roo Code will create it for you. The file is then opened for your review.
### Removing an Item
1. Find the installed item in the marketplace view (installed items show a "Remove" button).
2. Click the "Remove" button.
3. If the item is installed in both scopes, choose to remove from the current project or remove globally.
4. Roo Code removes the item from the corresponding configuration file.
**Note:** The "Remove" button is context-aware. If an item is installed in only one scope (e.g., just for the project), it will be a single-action button. The dropdown menu with "Remove from Project" and "Remove Globally" options only appears if the item is installed in both scopes.
**Important:** The removal is immediate after you click the button or select an option from the dropdown. There is no additional confirmation prompt.
### Parameterized MCPs
<img src="/img/marketplace/marketplace-6.png" alt="Parameterized MCP installation showing API key input and prerequisites" width="500" />
Some MCPs require specific information during installation, such as API keys or URLs. When installing these "parameterized" MCPs, you'll be prompted to:
- Review any prerequisites (like creating accounts or obtaining API keys)
- Enter required configuration values
- Select the installation method if applicable
This keeps sensitive information secure and makes configuration more flexible.
---
## Troubleshooting
### Installation Errors
- **Invalid YAML/JSON**: The configuration file (`.roomodes`, `.roo/mcp.json`, etc.) has a syntax error. To prevent data loss, Roo Code will not modify a corrupted configuration file. Please fix the syntax error before installing or removing items.
- **File Not Found**: Rare error - Roo Code automatically creates necessary configuration files.
### Item Not Working
If an installed item isn't working:
1. **Check the configuration file**: Verify the item was added correctly.
2. **Restart VS Code**: New configurations sometimes require a restart.
3. **Check prerequisites**: Review the item's description for any requirements.
4. **Check Roo Code logs**: Look for error messages in the Roo Code output panel.
---
## Related Documentation
### For MCPs
- [MCP Overview](/features/mcp/overview) - Comprehensive guide to Model Context Protocol
- [What is MCP?](/features/mcp/what-is-mcp) - Understanding the fundamentals
- [Using MCP in Roo Code](/features/mcp/using-mcp-in-roo) - Detailed configuration and usage guide
- [Recommended MCP Servers](/features/mcp/recommended-mcp-servers) - Curated list of tested servers
### For Modes
- [Using Modes](/basic-usage/using-modes) - Learn about built-in modes and how to switch between them
- [Custom Modes](/features/custom-modes) - Create and configure your own specialized modes

120
apps/docs/docs/features/mcp/mcp-vs-api.md Normal file
View file

@ -0,0 +1,120 @@
---
description: Learn the key differences between Model Context Protocol (MCP) and REST APIs. Understand why MCP is AI-native and how it enables stateful, contextual interactions.
keywords:
- MCP vs API
- Model Context Protocol
- REST API comparison
- AI protocols
- stateful connections
- tool discovery
sidebar_label: MCP vs API
---
# MCP vs REST APIs: A Fundamental Distinction
Comparing REST APIs to the Model Context Protocol (MCP) is a category error. They operate at different layers of abstraction and serve fundamentally different purposes in AI systems.
---
## Architectural Differences
| Feature | MCP | REST APIs |
| -------------------- | ---------------------------------------------------- | ------------------------------------------------- |
| State Management | **Stateful** - maintains context across interactions | **Stateless** - each request is independent |
| Connection Type | Persistent, bidirectional connections | One-way request/response |
| Communication Style | JSON-RPC based with ongoing sessions | HTTP-based with discrete requests |
| Context Handling | Context is intrinsic to the protocol | Context must be manually managed |
| Tool Discovery | Runtime discovery of available tools | Design-time integration requiring prior knowledge |
| Integration Approach | Runtime integration with dynamic capabilities | Design-time integration requiring code changes |
---
## Different Layers, Different Purposes
REST APIs and MCP serve different tiers in the technology stack:
1. **REST**: Low-level web communication pattern that exposes operations on resources
2. **MCP**: High-level AI protocol that orchestrates tool usage and maintains context
MCP often uses REST APIs internally, but abstracts them away for the AI. Think of MCP as middleware that turns discrete web services into a cohesive environment the AI can operate within.
---
## Context Preservation: Critical for AI Workflows
MCP's stateful design solves a key limitation of REST in AI applications:
- **REST Approach**: Each call is isolated, requiring manual context passing between steps
- **MCP Approach**: One conversation context persists across multiple tool uses
For example, an AI debugging a codebase can open a file, run tests, and identify errors without losing context between steps. The MCP session maintains awareness of previous actions and results.
---
## Dynamic Tool Discovery
MCP enables an AI to discover and use tools at runtime:
```json
// AI discovers available tools
{
"tools": [
{
"name": "readFile",
"description": "Reads content from a file",
"parameters": {
"path": { "type": "string", "description": "File path" }
}
},
{
"name": "createTicket",
"description": "Creates a ticket in issue tracker",
"parameters": {
"title": { "type": "string" },
"description": { "type": "string" }
}
}
]
}
```
This "plug-and-play" capability allows new tools to be added without redeploying or modifying the AI itself.
---
## Real-World Example: Multi-Tool Workflow
Consider a task requiring multiple services: "Check recent commits, create a JIRA ticket for the bug fix, and post to Slack."
**REST-based approach**:
- Requires separate integrations for Git, JIRA, and Slack APIs
- Needs custom code to manage context between calls
- Breaks if any service changes its API
**MCP-based approach**:
- One unified protocol for all tools
- Maintains context across the entire workflow
- New tools can be swapped in without code changes
---
## Why Roo Code Uses MCP
Roo Code leverages MCP to provide:
1. **Extensibility**: Add unlimited custom tools without waiting for official integration
2. **Contextual awareness**: Tools can access conversation history and project context
3. **Simplified integration**: One standard protocol rather than numerous API patterns
4. **Runtime flexibility**: Discover and use new capabilities on-the-fly
MCP creates a universal connector between Roo Code and external services, with REST APIs often powering those services behind the scenes.
---
## Conclusion: Complementary, Not Competing Technologies
MCP doesn't replace REST APIs - it builds upon them. REST excels at providing discrete services, while MCP excels at orchestrating those services for AI agents.
The critical distinction is that MCP is AI-native: it treats the model as a first-class user, providing the contextual, stateful interaction layer that AI agents need to function effectively in complex environments.

31
apps/docs/docs/features/mcp/overview.md Normal file
View file

@ -0,0 +1,31 @@
---
sidebar_label: MCP Overview
description: Learn about the Model Context Protocol (MCP) in Roo Code. Discover how to extend AI capabilities with custom tools, resources, and server integrations.
keywords:
- MCP
- Model Context Protocol
- Roo Code extensions
- custom tools
- MCP servers
- AI integrations
---
# Model Context Protocol (MCP)
The Model Context Protocol (MCP) is a standard for extending Roo Code's capabilities by connecting to external tools and services. MCP servers provide additional tools and resources that help Roo accomplish tasks beyond its built-in capabilities, such as accessing databases, custom APIs, and specialized functionality.
---
## MCP Documentation
This documentation is organized into several sections:
- [**Using MCP in Roo Code**](/features/mcp/using-mcp-in-roo) - Comprehensive guide to configuring, enabling, and managing MCP servers with Roo Code. Includes server settings, tool approval, and troubleshooting.
- [**What is MCP?**](/features/mcp/what-is-mcp) - Clear explanation of the Model Context Protocol, its client-server architecture, and how it enables AI systems to interact with external tools.
- [**STDIO, Streamable HTTP & SSE Transports**](/features/mcp/server-transports) - Detailed comparison of local (STDIO) and remote (Streamable HTTP & legacy SSE) transport mechanisms with deployment considerations for each approach.
- [**MCP vs API**](/features/mcp/mcp-vs-api) - Analysis of the fundamental distinction between MCP and REST APIs, explaining how they operate at different layers of abstraction for AI systems.
- [**Recommended MCP Servers**](/features/mcp/recommended-mcp-servers) - Curated list of tested and recommended MCP servers for Roo Code, including a setup guide for Context7.

130
apps/docs/docs/features/mcp/recommended-mcp-servers.md Normal file
View file

@ -0,0 +1,130 @@
---
description: Discover recommended MCP servers for Roo Code, including Context7. Learn how to install and configure MCP servers with step-by-step instructions.
keywords:
- MCP servers
- Context7
- Roo Code MCP
- MCP installation
- MCP configuration
- recommended servers
sidebar_label: Recommended MCP Servers
---
# Recommended MCP Servers
While Roo Code can connect to any Model Context Protocol (MCP) server that follows the specification, the community has already built several high-quality servers that work out-of-the-box. This page curates the servers we **actively recommend** and provides step-by-step setup instructions so you can get productive in minutes.
> We'll keep this list up-to-date. If you maintain a server you'd like us to consider, please open a pull-request.
---
## Context7
`Context7` is our first-choice general-purpose MCP server. It ships a collection of highly-requested tools, installs with a single command, and has excellent support across every major editor that speaks MCP.
### Why we recommend Context7
- **One-command install** – everything is bundled, no local build step.
- **Cross-platform** – runs on macOS, Windows, Linux, or inside Docker.
- **Actively maintained** – frequent updates from the Upstash team.
- **Rich toolset** – database access, web-search, text utilities, and more.
- **Open source** – released under the MIT licence.
---
## Installing Context7 in Roo Code
There are two common ways to register the server:
1. **Global configuration** – available in every workspace.
2. **Project-level configuration** – checked into version control alongside your code.
We'll cover both below.
### 1. Global configuration
1. Open the Roo Code **MCP settings** panel by clicking the <Codicon name="server" /> icon.
2. Click **Edit Global MCP**.
3. Paste the JSON below inside the `mcpServers` object and save.
```json
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
}
}
}
```
**Windows (cmd.exe) variant**
```json
{
"mcpServers": {
"context7": {
"type": "stdio",
"command": "cmd",
"args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"]
}
}
}
```
Also on **Windows (cmd)** you may need to invoke `npx` through `cmd.exe`:
<img src="/img/recommended-mcp-servers/context7-global-setup-fixed.png" alt="Adding Context7 to the global MCP settings" width="600" />
### 2. Project-level configuration
If you prefer to commit the configuration to your repository, create a file called `.roo/mcp.json` at the project root and add the same snippet:
```json
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp@latest"]
}
}
}
```
**Windows (cmd.exe) variant**
```json
{
"mcpServers": {
"context7": {
"type": "stdio",
"command": "cmd",
"args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"]
}
}
}
```
<img src="/img/recommended-mcp-servers/context7-project-setup-fixed.png" alt="Adding Context7 to a project-level MCP file" width="600" />
> When both global and project files define a server with the same name, **the project configuration wins**.
---
## Verifying the installation
1. Make sure **Enable MCP Servers** is turned on in the MCP settings panel.
2. You should now see **Context7** listed. Click the <Codicon name="activate" /> toggle to start it if it isn't already running.
3. Roo Code will prompt you the first time a Context7 tool is invoked. Approve the request to continue.
<img src="/img/recommended-mcp-servers/context7-running-fixed.png" alt="Context7 running in Roo Code" width="400" />
---
## Next steps
- Browse the list of tools shipped with Context7 in the server pane.
- Configure **Always allow** for the tools you use most to streamline your workflow.
- Want to expose your own APIs? Check out the [MCP server creation guide](/features/mcp/using-mcp-in-roo#enabling-or-disabling-mcp-server-creation).
Looking for other servers? Watch this page – we'll add more recommendations soon!

285
apps/docs/docs/features/mcp/server-transports.md Normal file
View file

@ -0,0 +1,285 @@
---
description: Comprehensive guide to MCP transport mechanisms in Roo Code. Compare STDIO, Streamable HTTP, and SSE transports for local and remote server deployments.
keywords:
- MCP transports
- STDIO transport
- Streamable HTTP
- SSE transport
- MCP deployment
- local vs remote MCP
sidebar_label: STDIO, Streamable HTTP & SSE Transports
---
# MCP Server Transports: STDIO, Streamable HTTP & SSE
Model Context Protocol (MCP) supports three primary transport mechanisms for communication between Roo Code and MCP servers: Standard Input/Output (STDIO), Streamable HTTP (the modern standard), and Server-Sent Events (SSE) (for legacy use). Each has distinct characteristics, advantages, and use cases.
---
## STDIO Transport
STDIO transport runs locally on your machine and communicates via standard input/output streams.
### How STDIO Transport Works
1. The client (Roo Code) spawns an MCP server as a child process
2. Communication happens through process streams: client writes to server's STDIN, server responds to STDOUT
3. Each message is delimited by a newline character
4. Messages are formatted as JSON-RPC 2.0
```
Client Server
| |
|---- JSON message ------>| (via STDIN)
| | (processes request)
|<---- JSON message ------| (via STDOUT)
| |
```
### STDIO Characteristics
- **Locality**: Runs on the same machine as Roo Code
- **Performance**: Very low latency and overhead (no network stack involved)
- **Simplicity**: Direct process communication without network configuration
- **Relationship**: One-to-one relationship between client and server
- **Security**: Inherently more secure as no network exposure
### When to Use STDIO
STDIO transport is ideal for:
- Local integrations and tools running on the same machine
- Security-sensitive operations
- Low-latency requirements
- Single-client scenarios (one Roo Code instance per server)
- Command-line tools or IDE extensions
### STDIO Implementation Example
```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
const server = new Server({ name: "local-server", version: "1.0.0" })
// Register tools...
// Use STDIO transport
const transport = new StdioServerTransport(server)
transport.listen()
```
---
## Streamable HTTP Transport
Streamable HTTP transport is the modern standard for remote MCP server communication, replacing the older HTTP+SSE transport. It operates over HTTP/HTTPS and allows for more flexible server implementations.
### How Streamable HTTP Transport Works
1. The server provides a single HTTP endpoint (MCP endpoint) that supports both POST and GET methods.
2. The client (Roo Code) sends requests to this MCP endpoint using HTTP POST.
3. The server processes the request and sends back a response.
4. Optionally, the server can use Server-Sent Events (SSE) over the same connection to stream multiple messages or notifications to the client. This allows for basic request-response interactions as well as more advanced streaming and server-initiated communication.
```
Client Server
| |
|---- HTTP POST /mcp_endpoint ---->| (client request)
| | (processes request)
|<--- HTTP Response / SSE Stream --| (server response / stream)
| |
```
### Streamable HTTP Characteristics
- **Modern Standard**: Preferred method for new remote MCP server implementations.
- **Remote Access**: Can be hosted on a different machine from Roo Code.
- **Scalability**: Can handle multiple client connections concurrently.
- **Protocol**: Works over standard HTTP/HTTPS.
- **Flexibility**: Supports simple request-response and advanced streaming.
- **Single Endpoint**: Uses a single URL path for all MCP communication.
- **Authentication**: Can use standard HTTP authentication mechanisms.
- **Backwards Compatibility**: Servers can maintain compatibility with older HTTP+SSE clients.
### When to Use Streamable HTTP
Streamable HTTP transport is ideal for:
- All new remote MCP server developments.
- Servers requiring robust, scalable, and flexible communication.
- Integrations that might involve streaming data or server-sent notifications.
- Public services or centralized tools.
- Replacing legacy SSE transport implementations.
### Streamable HTTP Implementation Example
Configuration in `settings.json`:
```json
{
"mcpServers": {
"StreamableHTTPMCPName": {
"type": "streamable-http",
"url": "http://localhost:8080/mcp"
}
}
}
```
For server-side implementation, refer to the MCP SDK documentation for `StreamableHTTPClientTransport`.
### Backwards Compatibility with HTTP+SSE
Clients and servers can maintain backwards compatibility with the deprecated HTTP+SSE transport (from protocol version 2024-11-05).
Servers wanting to support older clients should:
- Continue to host both the SSE (`/events`) and POST (`/message`) endpoints of the old transport, alongside the new “MCP endpoint” defined for the Streamable HTTP transport.
---
## SSE Transport (Legacy)
Server-Sent Events (SSE) transport is a legacy method for remote server communication over HTTP/HTTPS. For new implementations, **Streamable HTTP transport is recommended.** SSE remains available for compatibility with older MCP servers.
### How SSE Transport Works
1. The client (Roo Code) connects to the server's SSE endpoint via HTTP GET request
2. This establishes a persistent connection where the server can push events to the client
3. For client-to-server communication, the client makes HTTP POST requests to a separate endpoint
4. Communication happens over two channels:
- Event Stream (GET): Server-to-client updates
- Message Endpoint (POST): Client-to-server requests
```
Client Server
| |
|---- HTTP GET /events ----------->| (establish SSE connection)
|<---- SSE event stream -----------| (persistent connection)
| |
|---- HTTP POST /message --------->| (client request)
|<---- SSE event with response ----| (server response)
| |
```
### SSE Characteristics
- **Remote Access**: Can be hosted on a different machine from Roo Code
- **Scalability**: Can handle multiple client connections concurrently
- **Protocol**: Works over standard HTTP (no special protocols needed)
- **Persistence**: Maintains a persistent connection for server-to-client messages
- **Authentication**: Can use standard HTTP authentication mechanisms
### When to Use SSE
SSE transport is better for:
- Remote access across networks
- Multi-client scenarios
- Public services
- Centralized tools that many users need to access
- Integration with web services
### SSE Implementation Example
```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js"
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js"
import express from "express"
const app = express()
const server = new Server({ name: "remote-server", version: "1.0.0" })
// Register tools...
// Use SSE transport
const transport = new SSEServerTransport(server)
app.use("/mcp", transport.requestHandler())
app.listen(3000, () => {
console.log("MCP server listening on port 3000")
})
```
---
## Local vs. Hosted: Deployment Aspects
The choice between STDIO and SSE transports directly impacts how you'll deploy and manage your MCP servers.
### STDIO: Local Deployment Model
STDIO servers run locally on the same machine as Roo Code, which has several important implications:
- **Installation**: The server executable must be installed on each user's machine
- **Distribution**: You need to provide installation packages for different operating systems
- **Updates**: Each instance must be updated separately
- **Resources**: Uses the local machine's CPU, memory, and disk
- **Access Control**: Relies on the local machine's filesystem permissions
- **Integration**: Easy integration with local system resources (files, processes)
- **Execution**: Starts and stops with Roo Code (child process lifecycle)
- **Dependencies**: Any dependencies must be installed on the user's machine
#### Practical Example
A local file search tool using STDIO would:
- Run on the user's machine
- Have direct access to the local filesystem
- Start when needed by Roo Code
- Not require network configuration
- Need to be installed alongside Roo Code or via a package manager
### Streamable HTTP / SSE (Legacy): Hosted Deployment Model
Streamable HTTP (recommended) and legacy SSE servers can be deployed to remote servers and accessed over the network:
- **Installation**: Installed once on a server, accessed by many users
- **Distribution**: Single deployment serves multiple clients
- **Updates**: Centralized updates affect all users immediately
- **Resources**: Uses server resources, not local machine resources
- **Access Control**: Managed through authentication and authorization systems
- **Integration**: More complex integration with user-specific resources
- **Execution**: Runs as an independent service (often continuously)
- **Dependencies**: Managed on the server, not on user machines
#### Practical Example
A database query tool using SSE would:
- Run on a central server
- Connect to databases with server-side credentials
- Be continuously available for multiple users
- Require proper network security configuration
- Be deployed using container or cloud technologies
### Hybrid Approaches
Some scenarios benefit from a hybrid approach:
1. **STDIO with Network Access**: A local STDIO server that acts as a proxy to remote services
2. **SSE with Local Commands**: A remote SSE server that can trigger operations on the client machine through callbacks
3. **Gateway Pattern**: STDIO servers for local operations that connect to SSE servers for specialized functions
---
## Choosing Between Transports
| Consideration | STDIO | Streamable HTTP | SSE (Legacy) |
| -------------------- | -------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------- |
| **Location** | Local machine only | Local or remote | Local or remote |
| **Clients** | Single client | Multiple clients | Multiple clients |
| **Performance** | Lower latency | Higher latency (network overhead) | Higher latency (network overhead) |
| **Setup Complexity** | Simpler | More complex (requires HTTP server) | More complex (requires HTTP server, potentially two endpoints) |
| **Security** | Inherently secure | Requires explicit security measures | Requires explicit security measures |
| **Network Access** | Not needed | Required | Required |
| **Scalability** | Limited to local machine | Can distribute across network | Can distribute across network |
| **Deployment** | Per-user installation | Centralized installation | Centralized installation |
| **Updates** | Distributed updates | Centralized updates | Centralized updates |
| **Resource Usage** | Uses client resources | Uses server resources | Uses server resources |
| **Dependencies** | Client-side dependencies | Server-side dependencies | Server-side dependencies |
| **Recommendation** | Ideal for local, secure, single-client tools | **Modern standard for all new remote servers** | Legacy, for existing older servers |
---
## Configuring Transports in Roo Code
For detailed information on configuring STDIO, Streamable HTTP, and SSE (Legacy) transports in Roo Code, including example configurations, see the [Understanding Transport Types](/features/mcp/using-mcp-in-roo#understanding-transport-types) section in the Using MCP in Roo Code guide.

524
apps/docs/docs/features/mcp/using-mcp-in-roo.mdx Normal file
View file

@ -0,0 +1,524 @@
---
description: Complete guide to using Model Context Protocol (MCP) in Roo Code. Learn how to configure MCP servers, manage tools, and extend Roo Code's capabilities.
keywords:
- MCP
- Model Context Protocol
- MCP servers
- Roo Code integration
- external tools
- API integration
sidebar_label: Using MCP in Roo Code
---
# Using MCP in Roo Code
:::info Confused about MCP Servers?
An MCP (Model Context Protocol) server acts as a bridge, giving Roo Code access to a wider range of **tools** and external services like databases, APIs, or custom scripts. It uses a standard communication method, allowing Roo to leverage these external capabilities.
For a deeper dive, check out [What is MCP?](/features/mcp/what-is-mcp).
:::
Model Context Protocol (MCP) extends Roo Code's capabilities by connecting to external tools and services. This guide covers everything you need to know about using MCP with Roo Code.
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/VAbadUDhH5c?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
<br />
---
## Configuring MCP Servers
MCP server configurations can be managed at two levels:
1. **Global Configuration**: Stored in the `mcp_settings.json` file, accessible via VS Code settings (see below). These settings apply across all your workspaces unless overridden by a project-level configuration.
2. **Project-level Configuration**: Defined in a `.roo/mcp.json` file within your project's root directory. This allows you to set up project-specific servers and share configurations with your team by committing the file to version control. Roo Code automatically detects and loads this file if it exists.
**Precedence**: If a server name exists in both global and project configurations, the **project-level configuration takes precedence**.
### Editing MCP Settings Files
You can edit both global and project-level MCP configuration files directly from the Roo Code MCP settings view:
1. Click the <Codicon name="server" /> icon in the top navigation of the Roo Code pane.
<img src="/img/using-mcp-in-roo/using-mcp-in-roo-10.png" alt="MCP Servers interface in Roo Code" width="400" />
2. Scroll to the bottom of the MCP settings view.
3. Click the appropriate button:
* **`Edit Global MCP`**: Opens the global `mcp_settings.json` file.
* **`Edit Project MCP`**: Opens the project-specific `.roo/mcp.json` file. If this file doesn't exist, Roo Code will create it for you.
<img src="/img/using-mcp-in-roo/using-mcp-in-roo-9.png" alt="Edit Global MCP and Edit Project MCP buttons" width="600" />
Both files use a JSON format with a `mcpServers` object containing named server configurations:
```json
{
"mcpServers": {
"server1": {
"command": "python",
"args": ["/path/to/server.py"],
"env": {
"API_KEY": "your_api_key"
},
"alwaysAllow": ["tool1", "tool2"],
"disabled": false
}
}
}
```
*Example of MCP Server config in Roo Code (STDIO Transport)*
### Understanding Transport Types
MCP supports three transport types for server communication: STDIO for local servers, Streamable HTTP (recommended for new remote servers), and SSE (for legacy remote servers).
#### STDIO Transport
Used for local servers running on your machine:
* Communicates via standard input/output streams
* Lower latency (no network overhead)
* Better security (no network exposure)
* Simpler setup (no HTTP server needed)
* Runs as a child process on your machine
For more in-depth information about how STDIO transport works, see [STDIO Transport](/features/mcp/server-transports#stdio-transport).
STDIO configuration parameters:
* `command` (required): The executable to run (e.g., `node`, `python`, `npx`, or an absolute path).
* `args` (optional): An array of string arguments to pass to the command. You can reference system environment variables using `${env:VARIABLE_NAME}` syntax.
* `cwd` (optional): The working directory from which to launch the server process. If omitted, defaults to the first workspace folder path or the main process's working directory. Useful if the server script relies on relative paths.
* `env` (optional): An object containing environment variables to set for the server process.
* `alwaysAllow` (optional): An array of tool names from this server to automatically approve.
* `disabled` (optional): Set to `true` to disable this server configuration.
* `timeout` (optional): Per-server timeout override in seconds (1-3600). If not specified, uses the default of 60 seconds.
* `watchPaths` (optional): An array of file paths to watch. When any of these files change, the server will automatically restart.
* `disabledTools` (optional): An array of tool names to disable from this server. These tools will not be available for use even if the server provides them.
STDIO configuration example:
```json
{
"mcpServers": {
"local-server": {
"command": "node",
"args": ["server.js"],
"cwd": "/path/to/project/root", // Optional: Specify working directory
"env": {
"API_KEY": "your_api_key"
},
"alwaysAllow": ["tool1", "tool2"],
"disabled": false
}
}
}
```
#### Using System Environment Variables in Arguments
You can reference system-level environment variables within the `args` array using the `${env:VARIABLE_NAME}` syntax. This allows you to pass sensitive information like API keys or tokens from your system environment without hardcoding them in your configuration:
```json
{
"mcpServers": {
"github": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"GITHUB_PERSONAL_ACCESS_TOKEN=${env:GITHUB_PERSONAL_ACCESS_TOKEN}",
"ghcr.io/github/github-mcp-server"
],
"alwaysAllow": [
"get_pull_request"
]
}
}
}
```
In this example, `${env:GITHUB_PERSONAL_ACCESS_TOKEN}` will be replaced with the value of the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable from your system. This is particularly useful when:
- Working with Docker containers that need environment variables passed through
- Keeping sensitive credentials out of your configuration files
- Using the same configuration across different environments with different credentials
**Note:** The environment variable must exist in your system environment for this to work. You can set system environment variables through your operating system's settings or shell configuration files (e.g., `.bashrc`, `.zshrc`, or Windows Environment Variables).
#### Streamable HTTP Transport
This is the **modern standard** for remote servers accessed over HTTP/HTTPS, offering more flexibility and replacing the legacy SSE transport for new implementations.
* Communicates via HTTP POST/GET to a single MCP endpoint
* Optionally uses Server-Sent Events (SSE) for streaming
* Can be hosted on a different machine
* Supports multiple client connections
* Requires network access
* Allows centralized deployment and management
For more in-depth information about how Streamable HTTP transport works, see [Streamable HTTP Transport](/features/mcp/server-transports#streamable-http-transport).
Streamable HTTP configuration parameters:
* `type` (required): Must be set to `"streamable-http"`.
* `url` (required): The full URL of the remote MCP server's single endpoint (e.g., `https://your-server.com/mcp`).
* `headers` (optional): An object containing custom HTTP headers to send with requests (e.g., for authentication tokens).
* `alwaysAllow` (optional): An array of tool names from this server to automatically approve.
* `disabled` (optional): Set to `true` to disable this server configuration.
* `timeout` (optional): Per-server timeout override in seconds (1-3600). If not specified, uses the default of 60 seconds.
* `disabledTools` (optional): An array of tool names to disable from this server. These tools will not be available for use even if the server provides them.
Streamable HTTP configuration example:
```json
{
"mcpServers": {
"modern-remote-server": {
"type": "streamable-http",
"url": "https://your-modern-server.com/api/mcp-endpoint",
"headers": {
"X-API-Key": "your-secure-api-key"
},
"alwaysAllow": ["newToolA", "newToolB"],
"disabled": false
}
}
}
```
#### SSE Transport (Legacy)
Used for older remote servers accessed over HTTP/HTTPS. **For new remote server implementations, [Streamable HTTP Transport](#streamable-http-transport) is recommended.**
* Communicates via Server-Sent Events protocol (typically requires separate endpoints for client-to-server and server-to-client communication)
* Can be hosted on a different machine
* Supports multiple client connections
* Requires network access
* Allows centralized deployment and management
For more in-depth information about how legacy SSE transport works, see [SSE Transport (Legacy)](/features/mcp/server-transports#sse-transport-legacy).
SSE (Legacy) configuration parameters:
* `type` (required for URL-based configs): Must be set to `"sse"` when using a `url` for an SSE server. For stdio configs (those using `command`), `type` defaults to `"stdio"` and can be omitted. For any URL-based config, omitting `type` will cause an immediate error—Roo Code cannot infer the transport type from a `url` alone.
* `url` (required): The base URL for the remote MCP server. For legacy SSE, this usually implies separate paths like `/events` (for SSE stream) and `/message` (for POST requests) will be derived or expected by the server.
* `headers` (optional): An object containing custom HTTP headers to send with requests (e.g., for authentication tokens).
* `alwaysAllow` (optional): An array of tool names from this server to automatically approve.
* `disabled` (optional): Set to `true` to disable this server configuration.
* `timeout` (optional): Per-server timeout override in seconds (1-3600). If not specified, uses the default of 60 seconds.
* `disabledTools` (optional): An array of tool names to disable from this server. These tools will not be available for use even if the server provides them.
SSE (Legacy) configuration example:
```json
{
"mcpServers": {
"legacy-remote-server": {
"type": "sse", // Explicitly define as SSE
"url": "https://your-legacy-server-url.com/mcp-base", // Base URL
"headers": {
"Authorization": "Bearer your-legacy-token"
},
"alwaysAllow": ["oldToolX"],
"disabled": false
}
}
}
```
## Enabling or Disabling MCP Servers
Disabling your MCP Servers here will remove all MCP related logic and definitions from your system prompt, reducing your token usage. This will prevent Roo Code from connecting to any MCP servers, and the `use_mcp_tool` and `access_mcp_resource` tools will not be available. Check this off if you don't intend to use MCP Servers. This is on by default.
1. Click the <Codicon name="server" /> icon in the top navigation of the Roo Code pane
2. Check/Uncheck `Enable MCP Servers`
<img src="/img/using-mcp-in-roo/using-mcp-in-roo-2.png" alt="Enable MCP Servers toggle" width="400" />
---
## Enabling or Disabling MCP Server Creation
Disabling your MCP Server Creation here will just remove the instructions from your system prompt that Roo Code uses to write MCP servers while not removing the context related to operating them. This reduces token usage. This is on by default.
1. Click the <Codicon name="server" /> icon in the top navigation of the Roo Code pane
2. Check/Uncheck `Enable MCP Server Creation`
<img src="/img/using-mcp-in-roo/using-mcp-in-roo-3.png" alt="Enable MCP Server Creation toggle" width="400" />
---
## How to Use Roo to Create an MCP Server
If you need a specific tool or capability that isn't available through existing MCP servers, you can ask Roo Code to build a new one for you.
**Prerequisite:** Ensure the **[Enable MCP Server Creation](#enabling-or-disabling-mcp-server-creation)** setting is checked ON in the MCP settings panel. If this is disabled, Roo will not have the necessary instructions to build a server.
**How to Initiate:**
1. **Make a Request:** Clearly ask Roo for the new tool or capability. For example:
* "Create an MCP tool that gets the current price of Bitcoin."
* "I need a tool that connects to my company's internal user database via its API."
* "Build an MCP server to interact with the GitHub Gist API."
2. **Roo's Process (Simplified):** Once you make the request (and the setting is enabled), Roo will:
* Fetch internal instructions for server creation.
* Scaffold a basic server project (usually TypeScript) in the default MCP directory (e.g., `~/Documents/Cline/MCP` on macOS) unless you specify otherwise.
* Write the code to implement the requested tool, including handling necessary API calls.
* **Handle Secrets:** If the tool requires API keys or other credentials, Roo will ask you for them using the [`ask_followup_question`](/advanced-usage/available-tools/ask-followup-question) tool to ensure they are configured securely as environment variables for the server.
* **Configure:** Automatically add the new server's configuration to your global `mcp_settings.json` or project `.roo/mcp.json` file.
* **Activate:** Attempt to connect to the newly configured server so its tools are immediately available.
3. **Outcome:** If successful, Roo will confirm the creation, and the new server and its tools will appear in your MCP server list, ready for use.
This feature allows you to tailor Roo's capabilities by having it build the specific integrations you need directly from your requests. For a deeper look into the internal mechanics, see the [Tool Calling Mechanism](/advanced-usage/available-tools/tool-use-overview#tool-calling-mechanism).
---
## Managing Individual MCP Servers
<img src="/img/using-mcp-in-roo/using-mcp-in-roo-8.png" alt="Example of a configuration pane for a MCP Server" width="400" />
Each MCP server has its own configuration panel where you can modify settings, manage tools, and control its operation. To access these settings:
1. Click the <Codicon name="server" /> icon in the top navigation of the Roo Code pane
2. Locate the MCP server you want to manage in the list
<img src="/img/using-mcp-in-roo/using-mcp-in-roo-4.png" alt="List of MCP Servers" width="400" />
### Deleting a Server
1. Press the <Codicon name="trash" /> next to the MCP server you would like to delete
2. Press the `Delete` button on the confirmation box
<img src="/img/using-mcp-in-roo/using-mcp-in-roo-5.png" alt="Delete confirmation box" width="400" />
### Restarting a Server
1. Press the <Codicon name="refresh" /> button next to the MCP server you would like to restart
### Enabling or Disabling a Server
1. Press the <Codicon name="activate" /> toggle switch next to the MCP server to enable/disable it
### Network Timeout
To set the maximum time to wait for a response after a tool call to the MCP server:
1. Click the `Network Timeout` pulldown at the bottom of the individual MCP server's config box and change the time. Default is 60 seconds (1 minute) but it can be set between 1 second and 3600 seconds (1 hour).
<img src="/img/using-mcp-in-roo/using-mcp-in-roo-6.png" alt="Network Timeout pulldown" width="400" />
### Auto Approve Tools
MCP tool auto-approval works on a per-tool basis and is disabled by default. To configure auto-approval:
1. First enable the global "Use MCP servers" auto-approval option in [auto-approving-actions](/features/auto-approving-actions)
2. In the MCP server settings, locate the specific tool you want to auto-approve
3. Check the `Always allow` checkbox next to the tool name
<img src="/img/using-mcp-in-roo/using-mcp-in-roo-7.png" alt="Always allow checkbox for MCP tools" width="120" />
When enabled, Roo Code will automatically approve this specific tool without prompting. Note that the global "Use MCP servers" setting takes precedence - if it's disabled, no MCP tools will be auto-approved.
---
## Finding and Installing MCP Servers
Roo Code does not come with any pre-installed MCP servers. You'll need to find and install them separately.
* **Community Repositories:** Check for community-maintained lists of MCP servers on GitHub
* **Ask Roo:** You can ask Roo Code to help you find or even create MCP servers (when "[Enable MCP Server Creation](#enabling-or-disabling-mcp-server-creation)" is enabled)
* **Build Your Own:** Create custom MCP servers using the SDK to extend Roo Code with your own tools
For full SDK documentation, visit the [MCP GitHub repository](https://github.com/modelcontextprotocol/).
---
## Using MCP Tools in Your Workflow
After configuring an MCP server, Roo automatically detects its available tools and resources. Effectively leveraging these tools involves understanding the core interaction steps and, crucially, how Roo interprets the tools you provide.
### Core Workflow Steps
Your interaction with MCP tools typically follows this sequence:
#### 1. Initiate a Task
Begin by typing your request in the Roo Code chat interface.
#### 2. Tool Identification by Roo
Roo analyzes your request to determine if an available MCP tool can assist. This stage is highly dependent on the quality of your MCP tool definitions.
##### The Critical Role of Descriptions
Roo's ability to:
* Identify the *correct* tool for the job,
* Understand how to structure the necessary parameters, and
* Avoid misinterpreting a tool's capabilities,
all hinge on clear, concise, and informative descriptions for both the tools themselves and their parameters. Vague or missing information, especially for parameters, can significantly hinder Roo's ability to select or use a tool effectively.
For instance, a request like "Analyze the performance of my API" might lead Roo to consider an MCP tool designed for API endpoint testing. Whether Roo successfully identifies and utilizes this tool as intended is directly influenced by the quality of its description.
##### Best Practices for Defining MCP Tools
To ensure Roo can leverage your MCP tools efficiently, consider the following when defining them in your server:
* **Tool Name:** Choose a descriptive and unambiguous name that clearly indicates the tool's primary function.
* **Tool Description:** Provide a comprehensive summary of what the tool does, its purpose, and any important context or prerequisites for its use. Explain the outcome or result of using the tool.
* **Parameter Descriptions:** This is critical. For each parameter:
* Clearly state its purpose and what kind of data it expects (e.g., "User ID for lookup," "File path to process," "Search query string").
* Specify any formatting requirements, constraints, or an example of a valid value if applicable.
* Indicate if the parameter is optional or required (though the MCP schema usually handles this, a note can be helpful).
* **Clarity for the AI:** Write descriptions as if you are explaining the tool to another developer (or an AI). The more context Roo has, the better it can integrate the tool into its problem-solving workflows. If a tool is intended to be used in a specific sequence or in conjunction with other tools, mentioning this can also be beneficial.
* **Augment with Custom Instructions:** Beyond the descriptions embedded in the MCP server, you can further guide Roo's usage of specific MCP tools by providing [Custom Instructions](/features/custom-instructions). This allows you to define preferred approaches, outline complex workflows involving multiple tools, or specify when a particular MCP tool should be prioritized or avoided.
#### 3. Tool Invocation
If Roo, guided by the tool descriptions, identifies a suitable tool, it will propose its use. You then approve this (unless [auto-approval](#auto-approve-tools) is configured for trusted tools).
### Maximizing Synergy with MCP Servers
By investing effort in crafting detailed descriptions and potentially augmenting them with custom instructions, you significantly improve the synergy between Roo Code and your MCP servers. This unlocks their full potential for more reliable and efficient task completion.
---
## Troubleshooting MCP Servers
Common issues and solutions:
* **Server Not Responding:** Check if the server process is running and verify network connectivity
* **Permission Errors:** Ensure proper API keys and credentials are configured in your `mcp_settings.json` (for global settings) or `.roo/mcp.json` (for project settings).
* **Tool Not Available:** Confirm the server is properly implementing the tool and it's not disabled in settings
* **Slow Performance:** Try adjusting the network timeout value for the specific MCP server
---
## Platform-Specific MCP Configuration Examples
### Windows Configuration Example
When setting up MCP servers on Windows, you'll need to use the Windows Command Prompt (`cmd`) to execute commands. Here's an example of configuring a Puppeteer MCP server on Windows:
```json
{
"mcpServers": {
"puppeteer": {
"command": "cmd",
"args": [
"/c",
"npx",
"-y",
"@modelcontextprotocol/server-puppeteer"
]
}
}
}
```
This Windows-specific configuration:
- Uses the `cmd` command to access the Windows Command Prompt
- Uses `/c` to tell cmd to execute the command and then terminate
- Uses `npx` to run the package without installing it permanently
- The `-y` flag automatically answers "yes" to any prompts during installation
- Runs the `@modelcontextprotocol/server-puppeteer` package which provides browser automation capabilities
### macOS and Linux Configuration Example
When setting up MCP servers on macOS or Linux, you can use a simpler configuration since you don't need the Windows Command Prompt. Here's an example of configuring a Puppeteer MCP server on macOS or Linux:
```json
{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-puppeteer"
]
}
}
}
```
This configuration:
- Directly uses `npx` without needing a shell wrapper
- Uses the `-y` flag to automatically answer "yes" to any prompts during installation
- Runs the `@modelcontextprotocol/server-puppeteer` package which provides browser automation capabilities
The same approach can be used for other MCP servers on Windows, adjusting the package name as needed for different server types.
---
## Runtime Version Manager Configuration
When working with multiple versions of programming languages or runtimes, you may use version managers like [asdf](https://asdf-vm.com/) or [mise](https://mise.jdx.dev/) (formerly rtx). These tools help manage multiple runtime versions on a single system. Here's how to configure MCP servers to work with these version managers:
### mise Configuration Example
[mise](https://mise.jdx.dev/) is a fast, modern runtime version manager that can be used to specify which version of Node.js, Python, or other runtimes to use for your MCP server:
```json
{
"mcpServers": {
"mcp-batchit": {
"command": "mise",
"args": [
"x",
"--",
"node",
"/Users/myself/workspace/mcp-batchit/build/index.js"
],
"disabled": false,
"alwaysAllow": [
"search",
"batch_execute"
]
}
}
}
```
This configuration:
- Uses the `mise` command to manage runtime versions
- The `x` subcommand executes a command with the configured runtime version
- The `--` separates mise arguments from the command to run
- Runs `node` with the specific version configured in your mise settings
- Points to the MCP server JavaScript file
- Automatically allows the "search" and "batch_execute" tools
### asdf Configuration Example
[asdf](https://asdf-vm.com/) is a popular tool for managing multiple runtime versions. Here's how to configure an MCP server to use a specific Node.js version managed by asdf:
```json
{
"mcpServers": {
"appsignal": {
"command": "/Users/myself/.asdf/installs/nodejs/22.2.0/bin/node",
"args": [
"/Users/myself/Code/Personal/my-mcp/build/index.js"
],
"env": {
"ASDF_NODE_VERSION": "22.2.0"
},
"disabled": false,
"alwaysAllow": []
}
}
}
```
This configuration:
- Directly references the Node.js executable from the asdf installations directory
- Sets the `ASDF_NODE_VERSION` environment variable to ensure consistent version use
- Points to the MCP server JavaScript file
Using version managers ensures that your MCP servers run with the correct runtime version, regardless of the system's default version, providing consistency across different environments and preventing version conflicts.

64
apps/docs/docs/features/mcp/what-is-mcp.md Normal file
View file

@ -0,0 +1,64 @@
---
description: Understand the Model Context Protocol (MCP) and how it enables AI systems to interact with external tools. Learn about MCP architecture and benefits.
keywords:
- what is MCP
- Model Context Protocol
- MCP architecture
- AI tools integration
- MCP client-server
- JSON-RPC protocol
sidebar_label: What is MCP?
---
# What is MCP?
MCP (Model Context Protocol) is a standardized communication protocol for LLM systems to interact with external tools and services. It functions as a universal adapter between AI assistants and various data sources or applications.
---
## How It Works
MCP uses a client-server architecture:
1. The AI assistant (client) connects to MCP servers
2. Each server provides specific capabilities (file access, database queries, API integrations)
3. The AI uses these capabilities through a standardized interface
4. Communication occurs via JSON-RPC 2.0 messages
Think of MCP as similar to a USB-C port in the sense that any compatible LLM can connect to any MCP server to access its functionality. This standardization eliminates the need to build custom integrations for each tool and service.
For example, an AI using MCP can perform tasks like "search our company database and generate a report" without requiring specialized code for each database system.
---
## Common Questions
- **Is MCP a cloud service?** MCP servers can run locally on your computer or remotely as cloud services, depending on the use case and security requirements.
- **Does MCP replace other integration methods?** No. MCP complements existing tools like API plugins and retrieval-augmented generation. It provides a standardized protocol for tool interaction but doesn't replace specialized integration approaches.
- **How is security handled?** Users control which MCP servers they connect to and what permissions those servers have. As with any tool that accesses data or services, use trusted sources and configure appropriate access controls.
---
## MCP in Roo Code
Roo Code implements the Model Context Protocol to:
- Connect to both local and remote MCP servers
- Provide a consistent interface for accessing tools
- Extend functionality without core modifications
- Enable specialized capabilities on demand
MCP provides a standardized way for AI systems to interact with external tools and services, making complex integrations more accessible and consistent.
---
## Learn More About MCP
Ready to dig deeper? Check out these guides:
- [MCP Overview](/features/mcp/overview) - A quick glance at the MCP documentation structure
- [Using MCP in Roo Code](/features/mcp/using-mcp-in-roo) - Get started with MCP in Roo, including creating simple servers
- [MCP vs API](/features/mcp/mcp-vs-api) - Technical advantages compared to traditional APIs
- [STDIO & Streamable HTTP & SSE Transports](/features/mcp/server-transports) - Local vs. hosted deployment models

86
apps/docs/docs/features/message-queueing.md Normal file
View file

@ -0,0 +1,86 @@
---
description: Learn how message queueing in Roo Code allows you to send multiple messages while the AI is working, with messages being processed sequentially for uninterrupted workflow.
keywords:
- message queueing
- queued messages
- sequential processing
- workflow efficiency
- chat interface
- Roo Code features
---
# Message Queueing
Keep your workflow uninterrupted with message queueing—send multiple messages while Roo is working, and they'll be processed sequentially without losing your train of thought.
:::tip Efficiency Boost
No more waiting! Type your follow-up thoughts, corrections, or additional requests while Roo is still processing, and they'll be handled in order.
:::
---
## Overview
Message queueing lets you type and send messages while Roo is still working. Just type your message and hit Enter - it gets queued and will be processed as soon as Roo is ready for your next input. When a queued message is processed, Roo implicitly approves whatever would normally require your confirmation (tool calls, file writes, running commands)—even if auto-approval is disabled. This is useful for quick corrections or additions when you want to keep work moving without manual prompts.
---
## How It Works
While Roo is working:
1. **Type your message** as normal
2. **Press Enter** or click Send
3. **Message gets queued** and appears with "Queued Messages:" label
4. **Roo processes the queued message** as soon as it's ready for your next input and implicitly approves the next pending action (e.g., a tool call, file write, or command)—even if auto-approval is disabled
<img src="/img/message-queueing/message-queueing.png" alt="Message queueing interface showing active processing and three queued messages" width="800" />
**What you'll see:**
- Queued messages appear with "Queued Messages:" label
- Bordered cards for each queued message
- Click messages to edit them
- Trash icon to delete messages
The input field stays active so you can type anytime - just hit Enter to queue your message.
:::warning Queued Messages Implicitly Approve
Queued messages act as approval for the next action. When a queued message is processed, Roo proceeds with whatever would normally require confirmation (tool calls, file writes, running commands)—even if auto-approval is disabled.
Editing or deleting a queued message requires clicking it before it's processed. In fast workflows this window can be extremely short; if you need a manual review step, avoid queueing until you're ready to approve.
Note: This behavior is distinct from [Auto-Approving Actions](/features/auto-approving-actions) and is not controlled by its settings.
:::
---
## FAQ
**Q: How many messages can I queue?**
A: There is no hard limit on the number of messages you can queue. The queue size is only limited by available browser memory.
**Q: Can I reorder queued messages?**
A: No, messages are always processed in the order they were sent (FIFO).
**Q: Do queued messages require approval?**
A: No. When processed, a queued message implicitly approves the next pending action (tool calls, file writes, running commands), even if auto-approval is disabled. If you need a manual review step, do not queue the message; wait for the approval prompt and confirm manually.
**Q: Why are my queued messages triggering auto-approval?**
A: This isn’t the Auto-Approving Actions setting. Queueing a message tells Roo to proceed without pausing for confirmations, so the queued message implicitly approves the next action. To avoid this, don’t queue when you need a manual review—wait for the approval prompt and confirm manually. See [Auto-Approving Actions](/features/auto-approving-actions) for settings-based approvals.
**Q: What happens if Roo encounters an error?**
A: Queued messages remain in the queue. You can choose to cancel them or let processing continue.
**Q: Do queued messages use the same context?**
A: Yes, each message builds on the conversation context, including previous messages and responses.
**Q: Can I edit a queued message?**
A: Yes! Click on any queued message to edit it. Press Enter to save your changes or Escape to cancel editing. Multiple messages can be edited simultaneously.
---
## See Also
- [The Chat Interface](/basic-usage/the-chat-interface) - Learn about all chat features
- [Task Management](/features/task-todo-list) - Organize complex workflows
- [Auto-Approving Actions](/features/auto-approving-actions) - Streamline repetitive approvals
- [Keyboard Shortcuts](/features/keyboard-shortcuts) - Speed up your workflow

122
apps/docs/docs/features/model-temperature.md Normal file
View file

@ -0,0 +1,122 @@
---
description: Learn how to adjust model temperature in Roo Code to optimize AI responses for different tasks, from precise code generation to creative brainstorming.
keywords:
- model temperature
- AI settings
- output randomness
- code generation
- temperature control
- API configuration
---
import KangarooIcon from '@site/src/components/KangarooIcon';
# Model Temperature
Temperature controls the randomness of AI model outputs. Adjusting this setting optimizes results for different tasks - from precise code generation to creative brainstorming. Temperature is one of the most powerful parameters for controlling AI behavior. A well-tuned temperature setting can dramatically improve the quality and appropriateness of responses for specific tasks.
<img src="/img/model-temperature/model-temperature.gif" alt="Animation showing temperature slider adjustment" width="100%" />
---
## What is Temperature?
Temperature is a setting (usually between 0.0 and 2.0) that controls how random or predictable the AI's output is. Finding the right balance is key: lower values make the output more focused and consistent, while higher values encourage more creativity and variation. For many coding tasks, a moderate temperature (around 0.3 to 0.7) often works well, but the best setting depends on what you're trying to achieve.
:::info Temperature and Code: Common Misconceptions
Temperature controls output randomness, not code quality or accuracy directly. Key points:
- **Low Temperature (near 0.0):** Produces predictable, consistent code. Good for simple tasks, but can be repetitive and lack creativity. It doesn't guarantee _better_ code.
- **High Temperature:** Increases randomness, potentially leading to creative solutions but also more errors or nonsensical code. It doesn't guarantee _higher-quality_ code.
- **Accuracy:** Code accuracy depends on the model's training and prompt clarity, not temperature.
- **Temperature 0.0:** Useful for consistency, but limits exploration needed for complex problems.
:::
---
## Default Values in Roo Code
Roo Code uses a default temperature of 0.0 for most models, optimizing for maximum determinism and precision in code generation. This applies to OpenAI models, Anthropic models (non-thinking variants), LM Studio models, and most other providers.
Some models use higher default temperatures - DeepSeek R1 models and certain reasoning-focused models default to 0.3, providing a balance between determinism and creative exploration.
Models with thinking capabilities (where the AI shows its reasoning process) require a fixed temperature of 1.0 which cannot be changed, as this setting ensures optimal performance of the thinking mechanism. This applies to any model with the ":thinking" flag enabled.
Some specialized models don't support temperature adjustments at all, in which case Roo Code respects these limitations automatically.
---
## When to Adjust Temperature
Here are some examples of temperature settings that might work well for different tasks:
- **Code Mode (0.0-0.3):** For writing precise, correct code with consistent, deterministic results
- **Architect Mode (0.4-0.7):** For brainstorming architecture or design solutions with balanced creativity and structure
- **Ask Mode (0.7-1.0):** For explanations or open-ended questions requiring diverse and insightful responses
- **Debug Mode (0.0-0.3):** For troubleshooting bugs with consistent precision
These are starting points – it's important to [experiment with different settings](#experimentation) to find what works best for your specific needs and preferences.
---
## How to Adjust Temperature
1. **Open the Roo Code Panel:** Click the Roo Code icon (<KangarooIcon />) in the VS Code Activity Bar
2. **Open Settings:** Click the <Codicon name="gear" /> icon in the top right corner
3. **Find Temperature Control:** Navigate to the Providers section
4. **Enable Custom Temperature:** Check the "Use custom temperature" box
5. **Set Your Value:** Adjust the slider to your preferred value
<img src="/img/model-temperature/model-temperature.png" alt="Temperature setting in Roo Code settings panel" width="550" />
*Temperature slider in Roo Code settings panel*
---
## Using API Configuration Profiles for Temperature
Create multiple [API configuration profiles](/features/api-configuration-profiles) with different temperature settings:
**How to set up task-specific temperature profiles:**
1. Create specialized profiles like "Code - Low Temp" (0.1) and "Ask - High Temp" (0.8)
2. Configure each profile with appropriate temperature settings
3. Switch between profiles using the dropdown in settings or chat interface
4. Set different profiles as defaults for each mode for automatic switching when changing modes
This approach optimizes model behavior for specific tasks without manual adjustments.
---
## Technical Implementation
Roo Code implements temperature handling with these considerations:
- User-defined settings take priority over defaults
- Provider-specific behaviors are respected
- Model-specific limitations are enforced:
- Thinking-enabled models require a fixed temperature of 1.0
- Some models don't support temperature adjustments
---
## Experimentation
Experimenting with different temperature settings is the most effective way to discover what works best for your specific needs:
### Effective Temperature Testing
1. **Start with defaults** - Begin with Roo Code's preset values (0.0 for most tasks) as your baseline
2. **Make incremental adjustments** - Change values in small steps (±0.1) to observe subtle differences
3. **Test consistently** - Use the same prompt across different temperature settings for valid comparisons
4. **Document results** - Note which values produce the best outcomes for specific types of tasks
5. **Create profiles** - Save effective settings as [API configuration profiles](/features/api-configuration-profiles) for quick access
Remember that different models may respond differently to the same temperature values, and thinking-enabled models always use a fixed temperature of 1.0 regardless of your settings.
---
## Related Features
- Works with all [API providers](/providers/openai) supported by Roo Code
- Complements [custom instructions](/features/custom-instructions) for fine-tuning responses
- Works alongside [custom modes](/features/custom-modes) you create

61
apps/docs/docs/features/more-features.md Normal file
View file

@ -0,0 +1,61 @@
---
description: Explore additional Roo Code features including suggested responses for faster interaction, text-to-speech capabilities, and support for 18 languages.
keywords:
- additional features
- suggested responses
- text to speech
- TTS
- language support
- multilingual
- accessibility
sidebar_label: Additional Features
---
# Additional Features
This page describes additional features in Roo Code that enhance your development workflow.
---
## Suggested Responses
Roo Code provides suggested responses to questions, saving you time typing. These suggestions appear as buttons below the chat input box after you ask a question. Click a suggestion to quickly use it as your next prompt.
This feature aims to streamline your workflow by anticipating your potential follow-up questions and providing one-click access to relevant prompts.
---
## Text to Speech
Roo Code includes a Text-to-Speech (TTS) feature that reads out the AI responses, allowing you to listen to the information instead of reading it. This can be helpful for accessibility, learning, or simply for a change of pace.
To use Text-to-Speech, simply enable it in the Roo Code settings. Once enabled, a speaker icon will appear next to each AI response in the chat. Click the icon to start listening.
---
## Global Language Support
Roo Code supports 18 languages, making it accessible to a wider range of users globally. You can now use Roo Code in:
- English
- Simplified Chinese
- Traditional Chinese
- Spanish
- Hindi
- French
- Portuguese
- German
- Japanese
- Korean
- Italian
- Turkish
- Vietnamese
- Polish
- Catalan
- Russian
- Dutch
- Indonesian
To change your language, go to **Advanced Settings > Language** in the Roo Code settings panel.
This global update ensures a smoother and more inclusive coding experience for users around the world.

87
apps/docs/docs/features/rooignore.md Normal file
View file

@ -0,0 +1,87 @@
---
description: Learn how to use .rooignore files to control Roo Code's file access, protect sensitive information, and manage which files the AI can read or modify.
keywords:
- rooignore
- file access control
- sensitive data protection
- gitignore syntax
- file permissions
- security
sidebar_label: .rooignore
---
# Using .rooignore to Control File Access
The `.rooignore` file is a key feature for managing Roo Code's interaction with your project files. It allows you to specify files and directories that Roo should not access or modify, similar to how `.gitignore` works for Git.
---
## What is `.rooignore`?
- **Purpose**: To protect sensitive information, prevent accidental changes to build artifacts or large assets, and generally define Roo's operational scope within your workspace.
- **How to Use**: Create a file named `.rooignore` in the root directory of your VS Code workspace. List patterns in this file to tell Roo which files and directories to ignore.
- **Scope**: `.rooignore` affects both Roo's tools and context mentions (like `@directory` attachments).
Roo actively monitors the `.rooignore` file. Any changes you make are reloaded automatically, ensuring Roo always uses the most current rules. The `.rooignore` file itself is always implicitly ignored, so Roo cannot change its own access rules.
---
## Pattern Syntax
The syntax for `.rooignore` is identical to `.gitignore`. Here are common examples:
- `node_modules/`: Ignores the entire `node_modules` directory.
- `*.log`: Ignores all files ending in `.log`.
- `config/secrets.json`: Ignores a specific file.
- `!important.log`: An exception; Roo will _not_ ignore this specific file, even if a broader pattern like `*.log` exists.
- `build/`: Ignores the `build` directory.
- `docs/**/*.md`: Ignores all Markdown files in the `docs` directory and its subdirectories.
For a comprehensive guide on syntax, refer to the [official Git documentation on .gitignore](https://git-scm.com/docs/gitignore).
---
## How Roo Tools Interact with `.rooignore`
`.rooignore` rules are enforced across various Roo tools:
### Strict Enforcement (Reads & Writes)
These tools directly check `.rooignore` before any file operation. If a file is ignored, the operation is blocked:
- [`read_file`](/advanced-usage/available-tools/read-file): Will not read ignored files.
- [`write_to_file`](/advanced-usage/available-tools/write-to-file): Will not write to or create new ignored files.
- [`apply_diff`](/advanced-usage/available-tools/apply-diff): Will not apply diffs to ignored files.
### File Discovery and Listing
- **[`list_files`](/advanced-usage/available-tools/list-files) Tool & `@directory` Attachments**: When Roo lists files or when you use `@directory` attachments, ignored files are omitted or marked with a 🔒 symbol (see "User Experience" below). Both use identical filtering logic.
- **Environment Details**: Information about your workspace (like open tabs and project structure) provided to Roo is filtered to exclude or mark ignored items.
### Context Mentions
- **`@directory` Attachments**: Directory contents respect `.rooignore` patterns. Ignored files are filtered out or marked with `[🔒]` prefix depending on the `showRooIgnoredFiles` setting.
- **Single File Mentions**: Ignored files return "(File is ignored by .rooignore)" instead of content.
### Command Execution
- **[`execute_command`](/advanced-usage/available-tools/execute-command) Tool**: This tool checks if a command (from a predefined list like `cat` or `grep`) targets an ignored file. If so, execution is blocked.
---
## Key Limitations and Scope
- **Workspace-Centric**: `.rooignore` rules apply **only to files and directories within the current VS Code workspace root**. Files outside this scope are not affected.
- **[`execute_command`](/advanced-usage/available-tools/execute-command) Specificity**: Protection for `execute_command` is limited to a predefined list of file-reading commands. Custom scripts or uncommon utilities might not be caught.
- **Not a Full Sandbox**: `.rooignore` is a powerful tool for controlling Roo's file access via its tools, but it does not create a system-level sandbox.
---
## User Experience and Notifications
- **Visual Cue (🔒)**: In file listings and `@directory` attachments, files ignored by `.rooignore` may be marked with a lock symbol (🔒), depending on the `showRooIgnoredFiles` setting (defaults to `true`).
- **Ignore Messages**: Single file mentions return "(File is ignored by .rooignore)" instead of content.
- **Error Messages**: If a tool operation is blocked, Roo receives an error: `"Access to [file_path] is blocked by the .rooignore file settings. You must try to continue in the task without using this file, or ask the user to update the .rooignore file."`
- **Chat Notifications**: You will typically see a notification in the Roo chat interface when an action is blocked due to `.rooignore`.
This guide helps you understand the `.rooignore` feature, its capabilities, and its current limitations, so you can effectively manage Roo's interaction with your codebase.

384
apps/docs/docs/features/settings-management.md Normal file
View file

@ -0,0 +1,384 @@
---
sidebar_label: Import/Export/Reset Settings
description: Manage your Roo Code settings by exporting, importing, or resetting them to defaults.
keywords:
- settings management
- import settings
- export settings
- reset settings
- configuration backup
- auto import
---
# Import, Export, and Reset Settings
Roo Code allows you to manage your configuration settings effectively through export, import, and reset options. These features are useful for backing up your setup, sharing configurations with others, or restoring default settings if needed.
You can find these options at the bottom of the Roo Code settings page, accessible via the gear icon (<i class="codicon codicon-gear"></i>) in the Roo Code chat view.
<img src="/img/settings-management/settings-management.png" alt="Export, Import, and Reset buttons in Roo Code settings" width="400" />
*Image: Export, Import, and Reset buttons.*
---
## Export Settings
Clicking the **Export** button saves your current Roo Code settings to a JSON file.
- **What's Exported:** The file includes your configured API Provider Profiles and Global Settings (UI preferences, mode configurations, context settings, etc.).
- **Security Warning:** The exported JSON file contains **all** your configured API Provider Profiles and Global Settings. Crucially, this includes **API keys in plaintext**. Treat this file as highly sensitive. Do not share it publicly or with untrusted individuals, as it grants access to your API accounts.
- **Process:**
1. Click **Export**.
2. A file save dialog appears, suggesting `roo-code-settings.json` as the filename (usually in your `~/Documents` folder).
3. Choose a location and save the file.
This creates a backup of your configuration or a file you can share.
---
## Import Settings
Clicking the **Import** button allows you to load settings from a previously exported JSON file.
- **Process:**
1. Click **Import**.
2. A file open dialog appears. Select the `roo-code-settings.json` file (or similarly named file) you want to import.
3. Roo Code reads the file, validates its contents against the expected schema, and applies the settings.
- **Merging:** Importing settings **merges** the configurations. It adds new API profiles and updates existing ones and global settings based on the file content. It does **not** delete configurations present in your current setup but missing from the imported file.
- **Validation:** Import validates the file, but it can still succeed with warnings.
- If **some** API profiles reference a provider that no longer exists (or is otherwise invalid), Roo imports the rest and reports warnings.
- Import fails only if **all** profiles are invalid.
---
## Automatic Configuration Import
Automatically import your Roo Code settings from a file every time you start VS Code. This is a powerful way to sync your configuration across multiple machines or standardize settings for your entire team.
### Key Features
- **Effortless Sync**: Keep your settings consistent across different workspaces and devices.
- **Team Standardization**: Share a single configuration file to ensure your whole team uses the same settings.
- **Flexible Pathing**: Works with absolute paths, or paths relative to your home directory (e.g., `~/Documents/roo-settings.json`).
- **Silent & Safe**: If the file isn't found or contains errors, Roo Code starts up normally without blocking your workflow.
### Use Case
**Before**: Manually exporting and importing settings every time you moved to a new machine or wanted to share your setup.
- Manually open the settings panel.
- Export your current settings to a file.
- Send the file to a teammate or a new machine.
- Manually import the file.
**With this feature**: Configure the path once, and Roo Code handles the rest on every launch.
### How it Works
When VS Code starts, Roo Code checks for a specific setting: `roo-cline.autoImportSettingsPath`. If this setting contains a path to a valid Roo Code configuration file (`.json`), Roo Code will load it automatically.
- Upon successful import, you will see a notification: `Successfully imported settings from [your-file-name.json]`.
- If the file is invalid or can't be found, you'll get a non-intrusive warning, and the extension will start with your last known settings. The `autoImportSettings` function is designed to never block the extension from activating.
### Configuration
To use this feature, add the following to your VS Code `settings.json` file:
1. **Open your `settings.json` file**:
- Use the Command Palette (`Ctrl/Cmd + Shift + P`) and search for "Preferences: Open User Settings (JSON)".
2. **Add the setting**:
- Add the `roo-cline.autoImportSettingsPath` key with the path to your configuration file.
**Examples**:
- **Absolute Path (Recommended)**
```json
{
"roo-cline.autoImportSettingsPath": "/Users/your-username/Documents/dev-configs/roo-code.json"
}
```
- **Home Directory Path** (using `~`)
```json
{
"roo-cline.autoImportSettingsPath": "~/roo-code-settings.json"
}
```
- **To disable**, simply leave the path empty or remove the line entirely:
```json
{
"roo-cline.autoImportSettingsPath": ""
}
```
### FAQ
**"What happens if my file has an error?"**
- Roo Code will show a warning notification with the error details. The extension will continue to load normally with your previously saved settings.
**"Where does Roo Code look for relative paths?"**
- For safety and consistency, paths that are not absolute or home-directory-based are resolved relative to your home directory.
**"Can I use this to manage settings for my team?"**
- Yes. Place the configuration file in a shared location (like a synced cloud folder or a shared network drive) and have each team member point to that file.
---
## Reset Settings
Clicking the **Reset** button completely clears all Roo Code configuration data and returns the extension to its default state. This is a destructive action intended for troubleshooting or starting fresh.
- **Warning:** This action is **irreversible**. It permanently deletes all API configurations (including keys stored in secret storage), custom modes, global settings, and task history.
- **Process:**
1. Click the red **Reset** button.
2. A confirmation dialog appears, warning that the action cannot be undone.
3. Click "Yes" to confirm.
- **What is Reset:**
- **API Provider Profiles:** All configurations are deleted from settings and secret storage.
- **Global Settings:** All preferences (UI, modes, approvals, browser, etc.) are reset to defaults.
- **Custom Modes:** All user-defined modes are deleted.
- **Secret Storage:** All API keys and other secrets managed by Roo Code are cleared.
- **Task History:** The current task stack is cleared.
- **Result:** Roo Code returns to its initial state, as if freshly installed, with default settings and no user configurations.
Use this option only if you are certain you want to remove all Roo Code data or if instructed during troubleshooting. Consider exporting your settings first if you might want to restore them later.
---
## Command Palette Commands
Roo Code provides several useful commands accessible via the VS Code Command Palette (`Ctrl/Cmd + Shift + P`). These commands offer alternative ways to manage your settings and storage.
### Set Custom Storage Path
**Command:** `roo-cline.setCustomStoragePath`
Opens a dialog to set a custom storage directory for Roo Code data. By default, Roo Code stores task history, settings, and other data in the standard VS Code extension storage location. This command allows you to choose an alternative location.
**Use cases:**
- **Team Collaboration**: Store Roo Code data in a shared network folder so team members can access the same task history and settings
- **Drive Management**: Keep data on a specific drive (e.g., a larger secondary drive instead of your primary SSD)
- **Cloud Sync**: Store data in a cloud-synced folder (Dropbox, OneDrive, etc.) to sync across multiple machines
- **Backup Strategy**: Place data in a location that's included in your regular backup routine
**To use:**
1. Open the Command Palette (`Ctrl/Cmd + Shift + P`)
2. Type "Set Custom Storage Path" or search for `roo-cline.setCustomStoragePath`
3. Select the command
4. Choose a directory in the file picker dialog
5. Restart VS Code for the change to take effect
**Note:** This setting can also be configured in VS Code settings as `roo-cline.customStoragePath`. See the [VS Code Settings Reference](#vs-code-settings-reference) section below for details.
### Import Settings from File
**Command:** `roo-cline.importSettings`
Imports Roo Code settings from a JSON file via the Command Palette. This is an alternative to using the Import button in the settings UI.
**To use:**
1. Open the Command Palette (`Ctrl/Cmd + Shift + P`)
2. Type "Import Settings" or search for `roo-cline.importSettings`
3. Select the command
4. Choose your settings JSON file in the file picker dialog
5. Settings will be imported and merged with your current configuration
This command provides the same functionality as the Import button described in the [Import Settings](#import-settings) section above.
---
## UI Setting
#### System Prompt Context Toggles
Control what contextual information appears in the system prompt:
- **Include Current Time** (Settings → General)
- When enabled, adds the current timestamp to the system prompt
- When disabled, omits time information from the prompt
- Default: Enabled
- **Include Current Cost** (Settings → General)
- When enabled, adds the current task cost to the system prompt
- When disabled, omits cost information from the prompt
- Default: Enabled
**Example Impact:**
With both enabled, the system prompt includes:
```
# Current Time
Current time in ISO 8601 UTC format: 2025-10-28T23:06:08.458Z
User time zone: America/Edmonton, UTC-6:00
# Current Cost
$0.14
```
With both disabled, these sections are omitted, reducing token usage when you don't need this context.
#### Collapse thinking messages by default
- Location: Settings → UI
- Default: Enabled (thinking messages are collapsed by default)
- Behavior:
- Enabled (default): Thinking blocks remain collapsed until you expand them.
- Disabled: Thinking blocks are expanded by default.
- Notes:
- Applies across conversations globally.
- Text is localized; labels may differ by language.
---
## VS Code Settings Reference
Roo Code provides VS Code settings that can be configured through your VS Code `settings.json` file. These settings offer fine-grained control over command execution, task management, API behavior, storage, indexing, and debugging.
To configure these settings, open your VS Code settings (`Ctrl/Cmd + ,`) and search for "roo-cline", or edit your `settings.json` file directly (`Ctrl/Cmd + Shift + P` → "Preferences: Open User Settings (JSON)").
### Command & Execution
#### `roo-cline.allowedCommands`
- **Type**: Array of strings
- **Default**: `["git log", "git diff", "git show"]`
- **Description**: Commands that can be auto-executed without approval. When Roo Code requests to execute a command that matches an entry in this list, it will execute automatically without prompting for approval. This is useful for safe, read-only commands.
#### `roo-cline.deniedCommands`
- **Type**: Array of strings
- **Default**: `[]`
- **Description**: Commands that are always blocked from execution. Roo Code will refuse to execute any command that matches an entry in this list, providing a safety mechanism to prevent potentially dangerous operations.
#### `roo-cline.commandExecutionTimeout`
- **Type**: Number (seconds)
- **Default**: `0`
- **Range**: 0-600
- **Description**: Timeout in seconds for command execution. When set to a value greater than 0, commands running longer than this duration will be terminated. A value of 0 means no timeout (commands can run indefinitely). See also `commandTimeoutAllowlist` for exempting specific commands.
#### `roo-cline.commandTimeoutAllowlist`
- **Type**: Array of strings
- **Default**: `[]`
- **Description**: Commands exempt from execution timeout. Commands matching entries in this list will not be subject to the `commandExecutionTimeout` limit, allowing them to run without time restrictions. Useful for known long-running operations like build processes or deployment scripts.
### Task Management
#### `roo-cline.newTaskRequireTodos`
- **Type**: Boolean
- **Default**: `false`
- **Description**: When enabled, requires a todo list when creating new tasks via boomerang/subtasks. This ensures structured planning for complex work by mandating that new tasks include a checklist of steps to complete.
#### `roo-cline.preventCompletionWithOpenTodos`
- **Type**: Boolean
- **Default**: `false`
- **Description**: Prevents task completion when there are uncompleted todo items. When enabled, Roo Code will not allow you to mark a task as complete if the todo list still has pending items, ensuring all planned work is finished.
### API & Network
#### `roo-cline.apiRequestTimeout`
- **Type**: Number (seconds)
- **Default**: `600`
- **Range**: 0-3600
- **Description**: Timeout in seconds for API requests. Determines how long Roo Code will wait for a response from AI provider APIs before timing out. A value of 0 means no timeout.
### Storage & Import
#### `roo-cline.customStoragePath`
- **Type**: String
- **Default**: `""` (empty)
- **Description**: Custom file path for Roo Code's storage directory. By default, Roo Code stores its data in the standard extension storage location. Use this setting to specify an alternative directory for storing task history, settings, and other data.
#### `roo-cline.autoImportSettingsPath`
- **Type**: String
- **Default**: `""` (empty)
- **Description**: File path for automatic settings import on startup. When configured, Roo Code will automatically import settings from the specified JSON file every time VS Code starts. See the [Automatic Configuration Import](#automatic-configuration-import) section above for detailed usage instructions.
### Code Index
#### `roo-cline.maximumIndexedFilesForFileSearch`
- **Type**: Number
- **Default**: `10000`
- **Range**: 5000-500000
- **Description**: Maximum number of files indexed for file search. Controls the upper limit of files that Roo Code will index for semantic search functionality. Higher values increase search coverage but may impact performance.
#### `roo-cline.codeIndex.embeddingBatchSize`
- **Type**: Number
- **Default**: `60`
- **Range**: 1-200
- **Description**: Batch size for embedding operations during code indexing. Determines how many code chunks are processed together when generating embeddings for semantic search. Lower values reduce memory usage but increase processing time; higher values are faster but use more memory.
### Editor Integration
#### `roo-cline.enableCodeActions`
- **Type**: Boolean
- **Default**: `true`
- **Description**: Controls whether Roo Code actions appear in the editor context menu and lightbulb. When enabled, you can right-click in the editor or use the lightbulb menu to quickly send code selections to Roo Code with contextual prompts.
#### `roo-cline.vsCodeLmModelSelector`
- **Type**: Object
- **Default**: `{}`
- **Description**: Configuration for VS Code Language Model API provider selection. Allows you to specify vendor and family properties to control which language model is used when the VS Code LM API provider is selected. See [VS Code LM API documentation](/providers/vscode-lm) for details.
### Rules & Instructions
#### `roo-cline.useAgentRules`
- **Type**: Boolean
- **Default**: `true`
- **Description**: Enable loading of AGENTS.md files for agent-specific instructions. When enabled, Roo Code will look for and load `AGENTS.md` files in your project directories to provide context-specific guidance to the AI. Disable this if you want to prevent automatic loading of these instruction files.
### Debug
#### `roo-cline.debug`
- **Type**: Boolean
- **Default**: `false`
- **Description**: Enable debug mode for additional logging. When enabled, Roo Code will output detailed debug information to the console, useful for troubleshooting issues or understanding internal behavior.
#### `roo-cline.debugProxy.enabled`
- **Type**: Boolean
- **Default**: `false`
- **Description**: Enable debug proxy for intercepting API requests. When enabled, all API requests will be routed through a debug proxy server, allowing you to inspect and debug API communications.
#### `roo-cline.debugProxy.serverUrl`
- **Type**: String
- **Default**: `"http://127.0.0.1:8888"`
- **Description**: URL of the debug proxy server. Specifies the proxy server address used when `debugProxy.enabled` is true. Common debug proxy tools like mitmproxy or Charles Proxy typically run on this default address.
#### `roo-cline.debugProxy.tlsInsecure`
- **Type**: Boolean
- **Default**: `false`
- **Description**: Allow insecure TLS connections through the debug proxy. When enabled, certificate validation errors will be ignored, which is necessary when using self-signed certificates with debug proxies. Only enable this in development environments.

544
apps/docs/docs/features/shell-integration.mdx Normal file
View file

@ -0,0 +1,544 @@
---
description: Learn how Roo Code integrates with your shell to execute commands. Troubleshooting guide for terminal issues and shell configuration.
keywords:
- shell integration
- terminal commands
- command execution
- shell configuration
- troubleshooting
---
import Codicon from '@site/src/components/Codicon';
# Terminal Shell Integration
Terminal Shell Integration is a key feature that enables Roo Code to execute commands in your terminal and intelligently process their output. This bidirectional communication between the AI and your development environment unlocks powerful automation capabilities.
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/rkWBHeG9A-4?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
title="Terminal Integration Tutorial"
></iframe>
</div>
<br />
---
## What is Shell Integration?
Shell integration is automatically enabled in Roo Code and connects directly to your terminal's command execution lifecycle without requiring any setup from you. This built-in feature allows Roo to:
- Execute commands on your behalf through the [`execute_command`](/advanced-usage/available-tools/execute-command) tool
- Read command output in real-time without manual copy-pasting
- Automatically detect and fix errors in running applications
- Observe command exit codes to determine success or failure
- Track working directory changes as you navigate your project
- React intelligently to terminal output without user intervention
- Stop running commands directly from the chat interface using the stop button that appears next to the command execution message.
<img src="/img/v3.15/v3.15.png" alt="Stop Command Button in Chat UI" width="600" />
When you ask Roo to perform tasks like installing dependencies, starting a development server, or analyzing build errors, shell integration works behind the scenes to make these interactions smooth and effective.
---
## Terminal Integration Settings
Roo Code provides settings to fine-tune how it interacts with terminals. To access these settings:
1. Click the <Codicon name="gear" /> icon in the top-right corner of the Roo Code sidebar.
2. In the settings pane that opens, select the "Terminal" group from the left-hand menu.
### Command Execution Timeout Settings
You can configure command execution timeouts through VS Code settings. These settings are accessible in your `settings.json` file (`Ctrl/Cmd + Shift + P` → "Preferences: Open User Settings (JSON)").
#### `roo-cline.commandExecutionTimeout`
- **Type**: Number (seconds)
- **Default**: `0`
- **Range**: 0-600
- **Description**: Timeout in seconds for command execution. When set to a value greater than 0, commands running longer than this duration will be terminated. A value of 0 means no timeout (commands can run indefinitely).
**Example configuration**:
```json
{
"roo-cline.commandExecutionTimeout": 300
}
```
This example sets a 5-minute timeout for all commands.
#### `roo-cline.commandTimeoutAllowlist`
- **Type**: Array of strings
- **Default**: `[]`
- **Description**: Commands exempt from execution timeout. Commands matching entries in this list will not be subject to the `commandExecutionTimeout` limit, allowing them to run without time restrictions. Useful for known long-running operations like build processes or deployment scripts.
**Example configuration**:
```json
{
"roo-cline.commandExecutionTimeout": 300,
"roo-cline.commandTimeoutAllowlist": ["npm run build", "docker build", "npm test"]
}
```
This example sets a 5-minute timeout but exempts build and test commands from the timeout.
### Basic Settings
#### Terminal Output Limit
<img src="/img/shell-integration/shell-integration-13.png" alt="Terminal output limit slider set to 500" width="600" />
Truncates by lines. Roo keeps the beginning and end and drops the middle with an "[...N lines omitted...]" marker to stay under the limit. Mechanism: keeps approximately 20% of the head and 80% of the tail of the allowed line budget and inserts an omission marker, preserving a blank line before the tail for readability. Use when commands print many lines (e.g., long logs) and you mostly care about headers and final results. Avoid when important details are in the middle. Default: 500 lines.
#### Terminal Character Limit
<img src="/img/shell-integration/shell-integration-15.png" alt="Terminal character limit setting" width="600" />
Hard cap on total output size (characters). Roo keeps the beginning and end and omits the middle with an "[...N characters omitted...]" marker. Mechanism: takes precedence over the line limit; keeps ~20% of the head and ~80% of the tail of the character budget, overriding the line limit to prevent memory issues from very long lines. Use when commands print extremely long lines or massive blobs. Avoid when you need the exact full content.
#### Compress progress bar output
<img src="/img/shell-integration/shell-integration-14.png" alt="Compress progress bar output checkbox" width="600" />
ON: Collapses progress bars/spinners by processing carriage returns (\r) and backspaces (\b) so only the final state is kept, then applies run-length encoding to collapse repeated lines. OFF: Keeps every update exactly as printed. Use when you don’t need intermediate spinner states (recommended ON). Disable only if you’re debugging step-by-step progress behavior.
### Advanced Settings
Unless noted, these settings apply only when "Use Inline Terminal (recommended)" is OFF (i.e., using the VS Code terminal).
:::info Important
**Terminal restart required for these settings**
Changes to advanced terminal settings only take effect after restarting your terminals. To restart a terminal:
1. Click the trash icon in the terminal panel to close the current terminal
2. Open a new terminal with Terminal → New Terminal or <kbd>Ctrl</kbd>+<kbd>`</kbd> (backtick)
Always restart all open terminals after changing any of these settings.
:::
<a id="use-inline-terminal-recommended"></a>
<a id="disable-terminal-shell-integration"></a>
#### Use Inline Terminal (recommended)
<img src="/img/shell-integration/shell-integration-16.png" alt="Use Inline Terminal (recommended) switch" width="600" />
Controls how Roo Code executes terminal commands.
- ON (Use Inline Terminal): Runs commands with the Inline Terminal (in chat), bypassing shell profiles and VS Code shell integration for reliability and faster starts. Mechanism: uses a background “execa” provider and streams output directly (no VS Code OSC 633/133 markers).
<img src="/img/shell-integration/shell-integration-12.png" alt="Roo Code Inline Terminal when 'Use Inline Terminal (recommended)' is ON" width="600" />
*Inline Terminal active (Use Inline Terminal is ON).*
- OFF (Use VS Code terminal): Uses the VS Code integrated terminal and your shell profile; may require shell integration and is more likely to hit “Shell Integration Unavailable” issues. Use this only when you specifically need terminal UI features or interactive profile behavior.
#### Decision guide: Inline Terminal ON vs OFF
- Use ON when you want reliability, faster starts, or your shell profile causes issues.
- Use OFF when you need terminal UI features or your shell prompt customizations to run.
- Tip: If terminal commands fail or stall, switch ON and retry.
:::info Runtime Environment
On macOS (and possibly other operating systems) the environment provided to VS Code, and consequently Roo Code, can differ depending on how VS Code is launched.
If launched from the command line with the `code` command, VS Code and Roo Code inherit the environment from the shell that launched it.
If launched from the Finder, Dock, or Spotlight, environment exported from `.zshrc` or `.zprofile` will likely be missing.
If you rely on environment variables from those files and they are missing in VS Code, move them to `.zshenv`, then log out and back in so the window manager picks up the new settings.
:::
The following advanced settings apply only when this is OFF (i.e., when using the VS Code terminal):
#### Inherit environment variables
<img src="/img/shell-integration/shell-integration-17.png" alt="Inherit environment variables checkbox" width="600" />
VS Code terminal only. Controls whether VS Code integrated terminals inherit environment variables from the parent VS Code process. Mirrors the VS Code setting [`terminal.integrated.inheritEnv`](https://code.visualstudio.com/docs/editor/integrated-terminal#_inherit-environment-variables). Note: Inline Terminal (“Use Inline Terminal (recommended)” ON) runs as a background process and always uses the extension’s Node process environment; this setting doesn’t affect it. Keep enabled (VS Code default) if you rely on PATH/proxy/auth variables provided by VS Code. Disable only for clean, reproducible integrated terminal sessions or when debugging environment conflicts.
#### Terminal shell integration timeout
<img src="/img/shell-integration/shell-integration-18.png" alt="Terminal shell integration timeout slider set to 15s" width="600" />
How long Roo waits for VS Code shell integration to initialize and for the integration stream to start. If not ready within the timeout, a “no shell integration” event is emitted and execution will fall back to the Inline Terminal when retried. Use when your shell/profile has long startup times or you see “Shell Integration Unavailable” errors. Avoid increasing if you’re using the Inline Terminal (not applicable there). Default: 15s. Applies only when using the VS Code terminal.
#### Terminal command delay
<img src="/img/shell-integration/shell-integration-19.png" alt="Terminal command delay slider set to 0ms" width="600" />
Adds a small delay after each command to help VS Code terminals flush all output. Mechanism: sets `PROMPT_COMMAND='sleep N'` for bash/zsh and appends `start-sleep -milliseconds N` for PowerShell. Use when you see truncated/missing tail output or prompt races. Avoid when output captures look correct. Set to 0 to disable. Default: 0ms.
#### Enable PowerShell counter workaround
<img src="/img/shell-integration/shell-integration-20.png" alt="Enable PowerShell counter workaround checkbox" width="600" />
ON: Appends `; "(Roo/PS Workaround: N)" > $null` to each command to force a reliable post-execution signal and avoid missing or duplicated output on some setups. Use when using Windows PowerShell and output is incomplete or repeats, or when running the same command twice in a row fails. OFF: Runs PowerShell commands unchanged.
#### Clear ZSH EOL mark
<img src="/img/shell-integration/shell-integration-21.png" alt="Clear ZSH EOL mark checkbox" width="600" />
ON: Omits Zsh’s end-of-line mark (%) so output is parsed correctly. Mechanism: sets `PROMPT_EOL_MARK=""`. Use when captured output ends with a stray % or parsing looks off. OFF: Leaves the default EOL mark (may confuse parsing on some setups).
#### Enable Oh My Zsh integration
<img src="/img/shell-integration/shell-integration-22.png" alt="Enable Oh My Zsh integration checkbox" width="600" />
For users of the popular Oh My Zsh framework for Zsh. Enable this if you use Oh My Zsh and experience general issues with terminal command execution or output rendering that aren't solved by other settings. This helps Roo Code align with Oh My Zsh's specific shell integration mechanisms by setting `ITERM_SHELL_INTEGRATION_INSTALLED=Yes`. Restarting the IDE might be necessary.
#### Enable Powerlevel10k integration
<img src="/img/shell-integration/shell-integration-23.png" alt="Enable Powerlevel10k integration checkbox" width="600" />
For users of the Powerlevel10k theme for Zsh. Enable this if your Powerlevel10k prompt (which can be quite complex) seems to interfere with Roo Code's ability to correctly detect command boundaries, parse output, or track the current working directory. This sets `POWERLEVEL9K_TERM_SHELL_INTEGRATION=true`.
#### Enable ZDOTDIR handling
<img src="/img/shell-integration/shell-integration-24.png" alt="Enable ZDOTDIR handling checkbox" width="600" />
ON: Uses a temporary ZDOTDIR so VS Code shell integration works with zsh while preserving your config. Mechanism: creates a temp dir with a `.zshrc` that sources VS Code’s shell integration script, then re-sources your original zsh files and resets ZDOTDIR; the temp dir is cleaned up after initialization. Use when zsh shell integration fails or conflicts with your dotfiles. OFF: Uses your normal ZDOTDIR.
---
## How Shell Integration Works
Shell integration connects Roo to your terminal's command execution process in real-time:
1. **Connection**: When you open a terminal, VS Code establishes a special connection with your shell.
2. **Command Tracking**: VS Code monitors your terminal activities by detecting:
- When a new prompt appears
- When you enter a command
- When the command starts running
- When the command finishes (and whether it succeeded or failed)
- What directory you're currently in
3. **Different Shells, Same Result**: Each shell type (Bash, Zsh, PowerShell, Fish) implements this slightly differently behind the scenes, but they all provide the same functionality to Roo.
4. **Information Gathering**: Roo can see what commands are running, where they're running, how long they take, whether they succeed, and their complete output - all without you having to copy and paste anything.
---
## Troubleshooting Shell Integration
#### Quick fixes
1. Update VS Code/Cursor to the latest version (VS Code 1.93+ required).
2. Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → “Terminal: Select Default Profile” → choose bash, zsh, PowerShell, or fish.
3. Windows PowerShell: run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`, then restart VS Code.
4. WSL (bash): add `. "$(code --locate-shell-integration-path bash)"` to `~/.bashrc`.
#### PowerShell Execution Policy (Windows)
PowerShell restricts script execution by default. To configure:
1. Open PowerShell as Administrator
2. Check current policy: `Get-ExecutionPolicy`
3. Set appropriate policy: `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`
Common policies:
- `Restricted`: No scripts allowed (default)
- `RemoteSigned`: Local scripts can run; downloaded scripts need signing
- `Unrestricted`: All scripts run with warnings
- `AllSigned`: All scripts must be signed
#### Manual Shell Integration Installation
If automatic integration fails, add the appropriate line to your shell configuration:
**Bash** (`~/.bashrc`):
```bash
[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path bash)"
```
**Zsh** (`~/.zshrc`):
```bash
[[ "$TERM_PROGRAM" == "vscode" ]] && . "$(code --locate-shell-integration-path zsh)"
```
**PowerShell** (`$Profile`):
```powershell
if ($env:TERM_PROGRAM -eq "vscode") { . "$(code --locate-shell-integration-path pwsh)" }
```
**Fish** (`~/.config/fish/config.fish`):
```fish
string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)
```
#### Terminal Customization Issues
If you use terminal customization tools:
**Powerlevel10k**:
```bash
# Add before sourcing powerlevel10k in ~/.zshrc
typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true
```
**Alternative**: Enable the Powerlevel10k Integration setting in Roo Code.
#### Verifying Shell Integration Status
Confirm shell integration is active with these commands:
**Bash**:
```bash
set | grep -i '[16]33;'
echo "$PROMPT_COMMAND" | grep vsc
trap -p DEBUG | grep vsc
```
**Zsh**:
```zsh
functions | grep -i vsc
typeset -p precmd_functions preexec_functions
```
**PowerShell**:
```powershell
Get-Command -Name "*VSC*" -CommandType Function
Get-Content Function:\Prompt | Select-String "VSCode"
```
**Fish**:
```fish
functions | grep -i vsc
functions fish_prompt | grep -i vsc
```
Visual indicators of active shell integration:
1. Shell integration indicator in terminal title bar
2. Command detection highlighting
3. Working directory updates in terminal title
4. Command duration and exit code reporting
---
#### WSL: best-practice setup
When using Windows Subsystem for Linux (WSL), there are two distinct ways to use VS Code with WSL, each with different implications for shell integration:
#### Method 1: VS Code Windows with WSL Terminal
In this setup:
- VS Code runs natively in Windows
- You use the WSL terminal integration feature in VS Code
- Shell commands are executed through the WSL bridge
- May experience additional latency due to Windows-WSL communication
- Shell integration markers may be affected by the WSL-Windows boundary: you must make sure that `source "$(code --locate-shell-integration-path <shell>)"` is loaded for your shell within the WSL environment because it may not get automatically loaded; see above.
#### Method 2: VS Code Running Within WSL
In this setup:
- You launch VS Code directly from within WSL using `code .`
- VS Code server runs natively in the Linux environment
- Direct access to Linux filesystem and tools
- Better performance and reliability for shell integration
- Shell integration is loaded automatically since VS Code runs natively in the Linux environment
- Recommended approach for WSL development
For optimal shell integration with WSL, we recommend:
1. Open your WSL distribution
2. Navigate to your project directory
3. Launch VS Code using `code .`
4. Use the integrated terminal within VS Code
---
#### Cygwin (bash, zsh)
Cygwin provides a Unix-like environment on Windows systems. To configure Cygwin as your terminal in VS Code:
1. Install Cygwin from [https://www.cygwin.com/](https://www.cygwin.com/)
2. Open VS Code settings:
- Select File > Preferences > Settings
- Click the "Open Settings (JSON)" icon in the top right corner
3. Add the following configuration to your `settings.json` (inside the top-level curly braces `{}`):
```json
{
"terminal.integrated.profiles.windows": {
"Cygwin": {
"path": "C:\\cygwin64\\bin\\bash.exe",
"args": ["--login"],
"env": {"CHERE_INVOKING": "1"}
}
},
"terminal.integrated.defaultProfile.windows": "Cygwin"
}
```
> Note: If you have 32-bit Cygwin installed, use `"C:\\cygwin\\bin\\bash.exe"` for the path.
4. Understanding the configuration:
- `path`: Points to the Bash executable in your Cygwin installation
- `args`: The `--login` flag ensures the shell reads profile files
- `env`: The `CHERE_INVOKING` environment variable tells Cygwin to use the current directory as the working directory
- `terminal.integrated.defaultProfile.windows`: Sets Cygwin as the default terminal profile
5. To open a new Cygwin terminal:
- Press Ctrl+Shift+(backtick) to open a new terminal, or
- Press `F1`, type "Terminal: Create New Terminal (with Profile)", and select "Cygwin"
While our testing shows that this works out of the box, if you encounter shell integration issues with Cygwin, ensure you have added the appropriate shell integration hooks to your Cygwin bash profile as described in the "Manual Shell Integration Installation" section.
#### VS Code Shell Integration for Fish + Cygwin on Windows
For fellow Windows users running Fish terminal within a Cygwin environment, here's how VS Code's shell integration works:
1. **(Optional) Locate the Shell Integration Script:**
Open your Fish terminal *within VS Code* and run the following command:
```bash
code --locate-shell-integration-path fish
```
This will output the path to the `shellIntegration.fish` script. Note down this path.
2. **Update Your Fish Configuration:**
Edit your `config.fish` file (usually located at `~/.config/fish/config.fish` within your Cygwin home directory). Add the following line, preferably within an `if status is-interactive` block or at the very end of the file:
```fish
# Example config.fish structure
if status is-interactive
# Your other interactive shell configurations...
# automatic locate integration script:
string match -q "$TERM_PROGRAM" "vscode"; and . (code --locate-shell-integration-path fish)
# Or if the above fails for you:
# Source the VS Code shell integration script
# IMPORTANT: Replace the example path below with the actual path you found in Step 1.
# Make sure the path is in a format Cygwin can understand (e.g., using /cygdrive/c/...).
# source "/cygdrive/c/Users/YourUser/.vscode/extensions/..../shellIntegration.fish"
end
```
*Remember to replace the example path with the actual path from Step 1, correctly formatted for Cygwin.*
3. **Configure VS Code Terminal Profile:**
Open your VS Code `settings.json` file (Ctrl+Shift+P -> "Preferences: Open User Settings (JSON)"). Update or add the Fish profile under `terminal.integrated.profiles.windows` like this:
```json
{
// ... other settings ...
"terminal.integrated.profiles.windows": {
// ... other profiles ...
// Recommended: Use bash.exe to launch fish as a login shell
"fish": {
"path": "C:\\cygwin64\\bin\\bash.exe", // Or your Cygwin bash path
"args": [
"--login",
"-i",
"-c",
"exec fish"
],
"icon": "terminal-bash" // Optional: Use a recognizable icon
},
// Alternative (if the above fails): Launch fish directly
"fish-direct": {
"path": "C:\\cygwin64\\bin\\fish.exe", // Ensure this is in your Windows PATH or provide full path
// Use 'options' here instead of 'args'; otherwise, you might encounter the error "terminal process terminated exit code 1".
"options": ["-l", "-c"], // Example: login and interactive flags.
"icon": "terminal-fish" // Optional: Use a fish icon
}
},
// Optional: Set fish as your default if desired
// "terminal.integrated.defaultProfile.windows": "fish", // or "fish-direct" depending what you use.
// ... other settings ...
}
```
*Note: Using `bash.exe --login -i -c "exec fish"` is often more reliable in Cygwin environments for ensuring the correct environment setup before `fish` starts. However, if that approach doesn't work, try the `fish-direct` profile configuration.*
4. **Restart VS Code:**
Close and reopen Visual Studio Code completely to apply the changes.
5. **Verify:**
Open a new Fish terminal in VS Code. The shell integration features (like command decorations, better command history navigation, etc.) should now be active. You can test basic functionality by running simple commands like `echo "Hello from integrated Fish!"`. <img src="/img/shell-integration/shell-integration-8.png" alt="Fish Cygwin Integration Example" width="600" />
This setup works reliably on Windows systems using Cygwin, Fish, and the Starship prompt, and should assist users with similar configurations.
#### Ctrl+C Behavior
**Issue**: If text is already typed in the terminal when Roo tries to run a command, Roo will press Ctrl+C first to clear the line, which can interrupt running processes.
**Workaround**: Make sure your terminal prompt is empty (no partial commands typed) before asking Roo to execute terminal commands.
#### Multi-line Command Issues
**Issue**: Commands that span multiple lines can confuse Roo and may show output from previous commands mixed in with current output.
**Workaround**: Instead of multi-line commands, use command chaining with `&amp;&amp;` to keep everything on one line (e.g., `echo a &amp;&amp; echo b` instead of typing each command on a separate line).
#### PowerShell-Specific Issues
1. **Premature Completion**: PowerShell sometimes tells Roo a command is finished before all the output has been shown.
2. **Repeated Commands**: PowerShell may refuse to run the same command twice in a row.
**Workaround**: Enable the "PowerShell counter workaround" setting and set a terminal command delay of 150ms in the settings to give commands more time to complete.
#### Incomplete Terminal Output
**Issue**: Sometimes VS Code doesn't show or capture all the output from a command.
**Workaround**: If you notice missing output, try closing and reopening the terminal tab, then run the command again. This refreshes the terminal connection.
#### Python Virtual Environment (venv) Issues
**Issue**: Disabling shell integration will disable venv; venv is VS Code–managed, Roo does not know anything about it because disabling shell integration uses a completely different mechanism for running commands (execa).
**Workaround**: If you need to use Python virtual environments with Roo Code, you might be able to:
```bash
killall code # closes all VS Code windows!
. venv/bin/activate
code
```
This way the environment is configured before code launches so Roo should inherit it.
#### Checking Debug Logs
When shell integration issues occur, check the debug logs:
1. Open Help → Toggle Developer Tools → Console
2. Set "Show All Levels" to see all log messages
3. Look for messages containing `[Terminal Process]`
4. Check `preOutput` content in error messages:
- Empty preOutput (`''`) means VS Code sent no data
- This indicates a potential VS Code shell integration issue, or an upstream bug that is out of our control
- The absence of shell integration markers may require adjusting settings to work around possible upstream bugs or local workstation configuration issues related to shell initialization and VS Code's loading of special shell integration hooks
#### Using the VS Code Terminal Integration Test Extension
The [VS Code Terminal Integration Test Extension](https://github.com/KJ7LNW/vsce-test-terminal-integration) helps diagnose shell integration issues by testing different settings combinations:
1. **When Commands Stall**:
- If you see "command already running" warnings, click "Reset Stats" to reset the terminal state
- These warnings indicate shell integration is not working
- Try different settings combinations until you find one that works
- If it really gets stuck, restart the extension by closing the window and pressing F5
2. **Testing Settings**:
- Systematically try different combinations of:
* Terminal Command Delay
* Shell Integration settings
- Document which combinations succeed or fail
- This helps identify patterns in shell integration issues
3. **Reporting Issues**:
- Once you find a problematic configuration
- Document the exact settings combination
- Note your environment (OS, VS Code version, shell, and any shell prompt customization)
- Open an issue with these details to help improve shell integration
---
## FAQ
- Why does Roo press Ctrl+C first?
- To clear any partially typed command so it can run reliably without interrupting your process.
- Can I run multi-line commands?
- Prefer chaining with && to avoid mixed output (e.g., `echo a && echo b`).
- How do I use Python venv with Inline Terminal?
- Close VS Code, activate the venv in a shell, then launch VS Code so Roo inherits it.
<a id="command-execution-fallback"></a>
- What does “Command Execution Fallback” mean?
- Roo ran the command without full shell integration. How it works: if VS Code terminal integration can’t connect, Roo runs the command in a background process.
- What you’ll see: a chat notice that real-time streaming and exit‑code detection may be limited.
- Fix: turn ON [Use Inline Terminal (recommended)](#use-inline-terminal-recommended) or follow the Troubleshooting steps above to restore VS Code shell integration.
<img src="/img/v3.15.0/v3.15.0.png" alt="Command execution fallback notification example" width="600" />

358
apps/docs/docs/features/skills.mdx Normal file
View file

@ -0,0 +1,358 @@
---
description: Learn how to create reusable skills that package task-specific instructions, making Roo Code more effective at specialized workflows.
keywords:
- skills
- task-specific instructions
- agentskills
- SKILL.md
- reusable instructions
- workflow automation
---
# Skills
Skills package task-specific instructions that Roo loads on-demand when your request matches the skill's purpose. Unlike custom instructions that apply to everything, skills activate only when needed—making Roo more effective at specialized tasks without cluttering the base prompt.
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/1992Rpfc800?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
title="Skills Tutorial Video"
></iframe>
</div>
<br />
---
## Why It Matters
**Custom Instructions apply broadly** across all your work. They're great for general coding standards or style preferences, but not ideal for specific workflows like "process PDF files" or "generate API documentation."
**Skills solve this**: Create a skill for PDF processing, and Roo only loads those instructions when you actually ask to work with PDFs. This keeps the system prompt focused and gives Roo deep expertise in specific domains without affecting unrelated tasks.
You can't package bundled assets (scripts, templates, references) with custom instructions. Skills let you store related files alongside the instructions, creating self-contained workflow packages.
## What Skills Let You Do
- **Task-Specific Expertise**: Package detailed instructions for specialized workflows (data processing, documentation generation, code migration patterns)
- **Bundled Resources**: Include helper scripts, templates, or reference files alongside instructions
- **Mode Targeting**: Create skills that only activate in specific modes (e.g., code refactoring skills only in Code mode)
- **Team Sharing**: Version-control project skills in `.roo/skills/` for consistent team workflows
- **Personal Library**: Build a global skills library in `~/.roo/skills/` that works across all projects
- **Override Control**: Project skills override global skills, mode-specific override generic
## How Skills Work
Skills use **progressive disclosure** to efficiently load content only when needed:
**Level 1: Discovery** - Roo reads each `SKILL.md` file and parses its frontmatter to extract `name` and `description`. Only this metadata is stored for matching—the full content isn't held in memory until needed.
**Level 2: Instructions** - When your request matches a skill's description, Roo uses [`read_file`](/advanced-usage/available-tools/read-file) to load the full SKILL.md instructions into context.
**Level 3: Resources** - The prompt tells Roo it may access bundled files (scripts, templates, references) alongside the skill. There's no separate resource manifest—Roo discovers these files on-demand when the instructions reference them.
This architecture means skills remain dormant until activated—they don't bloat your base prompt. You can install many skills, and Roo loads only what's relevant for each task.
---
## Creating Your First Skill
#### 1. Choose a location
**Global skills** (available in all projects):
```bash
# Linux/macOS — Roo-specific (higher priority)
~/.roo/skills/{skill-name}/SKILL.md
# Linux/macOS — cross-agent (shared with other agent tools)
~/.agents/skills/{skill-name}/SKILL.md
# Windows
%USERPROFILE%\.roo\skills\{skill-name}\SKILL.md
%USERPROFILE%\.agents\skills\{skill-name}\SKILL.md
```
**Project skills** (specific to current workspace):
```bash
# Roo-specific (higher priority)
<project-root>/.roo/skills/{skill-name}/SKILL.md
# Cross-agent (shared with other agent tools)
<project-root>/.agents/skills/{skill-name}/SKILL.md
```
#### 2. Create the skill directory and file
```bash
# Example: PDF processing skill
mkdir -p ~/.roo/skills/pdf-processing
touch ~/.roo/skills/pdf-processing/SKILL.md
```
#### 3. Write the SKILL.md file
The file requires frontmatter with `name` and `description`:
```markdown
---
name: pdf-processing
description: Extract text and tables from PDF files using Python libraries
---
# PDF Processing Instructions
When the user requests PDF processing:
1. Check if PyPDF2 or pdfplumber is installed
2. For text extraction, use pdfplumber for better table detection
3. For simple text-only PDFs, PyPDF2 is sufficient
4. Always handle encoding errors gracefully
5. Offer to save extracted content to a file
## Code Template
[Your detailed code patterns here]
## Common Issues
- Encrypted PDFs: Explain they require password parameter
- Scanned PDFs: Recommend OCR tools like pytesseract
- Large files: Suggest page-by-page processing
```
**Naming rules:**
- The `name` field must exactly match the directory name (or symlink name)
- Names must be 1–64 characters, lowercase letters/numbers/hyphens only
- No leading/trailing hyphens, no consecutive hyphens (e.g., `my--skill` is invalid)
- Both `name` and `description` are required
- Descriptions must be 1–1024 characters (trimmed)
- The description tells Roo when to use this skill—be specific
#### 4. Test the skill
Ask Roo something matching the description:
```
"Can you help me extract tables from this PDF file?"
```
Roo should recognize the request matches your skill description, load the SKILL.md file, and follow its instructions.
---
## Directory Structure
#### Basic structure
```
~/.roo/skills/ # Global Roo-specific skills (high priority)
├── pdf-processing/
│ ├── SKILL.md # Required
│ ├── extract.py # Optional: bundled scripts
│ └── templates/ # Optional: related files
│ └── output-template.md
└── api-docs-generator/
└── SKILL.md
~/.agents/skills/ # Global cross-agent skills (shared with other agent tools)
└── shared-workflow/
└── SKILL.md
.roo/skills/ # Project Roo-specific skills (override global)
└── custom-pdf-workflow/
└── SKILL.md
.agents/skills/ # Project cross-agent skills (shared with other agent tools)
└── team-shared-skill/
└── SKILL.md
```
#### Mode-specific skills
Create skills that only activate in specific modes:
```
~/.roo/skills-code/ # Only in Code mode (Roo-specific, global)
└── refactoring-patterns/
└── SKILL.md
.roo/skills-architect/ # Only in Architect mode (Roo-specific, project)
└── system-design-templates/
└── SKILL.md
~/.agents/skills-code/ # Only in Code mode (cross-agent, global)
└── shared-code-skill/
└── SKILL.md
.agents/skills-{modeSlug}/ # Mode-specific, cross-agent, project
```
**When to use mode-specific skills:**
- Code refactoring patterns (Code mode only)
- System design templates (Architect mode only)
- Documentation standards (specific to a doc writing mode)
---
## Override Priority
When skills with the same name exist in multiple locations, this priority applies (highest to lowest). `.roo/` paths always take precedence over `.agents/` paths at the same project level:
1. **Project `.roo` mode-specific** (`.roo/skills-code/my-skill/`) — highest priority
2. **Project `.roo` generic** (`.roo/skills/my-skill/`)
3. **Project `.agents` mode-specific** (`.agents/skills-code/my-skill/`)
4. **Project `.agents` generic** (`.agents/skills/my-skill/`)
5. **Global `.roo` mode-specific** (`~/.roo/skills-code/my-skill/`)
6. **Global `.roo` generic** (`~/.roo/skills/my-skill/`)
7. **Global `.agents` mode-specific** (`~/.agents/skills-code/my-skill/`)
8. **Global `.agents` generic** (`~/.agents/skills/my-skill/`) — lowest priority
A **project** skill always overrides a **global** skill of the same name. Within the same project level, `.roo/` overrides `.agents/`.
This lets you:
- Set global standards that work everywhere
- Override them per-project when needed (even with generic skills)
- Specialize skills for specific modes within each location
---
## Skill Discovery
Roo automatically discovers skills:
- **At startup**: All skills are indexed by reading and parsing each SKILL.md
- **During development**: File watchers detect changes to SKILL.md files
- **Mode filtering**: Only skills relevant to the current mode are available
You don't need to register or configure skills—just create the directory structure.
#### Symlink support
Skills support symbolic links for sharing skill libraries across projects:
```bash
# Share a skill library across projects
ln -s /shared/company-skills ~/.roo/skills/company-standards
```
The skill name comes from the symlink name (or directory name if not symlinked). The frontmatter `name` field must match this name exactly—you can't create aliases with different names pointing to the same skill.
---
## Troubleshooting
#### Skill isn't loading
**Symptom**: Roo doesn't use your skill even when you request something matching the description.
**Causes & fixes**:
1. **Name mismatch**: The frontmatter `name` field must exactly match the directory name
```markdown
# ✗ Wrong - directory is "pdf-processing"
---
name: pdf_processing
---
# ✓ Correct
---
name: pdf-processing
---
```
2. **Missing required fields**: Both `name` and `description` are required in frontmatter
3. **Wrong mode**: If the skill is in `skills-code/` but you're in Architect mode, it won't load. Move to `skills/` for all modes or create mode-specific variants.
4. **Description too vague**: Make descriptions specific so Roo can match them to requests
```markdown
# ✗ Vague
description: Handle files
# ✓ Specific
description: Extract text and tables from PDF files using Python libraries
```
#### Skill loads but doesn't help
**Symptom**: Roo reads the skill but doesn't follow instructions.
**Cause**: Instructions may be too general or missing critical details.
**Fix**: Make instructions actionable:
- Include specific function names or library choices
- Provide code templates
- List common edge cases and how to handle them
- Add troubleshooting guidance for the specific task
#### Multiple skills conflict
**Symptom**: Unclear which skill Roo will use when multiple might match.
**Cause**: Overlapping descriptions or mode configurations.
**Prevention**:
- Make descriptions distinct and specific
- Use mode-specific directories to separate concerns
- Rely on override priority—project skills override global
#### Can't share skills with team
**Symptom**: Want team members to use the same skills.
**Solution**: Place skills in `.roo/skills/` within your project and commit to version control. Each team member gets the same skills automatically.
---
## Skills vs Custom Instructions vs Slash Commands
| Feature | Skills | Custom Instructions | Slash Commands |
|---------|--------|---------------------|----------------|
| **When loaded** | On-demand (when request matches) | Always (part of base prompt) | On-demand (when invoked) |
| **Best for** | Task-specific workflows | General coding standards | Retrieving pre-written content |
| **Can bundle files** | Yes | No | No |
| **Mode targeting** | Yes (`skills-{mode}` directories) | Yes (`rules-{mode}` directories) | No |
| **Override priority** | Project > Global, Mode > Generic | Project > Global | Project > Global |
| **Format** | SKILL.md with frontmatter | Any text file | JSON metadata + content |
| **Discovery** | Automatic (directory scan) | Automatic (directory scan) | Automatic (directory scan) |
**When to use each:**
- **Skills**: "Generate API docs following OpenAPI spec" → Detailed OpenAPI processing instructions load only when needed
- **Custom Instructions**: "Always use TypeScript strict mode" → Applies to all TypeScript work
- **Slash Commands**: `/init` → Returns standardized project setup instructions
---
## Skill Specification
Roo Code skills follow the [Agent Skills](https://agentskills.io/) format for skill packaging and metadata. Skills are **instruction packages with optional bundled files**—they don't register new executable tools.
**Required conventions:**
- The frontmatter `name` must exactly match the directory (or symlink) name
- Both `name` and `description` fields are required in frontmatter
- Names: 1–64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens
- Descriptions: 1–1024 chars (trimmed)
#### Roo-specific enhancements
Roo Code adds mode-specific targeting and cross-agent compatibility beyond the base format:
- **Roo-specific locations**: `.roo/skills/`, `~/.roo/skills/` (higher priority)
- **Cross-agent locations**: `.agents/skills/`, `~/.agents/skills/` (shared with other agent tools)
- **Mode-specific directories**: `skills-{mode}/` (e.g., `skills-code/`, `skills-architect/`) in both `.roo/` and `.agents/` paths enable mode targeting
---
## See Also
- [Custom Instructions](/features/custom-instructions) - Set general rules that apply to all work
- [Slash Commands](/features/slash-commands) - Execute commands that return content
- [Custom Modes](/features/custom-modes) - Create specialized modes with specific tool access

446
apps/docs/docs/features/slash-commands.mdx Normal file
View file

@ -0,0 +1,446 @@
---
description: Learn how to create and use custom slash commands in Roo Code to automate workflows and extend functionality with markdown-based definitions.
keywords:
- slash commands
- custom commands
- Roo Code commands
- command automation
- workflow automation
- markdown commands
- .roo/commands
---
# Slash Commands
Create custom slash commands to automate repetitive tasks and extend Roo Code's functionality with simple markdown files.
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/IOpmeUGLpg0?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
title="Slash Commands Tutorial Video"
></iframe>
</div>
<br />
:::tip Quick Start
Type `/` in chat to select a command. To create or manage commands, open Settings > Slash Commands. You can still store commands in `.roo/commands/` (project) or `~/.roo/commands/` (global).
:::
---
## Overview
Slash commands let you create reusable prompts and workflows that can be triggered instantly. Turn complex multi-step processes into single commands, standardize team practices, and automate repetitive tasks with simple markdown files.
<img src="/img/slash-commands/slash-commands-5.png" alt="Slash commands menu showing available commands" width="500" />
**Key Benefits:**
- **Workflow Automation**: Turn complex multi-step processes into single commands
- **Team Standardization**: Share commands across your team for consistent practices
- **Context Preservation**: Include project-specific context in every command
- **Quick Access**: Fuzzy search and autocomplete for instant command discovery
---
## Creating Custom Commands
Custom commands extend Roo Code's functionality by adding markdown files to specific directories:
- **Project-specific**: `.roo/commands/` in your workspace root
- **Global**: `~/.roo/commands/` in your home directory
The filename becomes the command name. For example:
- `review.md` → `/review`
- `test-api.md` → `/test-api`
- `deploy-check.md` → `/deploy-check`
:::info Command Name Processing
When creating commands in Settings > Slash Commands, command names are automatically processed:
- Converted to lowercase
- Spaces replaced with dashes
- Special characters removed (except dashes)
- Multiple consecutive dashes replaced with single dash
- Leading/trailing dashes removed
Example: "My Cool Command!" becomes `my-cool-command`
:::
**Basic Command Format**
Create a simple command by adding a markdown file:
```markdown
# review.md
Please review this code for:
- Performance issues
- Security vulnerabilities
- Code style violations
- Potential bugs
```
**Advanced Command with Frontmatter**
Add metadata using frontmatter for enhanced functionality:
```yaml
---
description: Comprehensive code review focusing on security and performance
argument-hint: <file or directory to review>
---
# Security-First Code Review
Please perform a thorough security review of the selected code:
1. **Authentication & Authorization**
- Check for proper access controls
- Verify token validation
- Review permission checks
2. **Input Validation**
- Identify potential injection points
- Check for proper sanitization
- Review data type validation
3. **Security Best Practices**
- Look for hardcoded secrets
- Check for secure communication
- Review error handling for information leakage
```
**Frontmatter Fields:**
- **`description`**: Appears in the command menu to help users understand the command's purpose
- **`argument-hint`**: (Optional) Provides a hint about expected arguments when using the command. See [Argument Hints](#argument-hints) for detailed information
- **`mode`**: (Optional) Mode slug to switch to before running the command (e.g., `code`, `architect`). Roo switches to this mode first, then executes the command content in that mode's context
---
## Command Management
Create and maintain commands from Settings.
1. Click the gear icon in Roo Code and open Settings
2. Go to the Slash Commands tab
3. Click "New Command", name it, and choose location (Project or Global)
4. The command file opens with starter template content
<img src="/img/slash-commands/slash-commands-6.png" alt="Settings > Slash Commands tab for creating and managing commands" width="600" />
---
## Using Slash Commands
Type `/` in the chat to open the selection-only command menu. Use the gear icon to open Settings > Slash Commands for creating and editing commands.
<img src="/img/slash-commands/slash-commands-5.png" alt="Slash command popover with gear icon that opens Settings > Slash Commands" width="600" />
1. Selection-only: Pick from existing commands; creation and editing live in Settings
2. Autocomplete: Start typing to filter commands (e.g., `/sam` shows `sample-command-name`)
3. Description Preview: See command descriptions in the menu
4. Command Priority: Project commands override global commands with the same name
---
## Argument Hints
Argument hints provide instant help for slash commands, showing you what kind of information to provide when a command expects additional input.
When you type `/` to bring up the command menu, commands that expect arguments will display a light gray hint next to them. This hint tells you what kind of argument the command is expecting.
For example:
- `/mode <mode_slug>` - The hint `<mode_slug>` indicates you should provide a mode name like `code` or `debug`
- `/api-endpoint <endpoint-name> <http-method>` - Shows you need both an endpoint name and HTTP method
After selecting the command, it will be inserted into the chat input followed by a space. The hint is not inserted; it is only a visual guide to help you know what to type next. You must then manually type the argument after the command.
**Adding Argument Hints to Custom Commands**
You can add argument hints to your custom commands using the `argument-hint` field in the frontmatter:
```yaml
---
description: Generate a new REST API endpoint with best practices
argument-hint: <endpoint-name> <http-method>
---
```
This will display as `/api-endpoint <endpoint-name> <http-method>` in the command menu.
**Best Practices for Argument Hints:**
- **Be Specific**: Use descriptive placeholders like `<file-path>` instead of generic ones like `<arg>`
- **Show Multiple Arguments**: If your command needs multiple inputs, show them all: `<source> <destination>`
- **Use Consistent Format**: Always wrap placeholders in angle brackets: `<placeholder>`
- **Keep It Concise**: Hints should be brief and clear
**Common Questions:**
- **"What if I don't provide the argument?"** The command might not work as expected, or it might prompt you for more information. The hint is there to help you get it right the first time.
- **"Do all commands have hints?"** No, only commands that are designed to take arguments will have hints. Commands that work without additional input won't show hints.
- **"Can I use a command without replacing the hint?"** The hint text (like `<mode_slug>`) needs to be replaced with actual values. Leaving the hint text will likely cause the command to fail or behave unexpectedly.
---
## Examples and Use Cases
**Mode-Targeting Commands**
Use the `mode` field to ensure a command runs in a specific mode context:
```yaml
---
description: Analyze architecture and propose improvements
mode: architect
---
Review the current system architecture and suggest improvements for:
- Scalability bottlenecks
- Component coupling
- Security boundaries
- Data flow optimization
```
When you run this command, Roo switches to Architect mode first, then processes the command content with Architect's role definition and tool restrictions.
**Development Workflows**
**API Endpoint Generator**
```yaml
---
description: Generate a new REST API endpoint with best practices
argument-hint: <endpoint-name> <http-method>
---
Create a new REST API endpoint with the following specifications:
- Proper error handling
- Input validation
- Authentication middleware
- OpenAPI documentation
- Unit tests
- Integration tests
Follow our project's API conventions and patterns.
```
**Database Migration Helper**
```yaml
---
description: Create a database migration with rollback support
---
Generate a database migration that:
1. Includes both up and down migrations
2. Has proper transaction handling
3. Includes data validation
4. Provides clear migration descriptions
5. Follows our naming conventions
Remember to check for dependent migrations and data integrity.
```
**Code Quality**
**Performance Analyzer**
```yaml
---
description: Analyze code for performance bottlenecks
---
Analyze the selected code for performance issues:
- Identify O(n²) or worse algorithms
- Find unnecessary database queries
- Detect memory leaks
- Suggest caching opportunities
- Recommend async/await optimizations
- Check for proper resource cleanup
```
**Refactoring Assistant**
```yaml
---
description: Suggest refactoring improvements for cleaner code
---
Review this code and suggest refactoring improvements:
- Extract repeated code into functions
- Improve variable and function names
- Simplify complex conditionals
- Apply SOLID principles
- Reduce coupling between components
- Improve testability
```
**Documentation**
**README Generator**
```yaml
---
description: Create a comprehensive README for the current project
---
Generate a README.md file that includes:
1. Project title and description
2. Installation instructions
3. Usage examples
4. API documentation
5. Configuration options
6. Contributing guidelines
7. License information
Base it on the current project structure and existing code.
```
**API Documentation**
```yaml
---
description: Generate OpenAPI/Swagger documentation
---
Create OpenAPI 3.0 documentation for the API endpoints in this file:
- Include all HTTP methods
- Document request/response schemas
- Add example requests and responses
- Include authentication requirements
- Document error responses
- Add descriptive summaries
```
**Testing**
**Test Generator**
```yaml
---
description: Generate comprehensive test suites
---
Create tests for the selected code:
1. Unit tests for all public methods
2. Edge case testing
3. Error handling tests
4. Mock external dependencies
5. Performance benchmarks
6. Integration tests where applicable
Use our project's testing framework and conventions.
```
**Test Coverage Analyzer**
```yaml
---
description: Identify missing test coverage
---
Analyze the current test coverage and:
- Identify untested code paths
- Suggest additional test cases
- Find edge cases not covered
- Recommend integration tests
- Check for proper error testing
```
---
## Best Practices
**Command Naming:**
- Use descriptive, action-oriented names
- Keep names concise but clear
- Use hyphens for multi-word commands
- Avoid generic names like `help` or `test`
- Note: Names are automatically slugified (lowercase, special characters removed)
- The `.md` extension is automatically added/removed as needed
**Command Content:**
- Start with a clear directive
- Use structured formats (lists, sections)
- Include specific requirements
- Reference project conventions
- Keep commands focused on a single task
**Organization:**
- Group related commands in subdirectories
- Use consistent naming patterns
- Document complex commands
- Version control your commands
- Share team commands in the project repository
---
## Built-in Commands
Roo Code includes powerful built-in commands that provide specialized functionality:
### The `init` Command
The `/init` command is a comprehensive AI assistant setup tool that analyzes your codebase and creates tailored configuration files. This powerful command:
**Performs Multi-Phase Analysis:**
- **Discovery Phase**: Scans your project structure and identifies key technologies
- **Project Identification**: Determines project type, frameworks, and dependencies
- **Architecture Mapping**: Analyzes code organization and patterns
- **Build/Test Detection**: Identifies build tools, test frameworks, and scripts
- **Code Style Extraction**: Captures coding conventions and patterns
**Creates AI Assistant Configuration:**
- Generates mode-specific `AGENTS.md` files in `.roo/rules-*` directories
- Creates detailed rules for different AI assistant modes (Code, Architect, Debug, etc.)
- Produces concise, high-signal documentation following the "non-obvious-only" principle
- Supports multiple AI assistant formats (Claude, Cursor, Copilot)
**Manages Project Setup:**
- Creates comprehensive todo lists for project initialization
- Identifies security and performance considerations
- Documents project-specific conventions and patterns
- Enforces quality criteria for generated documentation
**Usage:**
Simply type `/init` in the chat to analyze your codebase and set up AI assistant configuration files tailored to your project.
:::tip
The `init` command is especially useful when starting work on a new project or when you want to establish consistent AI assistant behavior across your team.
:::
## Troubleshooting
**Commands Not Appearing:**
- **Check file location**: Ensure custom command files are in `.roo/commands/` or `~/.roo/commands/`
- **Verify file extension**: Custom commands must be `.md` files
- **Reload window**: Sometimes VS Code needs to be reloaded to detect new command files
**Command Not Found:**
When a slash command isn't found, the LLM will see an error message indicating where commands should be located. This helps guide you to create the command in the right place.
**Command Template Content:**
New commands created through the UI receive template content to help you get started. This template includes basic structure and examples that you can customize.
**Command Conflicts:**
- Project commands (`.roo/commands/`) override global commands (`~/.roo/commands/`) with the same name
- Built-in commands cannot be overridden
- When creating duplicate names through the UI, numbers are appended (e.g., `new-command-1`, `new-command-2`)
**File System Errors:**
- **Permission Issues**: Ensure you have write permissions to the `.roo/commands/` directory
- **Directory Creation**: The system will attempt to create the commands directory if it doesn't exist
- **Symbolic Links**: Command directories support symbolic links for sharing commands across projects
:::info About Mode Commands
The slash menu includes mode-switching commands (like `/code`, `/ask`) that fundamentally change the AI's operational mode - they don't just inject text but switch the entire AI context. Custom modes you create also appear as slash commands (e.g., a mode with slug `reviewer` becomes `/reviewer`). These mode commands cannot be overridden by custom workflow commands. Learn more in [Using Modes](/basic-usage/using-modes) and [Custom Modes](/features/custom-modes).
:::
---
## See Also
- [Using Modes](/basic-usage/using-modes) - Learn about Roo Code's different operational modes
- [Custom Instructions](/features/custom-instructions) - Set persistent instructions for Roo Code
- [Keyboard Shortcuts](/features/keyboard-shortcuts) - Quick access to commands
- [Task Management](/features/task-todo-list) - Manage complex workflows

67
apps/docs/docs/features/suggested-responses.md Normal file
View file

@ -0,0 +1,67 @@
---
description: Learn how suggested responses in Roo Code help you quickly answer follow-up questions with pre-formulated options, speeding up your workflow.
keywords:
- suggested responses
- follow-up questions
- quick answers
- workflow optimization
- ask_followup_question tool
sidebar_label: Suggested Responses
---
import Codicon from '@site/src/components/Codicon';
# Suggested Responses
When Roo needs more information to complete a task, it uses the [`ask_followup_question` tool](/advanced-usage/available-tools/ask-followup-question). To make responding easier and faster, Roo often provides suggested answers alongside the question.
---
## Overview
Suggested Responses appear as clickable buttons directly below Roo's question in the chat interface. They offer pre-formulated answers relevant to the question, helping you provide input quickly.
<img src="/img/suggested-responses/suggested-responses.png" alt="Example of Roo asking a question with suggested response buttons below it" width="500" />
---
## How It Works
1. **Question Appears**: Roo asks a question using the `ask_followup_question` tool.
2. **Suggestions Displayed**: If suggestions are provided by Roo, they appear as buttons below the question.
3. **Interaction**: You can interact with these suggestions in two ways.
---
## Interacting with Suggestions
You have three options for using suggested responses:
1. **Direct Selection**:
- **Action**: Simply click the button containing the answer you want to provide.
- **Result**: The selected answer is immediately sent back to Roo as your response. This is the quickest way to reply if one of the suggestions perfectly matches your intent.
2. **Keyboard Shortcut**:
- **Action**: Use the `roo.acceptInput` command with your configured keyboard shortcut.
- **Result**: The primary (first) suggestion button is automatically selected.
- **Note**: For setup details, see [Keyboard Shortcuts](/features/keyboard-shortcuts).
3. **Edit Before Sending**:
- **Action**:
- Hold down `Shift` and click the suggestion button.
- _Alternatively_, hover over the suggestion button and click the pencil icon (<Codicon name="edit" />) that appears.
- **Result**: The text of the suggestion is copied into the chat input box. You can then modify the text as needed before pressing Enter to send your customized response. This is useful when a suggestion is close but needs minor adjustments.
<img src="/img/suggested-responses/suggested-responses-1.png" alt="Chat input box showing text copied from a suggested response, ready for editing" width="600" />
---
## Benefits
- **Speed**: Quickly respond without typing full answers.
- **Clarity**: Suggestions often clarify the type of information Roo needs.
- **Flexibility**: Edit suggestions to provide precise, customized answers when needed.
This feature streamlines the interaction when Roo requires clarification, allowing you to guide the task effectively with minimal effort.

180
apps/docs/docs/features/task-todo-list.mdx Normal file
View file

@ -0,0 +1,180 @@
---
description: Learn how to use Roo Code's task todo list feature to track progress on complex tasks, manage subtasks, and stay organized.
keywords:
- todo list
- task management
- progress tracking
- subtasks
- project organization
---
# Task Todo List
Keep your tasks on track with integrated todo management that helps you stay organized and focused on your development goals. Task Todo Lists provide interactive, persistent checklists that track your progress through complex, multi-step workflows directly within the chat interface.
<img src="/img/task-todo-list/task-todo-list-3.png" alt="Task Todo List overview showing interactive checklist in Roo Code" width="600" />
:::tip Todo List Triggers
Todo lists are automatically created for complex tasks, multi-step workflows, or when using Architect mode. You can also manually trigger them by asking Roo to "use the update_todo_list tool" or "create a todo list".
See [When Roo Creates Todo Lists](#when-roo-creates-todo-lists) for detailed information about automatic and manual triggers.
:::
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/6h5vB9PpoPk?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
<br />
---
## Use Case
**Before**: Manually tracking steps for a complex task in your head or a separate notes file, making it easy to lose track of progress and next steps.
**With Task Todo Lists**: Roo Code automatically creates and manages a structured checklist embedded in the conversation. You can see the status of each item, watch as the AI marks items complete, and provide feedback when Roo presents updates for approval.
---
## How It Works
The Task Todo List feature is powered by the [`update_todo_list`](/advanced-usage/available-tools/update-todo-list) tool, which enables dynamic task management within the chat interface.
### When Roo Creates Todo Lists
Roo creates todo lists through both automatic detection and manual requests:
- **Task complexity detected** - Multiple steps, phases, or dependencies identified in your request
- **Working in Architect mode** - Always creates todo lists as the primary planning tool for structuring work
- **Direct tool request** - Say "use the update_todo_list tool" or "please use update_todo_list"
Remember: Even when manually triggered, Roo maintains control over the todo list content and workflow. You provide feedback during approval dialogs, but Roo manages the list based on task needs.
### Display and Interaction
Todo lists appear in multiple places:
1. **Task Header Summary**: A compact, read-only display showing progress and the next important item via the `TodoListDisplay` component
<img src="/img/task-todo-list/task-todo-list-1.png" alt="Task header summary showing todo list progress" width="600" />
2. **Interactive Tool Block**: An interface within the chat via the `UpdateTodoListToolBlock` component that allows you to:
- View all todo items with their current status
- Click the "Edit" button to enter edit mode where you can:
- Modify task descriptions directly
- Change task status using dropdown selectors
- Delete tasks with the × button
- Add new tasks with the "+ Add Todo" button
- Stage changes that are applied when Roo next updates the list
- View the progression as Roo manages the todo workflow
<img src="/img/task-todo-list/task-todo-list-2.png" alt="Interactive todo list tool block in chat" width="600" />
3. **Environment Details**: Todo lists appear as a "REMINDERS" table in the environment_details section, giving the AI persistent access to current todo state. Note: If the `todoListEnabled` setting is disabled, the reminders section will not appear in environment details.
### Expanded Todo View
When you click on the collapsed todo summary in the task header, a floating panel appears with enhanced functionality:
- **Backdrop overlay**: Click outside the panel to close it
- **Full todo list display**: Shows all todos with their current status indicators
- **Auto-scroll**: Automatically scrolls to the current in-progress task
- **Smooth animations**: Collapse and expand transitions for better user experience
- **Persistent state**: Maintains your scroll position when reopening
### Understanding Task Status
Roo Code automatically manages status progression based on task progress. Each todo item has one of three states:
**Pending**: Shows an empty circle with a border, indicating the task hasn't been started yet
![Pending todo item with empty circle](../../static/img/task-todo-list/task-todo-list-4.png)
**In Progress**: Displays a filled yellow circle, showing the task is currently being worked on
![In progress todo item with yellow circle](../../static/img/task-todo-list/task-todo-list-5.png)
**Completed**: Features a filled green circle, confirming the task is fully finished
![Completed todo item with green circle](../../static/img/task-todo-list/task-todo-list-6.png)
### Editing Todo Lists During Approval
When Roo presents a todo list update for approval, you have full control through the Edit mode:
1. **Click "Edit"** to enter edit mode
2. **Make your changes**:
- Edit task descriptions inline
- Change status using the dropdown menu (Pending/In Progress/Completed)
- Remove tasks with the × button
- Add new tasks with the "+ Add Todo" button at the bottom
3. **Save or Cancel** your changes
4. **Approve or Reject** the overall update
Note: Your edits are staged and only applied when Roo processes the next todo list update. This maintains Roo's control over the workflow while giving you input on task details.
---
## FAQ
**"Can I create my own todo lists?"**
Yes, you can manually trigger todo list creation by asking Roo to "use the update_todo_list tool" or "create a todo list". However, Roo maintains control over the todo list content and workflow - you provide feedback during approval dialogs, but Roo manages the list based on task needs.
**"Can I use todo lists for simple tasks?"**
Roo Code typically only creates todo lists for complex, multi-step tasks where they provide clear value. For simple tasks, the overhead of list management isn't necessary.
**"Why can't I directly control the todo list?"**
This is an architectural design decision where Roo Code maintains authority over task management. You provide guidance and feedback, but Roo controls the workflow to ensure consistent task progression and accurate status tracking.
---
## Configuration
### Todo List Settings
Roo Code provides VS Code settings to control todo list behavior. These settings can be configured in your VS Code `settings.json` file (`Ctrl/Cmd + Shift + P` → "Preferences: Open User Settings (JSON)").
#### Require Todo Lists for New Tasks
**Setting**: `roo-cline.newTaskRequireTodos`
- **Type**: Boolean
- **Default**: `false`
When enabled, this setting requires a todo list when creating new tasks via [boomerang](/features/boomerang-tasks) or subtask delegation. This ensures structured planning for complex work by mandating that new tasks include a checklist of steps to complete.
**Example configuration**:
```json
{
"roo-cline.newTaskRequireTodos": true
}
```
#### Prevent Completion with Open Todos
**Setting**: `roo-cline.preventCompletionWithOpenTodos`
- **Type**: Boolean
- **Default**: `false`
When enabled, this setting prevents task completion when there are uncompleted todo items. Roo Code will not allow you to mark a task as complete if the todo list still has pending items, ensuring all planned work is finished before closing the task.
**Example configuration**:
```json
{
"roo-cline.preventCompletionWithOpenTodos": true
}
```
### Disabling Todo Lists
You can disable todo lists entirely through the `todoListEnabled` setting. When disabled:
- Roo will not create todo lists for any tasks
- The REMINDERS section will not appear in environment details
- Existing todo lists will remain visible but won't be updated

166
apps/docs/docs/features/worktrees.mdx Normal file
View file

@ -0,0 +1,166 @@
---
description: Use Git worktrees to work on multiple branches simultaneously with Roo Code, each in its own VS Code window.
keywords:
- worktrees
- git worktrees
- multiple branches
- parallel development
- branch management
- agentic coding
---
# Worktrees
Git worktrees allow you to work on multiple branches of the same repository simultaneously by keeping them in different directories. Each worktree gets its own VS Code window with Roo Code, enabling parallel development without branch switching.
This is particularly powerful for agentic coding workflows where you might want to:
- Test different implementation approaches in parallel
- Review pull requests without disrupting your current work
- Run multiple tasks on different branches simultaneously
- Maintain separate environments for development and debugging
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe title="Worktrees Tutorial Video"
src="https://www.youtube.com/embed/BRrhcYYSh9M?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
<div style={{ marginTop: '20px' }}></div>
:::note Requirements
- Git must be installed on your system
- Your workspace must be a Git repository
- Multi-root workspaces are not supported
- Workspace must be at the repository root (not a subfolder)
:::
---
## Getting Started
### Accessing Worktrees
You can access the worktrees feature in two ways:
1. **Home Screen**: When you have multiple worktrees, a worktree selector appears at the top of the chat interface
- Click the selector to see all your worktrees
- Click on any worktree to switch to it
- Click the `+` button to create a new worktree
- Click the ⚙️ to manage worktrees
2. **Settings Panel**: from the last point above or via Settings (⚙️) → Worktrees
- View and manage all your worktrees
- Create new worktrees
- Delete existing worktrees
- Configure `.worktreeinclude` settings
- Choose whether to show the selector in the home screen
### Creating Your First Worktree
1. Open the Roo Code settings by clicking the gear icon
2. Navigate to the "Worktrees" section
3. Click the "Create worktree" button
4. Fill in the required fields:
- **Base Branch**: The branch to create your new branch from (typically `main` or `develop`)
- **Branch Name**: Name for the new branch (e.g., `worktree/feature-name`)
- **Worktree Path**: Location where the worktree will be created
5. Click "Create"
6. Choose whether to open the new worktree in a new window or stay in your current window
The worktree will be created with all the files from the base branch, and you can immediately start working on it.
---
## Key Functionality
### Switching Between Worktrees
Once you have multiple worktrees, switching between them is seamless:
**From the Home Screen**:
- Click the worktree selector at the top of the chat
- Select the worktree you want to switch to
- Choose whether to switch in the current window or open a new window
**From Settings**:
- Navigate to Settings → Worktrees
- Click on any worktree to switch to it in the current window
- Click the icon to open in a new window
:::tip Multiple Windows
Opening worktrees in new windows allows you to have multiple tasks running in parallel, each in its own workspace. This is ideal for comparing different approaches or working on multiple features simultaneously.
:::
### Managing Worktrees
**Viewing Your Worktrees**:
The worktrees list shows:
- Branch name (or "Detached HEAD" if not on a branch)
- Worktree path on your filesystem
- Status indicators (Primary, Locked)
- Current worktree is highlighted
**Deleting Worktrees**:
1. Navigate to Settings → Worktrees
2. Click the trash icon <Codicon name="trash" /> next to the worktree you want to delete
### Copying Files with .worktreeinclude
By default, Git worktrees only include files tracked by Git. Untracked files like `node_modules`, `.env`, or build artifacts aren't copied. The `.worktreeinclude` feature solves this problem.
**How it Works**:
- Create a `.worktreeinclude` file at the root of your repository
- Add patterns for files/directories you want to copy (uses `.gitignore` syntax)
- Files must also be in `.gitignore` to be copied (intersection of both files)
- When creating a new worktree, matching files are automatically copied
**Setting Up .worktreeinclude**:
1. Navigate to Settings → Worktrees
2. If you don't have a `.worktreeinclude` file, you'll see a message at the bottom
3. Click "Create from .gitignore" to automatically create one based on your `.gitignore`
4. Edit the file to include only the patterns you want to copy (e.g., `node_modules`, `.env.local`)
**Example .worktreeinclude**:
```
node_modules
.env.local
.cache
dist
```
:::tip What Gets Copied
Only files that match BOTH `.worktreeinclude` AND `.gitignore` patterns are copied. This ensures you're only copying untracked files that you intentionally want to duplicate across worktrees.
:::
### Home Screen Integration
The worktree selector can be shown or hidden from the home screen:
1. Navigate to Settings → Worktrees
2. Toggle "Show worktrees in home screen"
3. When enabled, the selector appears at the top of the chat when you have multiple worktrees
4. When disabled, you can still manage worktrees from Settings
---
## Tips
- **Organized locations**: Use a consistent location like `~/.roo/worktrees/` for all your worktrees
- **Descriptive branch names**: Use clear naming like `worktree/feature-name` to identify worktree branches later on
- **Regular cleanup**: Delete worktrees you're no longer using to save disk space
- **Commit before deleting**: Always commit and push important changes before deleting a worktree
- **Use .worktreeinclude**: Set up a `.worktreeinclude` file once and benefit from it for all future worktrees
- **New windows for parallel work**: Open worktrees in new windows when you want to work on multiple branches simultaneously

43
apps/docs/docs/getting-started/connecting-api-provider.md Normal file
View file

@ -0,0 +1,43 @@
---
sidebar_label: Connecting To AI Provider
description: Learn how to connect Roo Code to AI providers like Anthropic Claude, OpenAI, and OpenRouter. Step-by-step guide for API key setup and configuration.
keywords:
- Roo Code API key
- Claude API
- OpenAI API
- OpenRouter
- Anthropic API
- AI provider setup
- API configuration
---
import KangarooIcon from '@site/src/components/KangarooIcon';
# Connecting Your First LLM Provider
Roo Code needs an inference provider to access the LLM models that make it work.
A great model to start is **Claude Sonnet 4.5**, which offers a lot of power at a reasonable price point. To get it going, choose a provider:
- **OpenRouter (Recommended):** Provides access to multiple AI models from different labs through a single API key. Great for flexibility and getting started reasonably fast. To get an API key, [follow these instructions <LucideIcon name="ArrowRight" />](/providers/openrouter#getting-an-api-key)
- **Anthropic:** Direct access to the Claude family of models. Requires API access approval and may have [rate limits depending on your tier](https://docs.anthropic.com/en/api/rate-limits#requirements-to-advance-tier). To get an API key, [follow these instructions <LucideIcon name="ArrowRight" />](/providers/anthropic#getting-an-api-key)
Roo Code is compatible with [other providers](/providers) which offer Claude, and with a wide range of different models you can try.
:::info Model Selection Advice
We recommend **Claude Sonnet 4.5** because it "just works" out of the box for most tasks. We use it internally a lot.
You can choose other models, but that introduces complexity. Different models vary in how they follow tool instructions, parse formats, and maintain context through multi-step operations, so it may be better to try them later. If you do experiment with other models, choose ones specifically designed for structured reasoning and tool use.
:::
---
## Configuring the provider in VS Code
1. Open the Roo Code panel by clicking the Roo Code icon (<KangarooIcon />) in the VS Code Activity Bar
2. In the welcome screen, choose your LLM provider.
3. Paste the API key you copied from your provider into the right field and continue.
4. Select your model (it should be called `claude-sonnet-4-5` or `anthropic/claude-sonnet-4-5`) and complete the process.
Now you can start coding!

121
apps/docs/docs/getting-started/installing.mdx Normal file
View file

@ -0,0 +1,121 @@
---
sidebar_label: Installing Roo Code
description: Step-by-step guide to install Roo Code in VS Code, Cursor, VSCodium, and other compatible editors. Get started with AI-powered coding in minutes.
keywords:
- install Roo Code
- VS Code extension
- AI coding assistant installation
- Cursor
- VSCodium
- VSIX installation
---
import KangarooIcon from '@site/src/components/KangarooIcon';
# Installing Roo Code
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/Mcq3r1EPZ-4?rel=0&modestbranding=1"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="autoplay; encrypted-media"
allowFullScreen
></iframe>
</div>
Roo Code is a VS Code extension that brings AI-powered coding assistance directly to your editor. Install using one of these methods:
1. **VS Code Marketplace (Recommended)** - fastest method for standard VS Code and Cursor users
2. **Open VSX Registry** - for VS Code-compatible editors like VSCodium
---
## VS Code Marketplace
1. Open VS Code
2. Access Extensions: Click the Extensions icon in the Activity Bar or press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS)
3. Search for "Roo Code"
4. Select "Roo Code" by RooVeterinaryInc and click **Install**
5. Reload VS Code if prompted
After installation, find the Roo Code icon (<KangarooIcon />) in the Activity Bar to open the Roo Code panel.
<img src="/img/installing/installing-3.png" alt="VS Code marketplace with Roo Code extension ready to install" width="400" />
*VS Code marketplace with Roo Code extension ready to install*
---
## Open VSX Registry
For VS Code-compatible editors without Marketplace access (like VSCodium and Windsurf):
1. Open your editor
2. Access the Extensions view
3. Search for "Roo Code"
4. Select "Roo Code" by RooVeterinaryInc and click **Install**
5. Reload if prompted
<img src="/img/installing/installing-3.png" alt="Open VSX Registry with Roo Code extension ready to install" width="400" />
## Roo Code Nightly
For information on installing Roo Code Nightly (our prerelease build published on each merge to main), please see the [Roo Code Nightly](/advanced-usage/roo-code-nightly) guide in the Advanced Usage section.
## Manual Installation from VSIX
If you prefer to download and install the VSIX file directly:
1. **Download the VSIX file:**
* Find official releases on the [Roo Code GitHub Releases page](https://github.com/RooCodeInc/Roo-Code/releases)
* Download the `.vsix` file from the latest release
2. **Install in VS Code:**
* Open VS Code
* Access Extensions view
* Click the "..." menu in the Extensions view
* Select "Install from VSIX..."
* Browse to and select your downloaded `.vsix` file
<img src="/img/installing/installing-2.png" alt="VS Code's Install from VSIX dialog" width="400" />
*Installing Roo Code using VS Code's "Install from VSIX" dialog*
---
## Local Setup & Development
For instructions on setting up Roo Code for local development, building from source, or contributing, please see the [Local Development Setup](/advanced-usage/local-development-setup) guide in the Advanced Usage section.
---
## Troubleshooting
<img src="/img/installing/installing-4.png" alt="VS Code Output panel showing Roo Code logs for troubleshooting" width="100%" />
*VS Code Output panel showing Roo Code logs for troubleshooting*
**Extension Not Visible**
* Restart VS Code
* Verify Roo Code is listed and enabled in Extensions
* Try disabling and re-enabling
* Check Output panel for errors (View → Output, select "Roo Code")
**Installation Problems**
* Ensure stable internet connection
* Verify VS Code version 1.84.0 or later
* If VS Code Marketplace is inaccessible, try the Open VSX Registry method
---
## Getting Support
If you encounter issues not covered here:
* Join our [Discord community](https://discord.gg/roocode) for real-time support
* Submit issues on [GitHub](https://github.com/RooCodeInc/Roo-Code/issues)
* Visit our [Reddit community](https://www.reddit.com/r/RooCode)

87
apps/docs/docs/getting-started/your-first-task.md Normal file
View file

@ -0,0 +1,87 @@
---
sidebar_label: Your First Task
description: Learn how to start your first task with Roo Code AI assistant. Step-by-step guide for beginners to understand the approval workflow and iterative process.
keywords:
- Roo Code tutorial
- first task
- getting started
- AI coding assistant tutorial
- approval workflow
---
import KangarooIcon from '@site/src/components/KangarooIcon';
# Your first task
Now that you've [configured your AI provider and model](/getting-started/connecting-api-provider), you're ready to start using Roo Code! This guide walks you through your first interaction.
---
## Step 1: Open the Roo Code Panel
Click the Roo Code icon (<KangarooIcon />) in the VS Code Activity Bar (vertical bar on the side of the window) to open the chat interface. If you don't see the icon, verify the extension is installed and enabled.
<figure>
<img src="/img/your-first-task/your-first-task.png" alt="Roo Code icon in VS Code Activity Bar" width="600" />
<figcaption>The Roo Code icon in the Activity Bar opens the chat interface. You can drag it to position Roo elsewhere.</figcaption>
</figure>
## Step 2: Type Your Task
Type a clear, concise description of what you want Roo Code to do in the chat box at the bottom of the panel. Examples of effective tasks:
- "Create a file named `hello.txt` containing 'Hello, world!'."
- "Write a Python function that adds two numbers."
- "Create an HTML file for a simple website with the title 'Roo test'"
No special commands or syntax needed—just use plain English.
<figure>
<img src="/img/your-first-task/your-first-task-6.png" alt="Typing a task in the Roo Code chat interface" width="400" />
<figcaption>Enter your task in natural language - no special syntax required.</figcaption>
</figure>
## Step 3: Send Your Task
Press Enter or click the Send icon (<Codicon name="send" />) to the right of the input box.
## Step 4: Review and Approve Actions
Roo Code analyzes your request and proposes specific actions. These may include:
- **Reading files:** Shows file contents it needs to access
- **Writing to files:** Displays a diff with proposed changes (added lines in green, removed in red)
- **Executing commands:** Shows the exact command to run in your terminal
- **Using the Browser:** Outlines browser actions (click, type, etc.)
- **Asking questions:** Requests clarification when needed to proceed
<figure>
<img src="/img/your-first-task/your-first-task-7.png" alt="Reviewing a proposed file creation action" width="800" />
<figcaption>Roo Code shows exactly what action it wants to perform and waits for your approval.</figcaption>
</figure>
**Each action requires your explicit approval** (unless auto-approval is enabled):
- **Approve:** Click the "Approve" button to execute the proposed action
- **Reject:** Click the "Reject" button and provide feedback if needed
## Step 5: Iterate
Roo Code works iteratively. After each action, it waits for your feedback before proposing the next step. Continue this review-approve cycle until your task is complete.
<figure>
<img src="/img/your-first-task/your-first-task-8.png" alt="Final result of a completed task showing the iteration process" width="500" />
<figcaption>After completing the task, Roo Code shows the final result and awaits your next instruction.</figcaption>
</figure>
---
## Conclusion
You've now completed your first task with Roo Code! Through this process, you've learned:
- How to interact with Roo Code using natural language
- The approval-based workflow that keeps you in control
- The iterative approach Roo Code uses to solve problems step-by-step
This iterative, approval-based workflow is at the core of how Roo Code works—letting AI handle the tedious parts of coding while you maintain complete oversight. Now that you understand the basics, you're ready to tackle more complex tasks, explore different [modes](/basic-usage/using-modes) for specialized workflows, or try the [auto-approval feature](/features/auto-approving-actions) to speed up repetitive tasks.

85
apps/docs/docs/index.mdx Normal file
View file

@ -0,0 +1,85 @@
---
sidebar_label: Welcome
description: Learn how to use Roo Code, the autonomous AI coding agent that helps you code faster and smarter in VS Code. Complete guides, tutorials, and documentation.
keywords:
- Roo Code
- AI coding assistant
- VS Code extension
- autonomous coding agent
- AI pair programmer
- code generation
- documentation
---
# Roo Code Docs
Roo Code is an open-source AI coding agent for VS Code designed to take full advantage of advanced large-language models and change how you create software at a fundamental level. It's powerful, customizable, and model-agnostic, with actual file system access, terminal control, and multi-step workflows.
Roo's approach is to trade tokens for quality. If you want the best and most effective AI coding experience available, this is it.
The Roo Code VS Code extension works locally in your IDE and gives you full control over your coding experience. It's great for deep or highly iterative development work, and it fits into your existing workflow.
## What can Roo Code do for you
- Generate Code from natural language descriptions and specs
- Refactor & debug existing code
- Write & update documentation
- Answer questions about your codebase
- Automate repetitive tasks
- Utilize MCP Servers
## A mindset for success
The most successful Roo users tend to embrace the following ideas:
- **Leverage model agnosticism:** Roo isn't an LLM model, it needs an [LLM provider](/providers) to work. But it's compatible with dozens of providers and hundreds of models, so you're free to experiment, optimize and switch around, by design. No lock-ins in a world where "the best model" changes every other week.
- **Don't skimp on tokens:** expensive state-of-the-art models with lots of tokens will almost always beat cheap models using few tokens. Pay attention to your budget, but embrace the fact that tokens are cheaper than developer time.
- **Trust roles:** The extension's customizable Modes (Architect, Code, etc) keep the models on track and focused on the task at hand, without stepping outside of their boundaries. Lean on them depending on the task you're working on.
- **Be ambitious:** Roo works best the more you trust it. Out-of-the-box, the extension will ask for your permission to do everything, but as you become more comfortable and enable [Auto-Approve](/features/auto-approving-actions), you'll see it work for long periods on its own without getting stuck or making bad decisions. Once ready, throw large, complex projects at the [Orchestrator](/basic-usage/using-modes#orchestrator-mode-aka-boomerang-mode), who will coordinate tasks across Modes.
## Getting Started
- [Install the Extension](/getting-started/installing)
- [Connect an LLM Provider](/getting-started/connecting-api-provider)
## Tutorial & Feature Videos
<div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '.5rem', margin: '0rem' }}>
<a href="https://www.youtube.com/watch?v=Mcq3r1EPZ-4" target="_blank" rel="noopener noreferrer" style={{ textDecoration: 'none', color: 'inherit' }}>
<img src="https://img.youtube.com/vi/Mcq3r1EPZ-4/maxresdefault.jpg" alt="Installing Roo Code" style={{ width: '100%', height: 'auto', borderRadius: '8px', display: 'block' }} />
<div style={{ marginTop: '0.0rem', textAlign: 'center', fontWeight: 600, fontSize: '1rem' }}>Installing Roo Code</div>
</a>
<a href="https://www.youtube.com/watch?v=ZBML8h5cCgo" target="_blank" rel="noopener noreferrer" style={{ textDecoration: 'none', color: 'inherit' }}>
<img src="https://img.youtube.com/vi/ZBML8h5cCgo/maxresdefault.jpg" alt="Configuring Profiles" style={{ width: '100%', height: 'auto', borderRadius: '8px', display: 'block' }} />
<div style={{ marginTop: '0.0rem', textAlign: 'center', fontWeight: 600, fontSize: '1rem' }}>Configuring Profiles</div>
</a>
<a href="https://www.youtube.com/watch?v=r1bpod1VWhg" target="_blank" rel="noopener noreferrer" style={{ textDecoration: 'none', color: 'inherit' }}>
<img src="https://img.youtube.com/vi/r1bpod1VWhg/maxresdefault.jpg" alt="Codebase Indexing" style={{ width: '100%', height: 'auto', borderRadius: '8px', display: 'block' }} />
<div style={{ marginTop: '0.0rem', textAlign: 'center', fontWeight: 600, fontSize: '1rem' }}>Codebase Indexing</div>
</a>
<a href="https://www.youtube.com/watch?v=iiAv1eKOaxk" target="_blank" rel="noopener noreferrer" style={{ textDecoration: 'none', color: 'inherit' }}>
<img src="https://img.youtube.com/vi/iiAv1eKOaxk/maxresdefault.jpg" alt="Custom Modes" style={{ width: '100%', height: 'auto', borderRadius: '8px', display: 'block' }} />
<div style={{ marginTop: '0.0rem', textAlign: 'center', fontWeight: 600, fontSize: '1rem' }}>Custom Modes</div>
</a>
<a href="https://www.youtube.com/watch?v=Ho30nyY332E" target="_blank" rel="noopener noreferrer" style={{ textDecoration: 'none', color: 'inherit' }}>
<img src="https://img.youtube.com/vi/Ho30nyY332E/maxresdefault.jpg" alt="Checkpoints" style={{ width: '100%', height: 'auto', borderRadius: '8px', display: 'block' }} />
<div style={{ marginTop: '0.0rem', textAlign: 'center', fontWeight: 600, fontSize: '1rem' }}>Checkpoints</div>
</a>
<a href="https://www.youtube.com/watch?v=6h5vB9PpoPk" target="_blank" rel="noopener noreferrer" style={{ textDecoration: 'none', color: 'inherit' }}>
<img src="https://img.youtube.com/vi/6h5vB9PpoPk/maxresdefault.jpg" alt="Todo Lists" style={{ width: '100%', height: 'auto', borderRadius: '8px', display: 'block' }} />
<div style={{ marginTop: '0.0rem', textAlign: 'center', fontWeight: 600, fontSize: '1rem' }}>Todo Lists</div>
</a>
</div>
<p style={{ textAlign: 'center', marginTop: '1rem' }}>
<a href="/tutorial-videos">More quick tutorial and feature videos...</a>
</p>
## Additional Resources
- [Discord Server](https://discord.gg/roocode): Join the community for real-time help and discussion.
- [Reddit Community](https://www.reddit.com/r/RooCode): Share your experiences and see what others are building.
- [YouTube Channel](https://youtube.com/@roocodeyt?feature=shared): Watch tutorials and see features in action.
- [GitHub Issues](https://github.com/RooCodeInc/Roo-Code/issues): Report bugs and track development.
- [Feature Requests](https://github.com/RooCodeInc/Roo-Code/discussions/categories/feature-requests?discussions_q=is%3Aopen+category%3A%22Feature+Requests%22+sort%3Atop): Have an idea? Share it with the team.

57
apps/docs/docs/providers/anthropic.md Normal file
View file

@ -0,0 +1,57 @@
---
sidebar_label: Anthropic
description: Configure Anthropic's Claude AI models in Roo Code. Access Claude Opus, Sonnet, and Haiku models with prompt caching and large context windows.
keywords:
- anthropic
- claude
- claude ai
- roo code
- api provider
- claude opus
- claude sonnet
- claude haiku
- prompt caching
- ai models
---
# Using Anthropic With Roo Code
Anthropic is an AI safety and research company that builds reliable, interpretable, and steerable AI systems. Their Claude models are known for their strong reasoning abilities, helpfulness, and honesty.
**Website:** [https://www.anthropic.com/](https://www.anthropic.com/)
---
## Getting an API Key
1. **Sign Up/Sign In:** Go to the [Anthropic Console](https://console.anthropic.com/). Create an account or sign in.
2. **Navigate to API Keys:** Go to the [API keys](https://console.anthropic.com/settings/keys) section.
3. **Create a Key:** Click "Create Key". Give your key a descriptive name (e.g., "Roo Code").
4. **Copy the Key:** **Important:** Copy the API key _immediately_. You will not be able to see it again. Store it securely.
---
## Available Models
Roo Code supports all Claude models available through Anthropic's API.
For the complete, up-to-date model list and capabilities, see [Anthropic's model documentation](https://docs.anthropic.com/en/docs/about-claude/models).
---
## Configuration in Roo Code
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "Anthropic" from the "API Provider" dropdown.
3. **Enter API Key:** Paste your Anthropic API key into the "Anthropic API Key" field.
4. **Select Model:** Choose your desired Claude model from the "Model" dropdown.
5. **(Optional) Custom Base URL:** If you need to use a custom base URL for the Anthropic API, check "Use custom base URL" and enter the URL. Most people won't need to adjust this.
---
## Tips and Notes
- **Prompt Caching:** Claude models support [prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching), which can significantly reduce costs and latency for repeated prompts.
- **Context Window:** Claude models have large context windows (200,000 tokens), allowing you to include a significant amount of code and context in your prompts.
- **Pricing:** Refer to the [Anthropic Pricing](https://www.anthropic.com/pricing) page for the latest pricing information.
- **Rate Limits:** Anthropic has strict rate limits based on [usage tiers](https://docs.anthropic.com/en/api/rate-limits#requirements-to-advance-tier). If you're repeatedly hitting rate limits, consider contacting Anthropic sales or accessing Claude through a different provider like [OpenRouter](/providers/openrouter) or [Requesty](/providers/requesty).

64
apps/docs/docs/providers/baseten.md Normal file
View file

@ -0,0 +1,64 @@
---
title: Baseten
sidebar_label: Baseten
description: Learn how to configure and use Baseten's Model APIs with Roo Code. Access frontier open-source models with enterprise-grade performance, reliability, and competitive pricing.
keywords:
- Baseten
- Model APIs
- open-source models
- DeepSeek
- Kimi K2
- Qwen
- Roo Code
- AI integration
- API key
- enterprise inference
---
# Using Baseten With Roo Code
Baseten provides on-demand frontier model APIs designed for production applications, not just experimentation. Built on the Baseten Inference Stack, these APIs deliver optimized inference for leading open-source models from OpenAI, DeepSeek, Moonshot AI, and Alibaba Cloud.
**Website:** [https://www.baseten.co/products/model-apis/](https://www.baseten.co/products/model-apis/)
---
## Getting an API Key
1. **Sign Up/Sign In:** Go to [Baseten](https://www.baseten.co/) and create an account or sign in.
2. **Navigate to API Keys:** Access your dashboard and go to the API Keys section at [https://app.baseten.co/settings/api_keys](https://app.baseten.co/settings/api_keys).
3. **Create a Key:** Generate a new API key. Give it a descriptive name (e.g., "Roo Code").
4. **Copy the Key:** Copy the API key immediately and store it securely.
---
## Available Models
Roo Code supports all models available through Baseten's Model APIs.
For the complete, up-to-date model list and pricing, see [Baseten's Model APIs page](https://www.baseten.co/products/model-apis/).
---
## Configuration in Roo Code
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "Baseten" from the "API Provider" dropdown.
3. **Enter API Key:** Paste your Baseten API key into the "Baseten API Key" field.
4. **Select Model:** Choose your desired model from the "Model" dropdown.
:::warning Kimi K2 Thinking Model
To use the `moonshotai/Kimi-K2-Thinking` model, you must enable native tool calling in the Roo Code settings. This setting allows Roo Code to call the model's tools through their native tool processor and is required for this reasoning model to function properly.
:::
---
## Tips and Notes
- **Pricing:** See the [Baseten Model APIs page](https://www.baseten.co/products/model-apis/) for current pricing information.

98
apps/docs/docs/providers/bedrock.md Normal file
View file

@ -0,0 +1,98 @@
---
sidebar_label: AWS Bedrock
description: Use Amazon Bedrock with Roo Code to access Claude, Llama, and other foundation models through AWS. Configure credentials and VPC endpoints.
keywords:
- aws bedrock
- amazon bedrock
- roo code
- api provider
- claude bedrock
- llama bedrock
- aws ai
- foundation models
- vpc endpoint
---
# Using AWS Bedrock With Roo Code
Roo Code supports accessing models through Amazon Bedrock, a fully managed service that makes a selection of high-performing foundation models (FMs) from leading AI companies available via a single API.
**Website:** [https://aws.amazon.com/bedrock/](https://aws.amazon.com/bedrock/)
---
## Prerequisites
- **AWS Account:** You need an active AWS account.
- **Bedrock Access:** You must request and be granted access to Amazon Bedrock. See the [AWS Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html) for details on requesting access.
- **Model Access:** Within Bedrock, you need to request access to the specific models you want to use (e.g., Anthropic Claude).
- **Install AWS CLI:** Use AWS CLI to configure your account for authentication
```bash
aws configure
```
---
## Getting Credentials
You have two main options for configuring AWS credentials:
1. **AWS Access Keys (Recommended for Development):**
- Create an IAM user with the necessary permissions (at least `bedrock:InvokeModel`).
- Generate an access key ID and secret access key for that user.
- _(Optional)_ Create a session token if required by your IAM configuration.
2. **AWS Profile:**
- Configure an AWS profile using the AWS CLI or by manually editing your AWS credentials file. See the [AWS CLI documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) for details.
---
## Available Models
Roo Code supports all foundation models available through Amazon Bedrock.
For the complete, up-to-date model list with IDs and capabilities, see [AWS Bedrock's supported models documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html).
**Important:** Use the _model ID_ when configuring Roo Code, not the model name.
---
## Configuration in Roo Code
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "Bedrock" from the "API Provider" dropdown.
3. **Select Authentication Method:**
- **AWS Credentials:**
- Enter your "AWS Access Key" and "AWS Secret Key."
- (Optional) Enter your "AWS Session Token" if you're using temporary credentials.
- **AWS Profile:**
- Enter your "AWS Profile" name (e.g., "default").
4. **Select Region:** Choose the AWS region where your Bedrock service is available (e.g., "us-east-1").
5. **(Optional) Cross-Region Inference:** Check "Use cross-region inference" if you want to access models in a region different from your configured AWS region.
6. **(Optional) VPC Endpoint:** For enterprise environments:
- Check "Use VPC Endpoint" to route all Bedrock API calls through your VPC endpoint
- Enter your VPC endpoint URL in the text field that appears
- This ensures all LLM transactions remain within your corporate network
7. **Select Model:** Choose your desired model from the "Model" dropdown.
---
---
## Reasoning Budget for Claude Models
Roo Code supports using the reasoning budget (extended thinking) for Anthropic's Claude models on Bedrock. This allows the model to "think" more before responding, which can be useful for complex tasks.
To enable the reasoning budget:
1. **Select a supported Claude model** that includes reasoning capabilities.
2. **Enable Reasoning Mode** in the model settings.
3. **Adjust the thinking budget** to control how much the model should "think".
This feature is only available for supported Claude models.
## Tips and Notes
- **Permissions:** Ensure your IAM user or role has the necessary permissions to invoke Bedrock models. The `bedrock:InvokeModel` permission is required.
- **Pricing:** Refer to the [Amazon Bedrock pricing](https://aws.amazon.com/bedrock/pricing/) page for details on model costs.
- **Cross-Region Inference:** Using cross-region inference may result in higher latency.
- **VPC Endpoints:** When using VPC endpoints, ensure your endpoint is properly configured to handle Bedrock API calls. This feature is particularly useful for organizations with strict security requirements that mandate keeping all API traffic within their private network.

51
apps/docs/docs/providers/deepseek.md Normal file
View file

@ -0,0 +1,51 @@
---
sidebar_label: DeepSeek
description: Configure DeepSeek's chat and reasoning models in Roo Code. Access deepseek-chat and deepseek-reasoner for coding and complex reasoning tasks.
keywords:
- deepseek
- deepseek chat
- deepseek reasoner
- roo code
- api provider
- reasoning ai
- coding ai
- deepseek r1
---
# Using DeepSeek With Roo Code
Roo Code supports accessing models through the DeepSeek API, including `deepseek-chat` and `deepseek-reasoner`.
**Website:** [https://platform.deepseek.com/](https://platform.deepseek.com/)
---
## Getting an API Key
1. **Sign Up/Sign In:** Go to the [DeepSeek Platform](https://platform.deepseek.com/). Create an account or sign in.
2. **Navigate to API Keys:** Find your API keys in the [API keys](https://platform.deepseek.com/api_keys) section of the platform.
3. **Create a Key:** Click "Create new API key". Give your key a descriptive name (e.g., "Roo Code").
4. **Copy the Key:** **Important:** Copy the API key _immediately_. You will not be able to see it again. Store it securely.
---
## Available Models
Roo Code supports all models available through the DeepSeek API.
For the complete, up-to-date model list, see [DeepSeek's API documentation](https://api-docs.deepseek.com/quick_start/pricing).
---
## Configuration in Roo Code
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "DeepSeek" from the "API Provider" dropdown.
3. **Enter API Key:** Paste your DeepSeek API key into the "DeepSeek API Key" field.
4. **Select Model:** Choose your desired model from the "Model" dropdown.
---
## Tips and Notes
- **Pricing:** Refer to the [DeepSeek Pricing](https://api-docs.deepseek.com/quick_start/pricing/) page for details on model costs.

59
apps/docs/docs/providers/fireworks.md Normal file
View file

@ -0,0 +1,59 @@
---
sidebar_label: Fireworks AI
description: Use Fireworks AI with Roo Code to access state-of-the-art open-source and proprietary AI models like Kimi, Qwen, and DeepSeek on a high-performance platform with large context windows up to 256K tokens.
keywords:
- fireworks ai
- fireworks
- kimi models
- kimi k2
- qwen models
- qwen3
- deepseek models
- deepseek
- roo code
- api provider
- ai models
- language models
- llm api
- open source models
- serverless models
- openai compatible
---
# Using Fireworks AI With Roo Code
Fireworks AI is a high-performance platform for running AI models, offering fast, cost-effective access to a wide range of state-of-the-art open-source language models. Built for speed and reliability, Fireworks AI provides serverless deployment options with OpenAI-compatible APIs and context windows up to 256,000 tokens.
**Website:** [https://fireworks.ai/](https://fireworks.ai/)
---
## Getting an API Key
1. **Sign Up/Sign In:** Go to [Fireworks AI](https://fireworks.ai/) and create an account or sign in.
2. **Navigate to API Keys:** After logging in, go to the [API Keys page](https://app.fireworks.ai/settings/users/api-keys) in the account settings.
3. **Create a Key:** Click "Create API key" and give your key a descriptive name (e.g., "Roo Code").
4. **Copy the Key:** Copy the API key _immediately_ and store it securely. You will not be able to see it again.
---
## Available Models
Roo Code supports all models available through Fireworks AI's platform.
For the complete, up-to-date model list and specifications, see [Fireworks AI's models page](https://fireworks.ai/models).
---
## Configuration in Roo Code
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "Fireworks AI" from the "API Provider" dropdown.
3. **Enter API Key:** Paste your Fireworks AI API key into the "Fireworks AI API Key" field.
4. **Select Model:** Choose your desired model from the "Model" dropdown.
---
## Tips and Notes
- **Pricing:** See the [Fireworks AI pricing page](https://fireworks.ai/pricing) for current rates.

119
apps/docs/docs/providers/gemini.md Normal file
View file

@ -0,0 +1,119 @@
---
sidebar_label: Google Gemini
description: Use Google's Gemini AI models with Roo Code. Configure Gemini Flash, Pro, and experimental models for your development workflow.
keywords:
- google gemini
- gemini ai
- roo code
- api provider
- gemini flash
- gemini pro
- google ai
- gemini models
- ai studio
---
# Using Google Gemini With Roo Code
Roo Code supports Google's Gemini family of models through the Google AI Gemini API.
**Website:** [https://ai.google.dev/](https://ai.google.dev/)
---
## Getting an API Key
1. **Go to Google AI Studio:** Navigate to [https://ai.google.dev/](https://ai.google.dev/).
2. **Sign In:** Sign in with your Google account.
3. **Create API Key:** Click on "Create API key" in the left-hand menu.
4. **Copy API Key:** Copy the generated API key.
---
## Available Models
Roo Code supports all Gemini models available through Google's API and automatically tracks Google's latest stable releases.
For the complete, up-to-date model list and capabilities, see [Google's Gemini models documentation](https://ai.google.dev/models/gemini).
---
## Configuration in Roo Code
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "Google Gemini" from the "API Provider" dropdown.
3. **Enter API Key:** Paste your Gemini API key into the "Gemini API Key" field.
4. **Select Model:** Choose your desired Gemini model from the "Model" dropdown.
By default, Roo Code selects a stable Pro model with a temperature of **1.0** where your provider supports it. This keeps suggestions more expressive and natural while still staying on task. If you need highly deterministic output (for example, for code generation in CI), you can lower the temperature toward `0.0`.
---
## Advanced Features
### URL Context
Gemini models can now access and analyze web content directly through URL context. This feature allows Roo to:
- Read and understand web pages in real-time
- Analyze documentation from URLs
- Review online code repositories
- Access current information from websites
#### Enabling URL Context
1. Open Roo Code Settings
2. Navigate to the Gemini provider settings
3. Enable "URL Context" option
4. Save your settings
#### Usage Example
```
Please analyze the documentation at https://example.com/api-docs and create a TypeScript client library based on the API specification.
```
### Google Search Grounding
Enable Google Search grounding to enhance Gemini's responses with real-time search results. This provides:
- Up-to-date information from web searches
- Fact-checking capabilities
- Current event awareness
- Enhanced accuracy for technical queries
#### Enabling Search Grounding
1. Open Roo Code Settings
2. Navigate to the Gemini provider settings
3. Enable "Google Search Grounding" option
4. Save your settings
#### Usage Example
```
What are the latest best practices for React Server Components in 2025? Please search for the most recent information.
```
### Combined Usage
Both features can be used together for powerful workflows:
```
Search for the latest Node.js security vulnerabilities and then analyze my package.json file to see if I'm affected. Also check the official Node.js security page for recommendations.
```
---
## Tips and Notes
- **Pricing:** Gemini API usage is priced based on input and output tokens. URL context and search grounding may incur additional costs. Some experimental models are available for free. Refer to the [Gemini pricing page](https://ai.google.dev/pricing) for detailed information.
- **Model Selection:** Choose models based on your needs:
- **Flash models:** Faster and more cost-effective for most tasks
- **Pro models:** Better for complex reasoning and analysis
- **Thinking models:** Best for tasks requiring step-by-step reasoning (requires reasoning budget)
- **Experimental models:** Latest features, may be free but less stable
- **Context Windows:** Most Gemini models support large context windows up to 1,048,576 tokens, allowing for extensive code analysis and documentation processing.
- **Rate Limits:** URL context and search grounding features may have separate rate limits. Monitor your usage to avoid hitting limits.
- **Privacy:** When using URL context, be mindful of accessing private or sensitive URLs. Ensure you have permission to analyze the content.
- **Search Quality:** Google Search grounding works best with specific, well-formed queries. Be clear about what information you need.

114
apps/docs/docs/providers/index.json Normal file
View file

@ -0,0 +1,114 @@
{
"providers": [
{
"id": "providers/anthropic",
"title": "Anthropic",
"extension": true
},
{
"id": "providers/openai-chatgpt-plus-pro",
"title": "ChatGPT Plus/Pro",
"extension": true
},
{
"id": "providers/bedrock",
"title": "AWS Bedrock",
"extension": true
},
{
"id": "providers/deepseek",
"title": "DeepSeek",
"extension": true
},
{
"id": "providers/fireworks",
"title": "Fireworks AI",
"extension": true
},
{
"id": "providers/gemini",
"title": "Google Gemini",
"extension": true
},
{
"id": "providers/lmstudio",
"title": "LM Studio",
"extension": true
},
{
"id": "providers/litellm",
"title": "LiteLLM",
"extension": true
},
{
"id": "providers/mistral",
"title": "Mistral AI",
"extension": true
},
{
"id": "providers/moonshot",
"title": "Moonshot",
"extension": true
},
{
"id": "providers/ollama",
"title": "Ollama",
"extension": true
},
{
"id": "providers/openai",
"title": "OpenAI",
"extension": true
},
{
"id": "providers/openai-compatible",
"title": "OpenAI Compatible",
"extension": true
},
{
"id": "providers/openrouter",
"title": "OpenRouter",
"extension": true
},
{
"id": "providers/qwen-code",
"title": "Qwen Code CLI",
"extension": true
},
{
"id": "providers/requesty",
"title": "Requesty",
"extension": true
},
{
"id": "providers/sambanova",
"title": "SambaNova",
"extension": true
},
{
"id": "providers/vercel-ai-gateway",
"title": "Vercel AI Gateway",
"extension": true
},
{
"id": "providers/vertex",
"title": "GCP Vertex AI",
"extension": true
},
{
"id": "providers/vscode-lm",
"title": "VS Code Language Model API",
"extension": true
},
{
"id": "providers/xai",
"title": "xAI (Grok)",
"extension": true
},
{
"id": "providers/zai",
"title": "Z AI",
"extension": true
}
]
}

35
apps/docs/docs/providers/index.mdx Normal file
View file

@ -0,0 +1,35 @@
---
title: Model Providers
description: Compare model providers available for the Roo Code VS Code extension.
keywords:
- model providers
- API providers
- Roo Code providers
- extension providers
---
import ProviderTable from '@site/src/components/ProviderTable';
# Model Providers
The Roo Code VS Code extension is a capable coding agent, but it depends on LLM providers for the inference needed to complete tasks.
Other tools are intrinsically bound by design to a specific provider, forcing you to stick with them irrespective of how the landscape changes. Roo is **model-agnostic**, allowing you to choose the model that best fits your needs, according to your budget, skill profile, codebase, and more.
Roo supports connecting to a wide range of model providers, giving you flexibility in how you access AI models.
Learn how to set up your provider in [the Roo Code VS Code extension here](/getting-started/connecting-api-provider).
## Provider Comparison
Here's every provider currently documented for the extension. Click for detailed instructions.
<ProviderTable />
## Overwhelmed by choice?
Yeah, it's a lot.
- **Want access to many models?** Try [OpenRouter](/providers/openrouter) for a single API to 100+ models
- **Want to optimize for specific models?** Use the first-party provider for each of them (Anthropic, OpenAI, etc)
- **Looking for local/offline models?** Check out [Ollama](/providers/ollama) or [LM Studio](/providers/lmstudio)

163
apps/docs/docs/providers/litellm.md Normal file
View file

@ -0,0 +1,163 @@
---
sidebar_label: LiteLLM
description: Access over 100 LLMs through LiteLLM's unified OpenAI-compatible API in Roo Code. Simplify multi-model management and reduce costs.
keywords:
- litellm
- roo code
- api provider
- unified api
- openai compatible
- multi model
- llm proxy
- local deployment
- cost management
---
# Using LiteLLM With Roo Code
LiteLLM is a versatile tool that provides a unified interface to over 100 Large Language Models (LLMs) by offering an OpenAI-compatible API. This allows you to run a local server that can proxy requests to various model providers or serve local models, all accessible through a consistent API endpoint.
**Website:** [https://litellm.ai/](https://litellm.ai/) (Main project) & [https://docs.litellm.ai/](https://docs.litellm.ai/) (Documentation)
---
## Key Benefits
- **Unified API:** Access a wide range of LLMs (from OpenAI, Anthropic, Cohere, HuggingFace, etc.) through a single, OpenAI-compatible API.
- **Local Deployment:** Run your own LiteLLM server locally, giving you more control over model access and potentially reducing latency.
- **Simplified Configuration:** Manage credentials and model configurations in one place (your LiteLLM server) and let Roo Code connect to it.
- **Cost Management:** LiteLLM offers features for tracking costs across different models and providers.
---
## Setting Up Your LiteLLM Server
To use LiteLLM with Roo Code, you first need to set up and run a LiteLLM server.
### Installation
1. Install LiteLLM with proxy support:
```bash
pip install 'litellm[proxy]'
```
### Configuration
2. Create a configuration file (`config.yaml`) to define your models and providers:
```yaml
model_list:
# Configure Anthropic models
- model_name: claude-sonnet
litellm_params:
model: anthropic/claude-sonnet-model-id
api_key: os.environ/ANTHROPIC_API_KEY
# Configure OpenAI models
- model_name: gpt-model
litellm_params:
model: openai/gpt-model-id
api_key: os.environ/OPENAI_API_KEY
# Configure Azure OpenAI
- model_name: azure-model
litellm_params:
model: azure/my-deployment-name
api_base: https://your-resource.openai.azure.com/
api_version: "2023-05-15"
api_key: os.environ/AZURE_API_KEY
```
### Starting the Server
3. Start the LiteLLM proxy server:
```bash
# Using configuration file (recommended)
litellm --config config.yaml
# Or quick start with a single model
export ANTHROPIC_API_KEY=your-anthropic-key
litellm --model anthropic/claude-model-id
```
4. The proxy will run at `http://0.0.0.0:4000` by default (accessible as `http://localhost:4000`).
- You can also configure an API key for your LiteLLM server itself for added security.
Refer to the [LiteLLM documentation](https://docs.litellm.ai/docs/) for detailed instructions on advanced server configuration and features.
---
## Configuration in Roo Code
Once your LiteLLM server is running, you have two options for configuring it in Roo Code:
### Option 1: Using the LiteLLM Provider (Recommended)
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "LiteLLM" from the "API Provider" dropdown.
3. **Enter Base URL:**
- Input the URL of your LiteLLM server.
- Defaults to `http://localhost:4000` if left blank.
4. **Enter API Key (Optional):**
- If you've configured an API key for your LiteLLM server, enter it here.
- If your LiteLLM server doesn't require an API key, Roo Code will use a default dummy key (`"dummy-key"`), which should work fine.
5. **Select Model:**
- Roo Code will attempt to fetch the list of available models from your LiteLLM server by querying the `${baseUrl}/v1/model/info` endpoint.
- The models displayed in the dropdown are sourced from this endpoint.
- Use the refresh button to update the model list if you've added new models to your LiteLLM server.
- If no model is selected, Roo Code will use a default model. Ensure you have configured at least one model on your LiteLLM server.
### Option 2: Using OpenAI Compatible Provider
Alternatively, you can configure LiteLLM using the "OpenAI Compatible" provider:
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "OpenAI Compatible" from the "API Provider" dropdown.
3. **Enter Base URL:** Input your LiteLLM proxy URL (e.g., `http://localhost:4000`).
4. **Enter API Key:** Use any string as the API key (e.g., `"sk-1234"`) since LiteLLM handles the actual provider authentication.
5. **Select Model:** Choose the model name you configured in your `config.yaml` file.
<img src="/img/litellm/litellm.png" alt="Roo Code LiteLLM Provider Settings" width="600" />
---
## How Roo Code Fetches and Interprets Model Information
When you configure the LiteLLM provider, Roo Code interacts with your LiteLLM server to get details about the available models:
- **Model Discovery:** Roo Code makes a GET request to `${baseUrl}/v1/model/info` on your LiteLLM server. If an API key is provided in Roo Code's settings, it's included in the `Authorization: Bearer ${apiKey}` header.
- **Model Properties:** For each model reported by your LiteLLM server, Roo Code extracts and interprets the following:
- `model_name`: The identifier for the model.
- `maxTokens`: Maximum output tokens. Defaults to `8192` if not specified by LiteLLM.
- `contextWindow`: Maximum context tokens. Defaults to `200000` if not specified by LiteLLM.
- `supportsImages`: Determined from `model_info.supports_vision` provided by LiteLLM.
- `supportsPromptCache`: Determined from `model_info.supports_prompt_caching` provided by LiteLLM.
- `inputPrice` / `outputPrice`: Calculated from `model_info.input_cost_per_token` and `model_info.output_cost_per_token` from LiteLLM.
- `supportsComputerUse`: This flag is set to `true` if the underlying model identifier matches one of the Anthropic models predefined in Roo Code as suitable for "computer use" (see `COMPUTER_USE_MODELS` in technical details).
Roo Code uses default values for some of these properties if they are not explicitly provided by your LiteLLM server's `/model/info` endpoint for a given model. The defaults are:
- `maxTokens`: 8192
- `contextWindow`: 200,000
- `supportsImages`: `true`
- `supportsComputerUse`: `true` (for the default model ID)
- `supportsPromptCache`: `true`
- `inputPrice`: 3.0 (µUSD per 1k tokens)
- `outputPrice`: 15.0 (µUSD per 1k tokens)
---
## Tips and Notes
- **LiteLLM Server is Key:** The primary configuration for models, API keys for downstream providers (like OpenAI, Anthropic), and other advanced features are managed on your LiteLLM server. Roo Code acts as a client to this server.
- **Configuration Options:** You can use either the dedicated "LiteLLM" provider (recommended) for automatic model discovery, or the "OpenAI Compatible" provider for simple manual configuration.
- **Model Availability:** The models available in Roo Code's "Model" dropdown depend entirely on what your LiteLLM server exposes through its `/v1/model/info` endpoint.
- **Network Accessibility:** Ensure your LiteLLM server is running and accessible from the machine where VS Code and Roo Code are running (e.g., check firewall rules if not on `localhost`).
- **Troubleshooting:** If models aren't appearing or requests fail:
- Verify your LiteLLM server is running and configured correctly.
- Check the LiteLLM server logs for errors.
- Ensure the Base URL in Roo Code settings matches your LiteLLM server's address.
- Confirm any API key required by your LiteLLM server is correctly entered in Roo Code.
- **Computer Use Models:** The `supportsComputerUse` flag in Roo Code is primarily relevant for certain Anthropic models known to perform well with tool-use and function-calling tasks. If you are routing other models through LiteLLM, this flag might not be automatically set unless the underlying model ID matches the specific Anthropic ones Roo Code recognizes.
By leveraging LiteLLM, you can significantly expand the range of models accessible to Roo Code while centralizing their management.

53
apps/docs/docs/providers/lmstudio.md Normal file
View file

@ -0,0 +1,53 @@
---
sidebar_label: LM Studio
description: Learn how to set up and use LM Studio with Roo Code for running local language models with OpenAI-compatible API support.
keywords:
- LM Studio
- local models
- Roo Code
- AI integration
- GGUF models
- CodeLlama
- Mistral
- DeepSeek
- local inference
---
# Using LM Studio With Roo Code
Roo Code supports running models locally using LM Studio. LM Studio provides a user-friendly interface for downloading, configuring, and running local language models. It also includes a built-in local inference server that emulates the OpenAI API, making it easy to integrate with Roo Code.
**Website:** [https://lmstudio.ai/](https://lmstudio.ai/)
---
## Setting Up LM Studio
1. **Download and Install LM Studio:** Download LM Studio from the [LM Studio website](https://lmstudio.ai/).
2. **Download a Model:** Use the LM Studio interface to search for and download a model in GGUF format. Browse all available models in the LM Studio search interface or at [Hugging Face](https://huggingface.co/models?library=gguf).
3. **Start the Local Server:**
- Open LM Studio.
- Click the **"Local Server"** tab (the icon looks like `<->`).
- Select the model you downloaded.
- Click **"Start Server"**.
---
## Configuration in Roo Code
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "LM Studio" from the "API Provider" dropdown.
3. **Enter Model ID:** Enter the _file name_ of the model you loaded in LM Studio (e.g., `codellama-7b.Q4_0.gguf`). You can find this in the LM Studio "Local Server" tab.
4. **(Optional) Base URL:** By default, Roo Code will connect to LM Studio at `http://localhost:1234`. If you've configured LM Studio to use a different address or port, enter the full URL here.
---
## Tips and Notes
- **Resource Requirements:** Running large language models locally can be resource-intensive. Make sure your computer meets the minimum requirements for the model you choose.
- **Model Selection:** LM Studio provides a wide range of models. Experiment to find the one that best suits your needs.
- **Local Server:** The LM Studio local server must be running for Roo Code to connect to it.
- **LM Studio Documentation:** Refer to the [LM Studio documentation](https://lmstudio.ai/docs) for more information.
- **Troubleshooting:** If you see a "Please check the LM Studio developer logs to debug what went wrong" error, you may need to adjust the context length settings in LM Studio.
- **Token Tracking:** Roo Code tracks token usage for models run via LM Studio, helping you monitor consumption.
- **Reasoning Support:** For models that support it, Roo Code can parse "think" tags or similar reasoning indicators in LM Studio responses, offering more insight into the model's process.

27
apps/docs/docs/providers/minimax.md Normal file
View file

@ -0,0 +1,27 @@
---
sidebar_label: MiniMax
description: Configure MiniMax’s OpenAI‑compatible API in Roo Code. Choose the right region base URL and start chatting.
keywords:
- minimax
- mini max
- openai compatible
- china region
- api provider
---
# Using MiniMax With Roo Code
MiniMax is an OpenAI‑compatible provider. Pick the correct region endpoint, add your API key, and you’re ready to chat.
---
## Configuration in Roo Code
1. Open Roo Code Settings (gear icon).
2. Select Provider: “MiniMax”.
3. Choose Base URL (region):
- International: https://api.minimax.io/v1
- China (Mainland): https://api.minimaxi.com/v1
4. Enter your API key in “MiniMax API Key”.
5. Select a model from the dropdown.
6. Optional: adjust Temperature and Max Output Tokens in model settings.

60
apps/docs/docs/providers/mistral.md Normal file
View file

@ -0,0 +1,60 @@
---
sidebar_label: Mistral AI
description: Configure Roo Code to use Mistral AI models including Codestral for code generation, with support for function calling and vision.
keywords:
- Mistral AI
- Codestral
- Roo Code
- AI models
- code generation
- Pixtral
- Ministral
- function calling
- La Plateforme
---
# Using Mistral AI With Roo Code
Roo Code supports accessing models through the Mistral AI API, including both standard Mistral models and the code-specialized Codestral model.
**Website:** [https://mistral.ai/](https://mistral.ai/)
---
## Getting an API Key
1. **Sign Up/Sign In:** Go to the [Mistral Platform](https://console.mistral.ai/). Create an account or sign in. You may need to go through a verification process.
2. **Create an API Key:**
- [La Plateforme API Key](https://console.mistral.ai/api-keys/) and/or
- [Codestral API Key](https://console.mistral.ai/codestral)
---
## Available Models
Roo Code supports all models available through Mistral AI's API.
For the complete, up-to-date model list and capabilities, see [Mistral's model documentation](https://docs.mistral.ai/getting-started/models/models_overview/).
---
## Configuration in Roo Code
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "Mistral" from the "API Provider" dropdown.
3. **Enter API Key:** Paste your Mistral API key into the "Mistral API Key" field if you're using a `mistral` model. If you intend to use `codestral-latest`, see the "Codestral" section below.
4. **Select Model:** Choose your desired model from the "Model" dropdown.
---
## Using Codestral
[Codestral](https://docs.mistral.ai/capabilities/code_generation/) is a model specifically designed for code generation and interaction.
Only for Codestral you could use different endpoints (Default: codestral.mistral.ai).
For the La Platforme API Key change the **Codestral Base Url** to: https://api.mistral.ai
To use Codestral:
1. **Select "Mistral" as the API Provider.**
2. **Select a Codestral Model**
3. **Enter your Codestral (codestral.mistral.ai) or La Plateforme (api.mistral.ai) API Key.**

49
apps/docs/docs/providers/moonshot.md Normal file
View file

@ -0,0 +1,49 @@
---
sidebar_label: Moonshot
description: Configure Moonshot AI's language models in Roo Code. Access powerful AI models through Moonshot's OpenAI-compatible API.
keywords:
- moonshot
- moonshot ai
- roo code
- api provider
- openai compatible
---
# Using Moonshot With Roo Code
Roo Code supports accessing models through the Moonshot AI API, which provides an OpenAI-compatible interface.
**Website:** [https://platform.moonshot.cn/](https://platform.moonshot.cn/)
---
## Getting an API Key
1. **Sign Up/Sign In:** Go to the [Moonshot Platform](https://platform.moonshot.cn/). Create an account or sign in.
2. **Navigate to API Keys:** Find your API keys in the API keys section of the platform.
3. **Create a Key:** Create a new API key. Give your key a descriptive name (e.g., "Roo Code").
4. **Copy the Key:** **Important:** Copy the API key _immediately_. You will not be able to see it again. Store it securely.
---
## Available Models
Roo Code supports all models available through the Moonshot API.
For the complete, up-to-date model list, see [Moonshot's API documentation](https://platform.moonshot.cn/docs).
---
## Configuration in Roo Code
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "Moonshot" from the "API Provider" dropdown.
3. **Enter API Key:** Paste your Moonshot API key into the "Moonshot API Key" field.
4. **Select Model:** Choose your desired model from the "Model" dropdown.
---
## Tips and Notes
- **OpenAI-Compatible:** Moonshot uses an OpenAI-compatible API format, making it easy to integrate with Roo Code.
- **Pricing:** Refer to the Moonshot platform for details on model costs and pricing.

188
apps/docs/docs/providers/ollama.md Normal file
View file

@ -0,0 +1,188 @@
---
sidebar_label: Ollama
description: Set up Ollama with Roo Code to run open source language models locally for privacy, offline access, and cost-effective AI coding.
keywords:
- Ollama
- local models
- Roo Code
- open source AI
- CodeLlama
- Qwen
- offline AI
- privacy
- context window configuration
---
import KangarooIcon from '@site/src/components/KangarooIcon';
# Using Ollama With Roo Code
Roo Code supports running models locally using Ollama. This provides privacy, offline access, and potentially lower costs, but requires more setup and a powerful computer.
**Website:** [https://ollama.com/](https://ollama.com/)
---
## Setting up Ollama
1. **Download and Install Ollama:** Download the Ollama installer for your operating system from the [Ollama website](https://ollama.com/). Follow the installation instructions. Make sure Ollama is running
```bash
ollama serve
```
2. **Download a Model:** Browse [Ollama's model library](https://ollama.com/library) for all available models. To download a model, run:
```bash
ollama pull <model_name>
```
For example:
```bash
ollama pull qwen2.5-coder:32b
```
3. **Configure the Model:** Configure your model's context window in Ollama and save a copy.
:::info Default Context Behavior
**Roo Code automatically defers to the Modelfile's `num_ctx` setting by default.** When you use a model with Ollama, Roo Code reads the model's configured context window and uses it automatically. You don't need to configure context size in Roo Code settings - it respects what's defined in your Ollama model.
:::
**Option A: Interactive Configuration**
Load the model (we will use `qwen2.5-coder:32b` as an example):
```bash
ollama run qwen2.5-coder:32b
```
Change context size parameter:
```bash
/set parameter num_ctx 32768
```
Save the model with a new name:
```bash
/save your_model_name
```
**Option B: Using a Modelfile (Recommended)**
Create a `Modelfile` with your desired configuration:
```dockerfile
# Example Modelfile for reduced context
FROM qwen2.5-coder:32b
# Set context window to 32K tokens (reduced from default)
PARAMETER num_ctx 32768
# Optional: Adjust temperature for more consistent output
PARAMETER temperature 0.7
# Optional: Set repeat penalty
PARAMETER repeat_penalty 1.1
```
Then create your custom model:
```bash
ollama create qwen-32k -f Modelfile
```
:::tip Override Context Window
If you need to override the model's default context window:
- **Permanently:** Save a new model version with your desired `num_ctx` using either method above
- **Roo Code behavior:** Roo automatically uses whatever `num_ctx` is configured in your Ollama model
- **Memory considerations:** Reducing `num_ctx` helps prevent out-of-memory errors on limited hardware
:::
4. **Configure Roo Code:**
- Open the Roo Code sidebar (<KangarooIcon /> icon).
- Click the settings gear icon (<Codicon name="gear" />).
- Select "ollama" as the API Provider.
- Enter the model tag or saved name from the previous step (e.g., `your_model_name`).
- (Optional) Configure the base URL if you're running Ollama on a different machine. The default is `http://localhost:11434`.
- (Optional) Enter an API Key if your Ollama server requires authentication.
- (Advanced) Roo uses Ollama's native API by default for the "ollama" provider. An OpenAI-compatible `/v1` handler also exists but isn't required for typical setups.
---
## Tips and Notes
- **Resource Requirements:** Running large language models locally can be resource-intensive. Make sure your computer meets the minimum requirements for the model you choose.
- **Model Selection:** Experiment with different models to find the one that best suits your needs.
- **Offline Use:** Once you've downloaded a model, you can use Roo Code offline with that model.
- **Token Tracking:** Roo Code tracks token usage for models run via Ollama, helping you monitor consumption.
- **Ollama Documentation:** Refer to the [Ollama documentation](https://ollama.com/docs) for more information on installing, configuring, and using Ollama.
---
## Troubleshooting
### Out of Memory (OOM) on First Request
**Symptoms**
- First request from Roo fails with an out-of-memory error
- GPU/CPU memory usage spikes when the model first loads
- Works after you manually start the model in Ollama
**Cause**
If no model instance is running, Ollama spins one up on demand. During that cold start it may allocate a larger context window than expected. The larger context window increases memory usage and can exceed available VRAM or RAM. This is an Ollama startup behavior, not a Roo Code bug.
**Fixes**
1. **Preload the model**
```bash
ollama run &lt;model-name&gt;
```
Keep it running, then issue the request from Roo.
2. **Pin the context window (`num_ctx`)**
- Option A — interactive session, then save:
```bash
# inside `ollama run &lt;base-model&gt;`
/set parameter num_ctx 32768
/save &lt;your_model_name&gt;
```
- Option B — Modelfile (recommended for reproducibility):
```dockerfile
FROM &lt;base-model&gt;
PARAMETER num_ctx 32768
# Adjust based on your available memory:
# 16384 for ~8GB VRAM
# 32768 for ~16GB VRAM
# 65536 for ~24GB+ VRAM
```
Then create the model:
```bash
ollama create &lt;your_model_name&gt; -f Modelfile
```
3. **Ensure the model's context window is pinned**
Save your Ollama model with an appropriate `num_ctx` (via `/set` + `/save`, or preferably a Modelfile). **Roo Code automatically detects and uses the model's configured `num_ctx`** - there is no manual context size setting in Roo Code for the Ollama provider.
4. **Use smaller variants**
If GPU memory is limited, use a smaller quant (e.g., q4 instead of q5) or a smaller parameter size (e.g., 7B/13B instead of 32B).
5. **Restart after an OOM**
```bash
ollama ps
ollama stop &lt;model-name&gt;
```
**Quick checklist**
- Model is running before Roo request
- `num_ctx` pinned (Modelfile or `/set` + `/save`)
- Model saved with appropriate `num_ctx` (Roo uses this automatically)
- Model fits available VRAM/RAM
- No leftover Ollama processes

52
apps/docs/docs/providers/openai-chatgpt-plus-pro.md Normal file
View file

@ -0,0 +1,52 @@
---
sidebar_label: ChatGPT Plus/Pro
title: ChatGPT Plus/Pro
description: Use OpenAI models in Roo Code with your ChatGPT Plus/Pro subscription (OAuth sign-in, no API key).
keywords:
- OpenAI Codex
- ChatGPT Plus
- ChatGPT Pro
- Roo Code
- OAuth
- no api key
- subscription
---
<div style={{ position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden' }}>
<iframe
src="https://www.youtube.com/embed/c1IXRMl5i0g?rel=0&modestbranding=1"
title="OpenAI – ChatGPT Plus/Pro provider setup"
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: '100%',
}}
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
></iframe>
</div>
---
## Quickstart: Connect your subscription to Roo Code
1. Open Roo Code settings (click the gear icon <Codicon name="gear" /> in the Roo Code panel).
2. In **API Provider**, select **OpenAI – ChatGPT Plus/Pro**.
3. Click **Sign in to OpenAI Codex**.
4. Finish the sign-in flow in your browser.
5. Back in Roo Code settings, pick a model from the dropdown.
6. Save.
## Tips and Notes
- **Subscription Required:** You need an active ChatGPT Plus or Pro subscription. This provider won't work with free ChatGPT accounts. See [OpenAI's ChatGPT plans](https://openai.com/chatgpt/pricing) for more info.
- **No API Costs:** Usage through this provider counts against your ChatGPT subscription, not separately billed API usage.
- **Sign Out:** To disconnect, use the "Sign Out" button in the provider settings.
## What you can't do (and why)
- **You can't use arbitrary OpenAI API models.** This provider only exposes the models listed in Roo's Codex model catalog.
- **You can't export/migrate your sign-in state with settings export.** OAuth tokens are stored in VS Code SecretStorage, which isn't included in Roo's settings export.

116
apps/docs/docs/providers/openai-compatible.md Normal file
View file

@ -0,0 +1,116 @@
---
sidebar_label: OpenAI Compatible
description: Use Roo Code with any OpenAI-compatible API provider including Perplexity, Together AI, Anyscale, and custom endpoints.
keywords:
- OpenAI compatible
- Roo Code
- API integration
- custom endpoints
- Together AI
- Perplexity
- Anyscale
- model configuration
---
# Using OpenAI Compatible Providers With Roo Code
Roo Code supports a wide range of AI model providers that offer APIs compatible with the OpenAI API standard. This means you can use models from providers _other than_ OpenAI, while still using a familiar API interface. This includes providers like:
- **Local models** running through tools like Ollama and LM Studio (covered in separate sections).
- **Cloud providers** like Perplexity, Together AI, Anyscale, and others.
- **Any other provider** offering an OpenAI-compatible API endpoint.
This document focuses on setting up providers _other than_ the official OpenAI API (which has its own [dedicated configuration page](/providers/openai)).
---
## General Configuration
The key to using an OpenAI-compatible provider is to configure two main settings:
1. **Base URL:** This is the API endpoint for the provider. It will _not_ be `https://api.openai.com/v1` (that's for the official OpenAI API).
2. **API Key:** This is the secret key you obtain from the provider.
3. **Model ID:** This is the model name of the specific model.
You'll find these settings in the Roo Code settings panel (click the <Codicon name="gear" /> icon):
- **API Provider:** Select "OpenAI Compatible".
- **Base URL:** Enter the base URL provided by your chosen provider. **This is crucial.**
- **API Key:** Enter your API key.
- **Model:** Choose a model.
- **Model Configuration:** This lets you customize advanced configuration for the model
- Max Output Tokens
- Context Window
- Image Support
- Computer Use
- Input Price
- Output Price
---
## Native Tool Calling
Roo Code uses **native tool calling** exclusively. This is the only supported tool protocol -- there is no XML-based fallback.
At a high level:
- **Tool definitions** are sent to the model using OpenAI's native tools schema.
- **Tool calls** stream back as dedicated tool events, including the tool name, arguments, and metadata.
- **Tool arguments** are streamed incrementally, which reduces latency between the model deciding to use a tool and Roo Code executing it.
### Requirements
For native tool calling to work, the model you select **must** support OpenAI-compatible tool calling. If a model does not support native tool calling, it cannot be used with Roo Code.
### Example: simple native tool flow
Here's a simplified example of how a file-reading tool might be exposed when using an OpenAI-native endpoint:
```json
{
"tools": [
{
"type": "function",
"function": {
"name": "read_file",
"description": "Read a file from the workspace with line numbers.",
"parameters": {
"type": "object",
"properties": {
"path": { "type": "string", "description": "Relative file path" },
"start_line": { "type": "integer", "nullable": true },
"end_line": { "type": "integer", "nullable": true }
},
"required": ["path"]
}
}
}
]
}
```
When the model decides to use `read_file`, Roo Code surfaces **streamed tool events** in the task timeline:
- A native _tool call_ event with the tool name and arguments as they're being generated
- The corresponding _tool result_ event showing the file contents and any truncation or line-range information
This gives you lower-latency feedback on which tools are being used and with what arguments.
### Limitations
- **Model support:** Not all models support native tool calling. If a model does not support tools, it cannot be used with Roo Code. Check your provider's documentation to confirm tool-calling support for the model you want to use.
- **Provider quirks:** Some OpenAI-compatible providers only partially implement the native tools API. If you encounter tool-calling errors, verify that your provider fully supports OpenAI-compatible function calling.
For a deeper overview of how tools work in Roo Code in general, see the [Tool Use Overview](/advanced-usage/available-tools/tool-use-overview).
---
## Troubleshooting
- **"Invalid API Key":** Double-check that you've entered the API key correctly.
- **"Model Not Found":** Make sure you're using a valid model ID for your chosen provider.
- **Connection Errors:** Verify the Base URL is correct and that your provider's API is accessible.
- **Tool-calling errors:** Roo Code requires native tool calling. If your model does not support it, you need to switch to a model that does. Check your provider's documentation for tool-calling compatibility.
- **Unexpected Results:** If you're getting unexpected results, try a different model.
By using an OpenAI-compatible provider, you can leverage the flexibility of Roo Code with a wider range of AI models. Remember to always consult your provider's documentation for the most accurate and up-to-date information.

104
apps/docs/docs/providers/openai.md Normal file
View file

@ -0,0 +1,104 @@
---
sidebar_label: OpenAI
description: Connect Roo Code to OpenAI's official API for access to GPT and reasoning models with advanced capabilities and verbosity control.
keywords:
- OpenAI
- GPT models
- reasoning models
- Roo Code
- AI integration
- API key
- official OpenAI API
- verbosity
- reasoning effort
---
# Using OpenAI With Roo Code
Roo Code supports accessing models directly through the official OpenAI API, including the latest GPT-5 family with advanced features like reasoning effort control and verbosity settings.
:::info Want to use a ChatGPT Plus/Pro subscription instead?
Use the **OpenAI – ChatGPT Plus/Pro** provider to sign in via OAuth (no API key): [OpenAI – ChatGPT Plus/Pro](/providers/openai-chatgpt-plus-pro).
:::
**Website:** [https://openai.com/](https://openai.com/)
---
## Getting an API Key
1. **Sign Up/Sign In:** Go to the [OpenAI Platform](https://platform.openai.com/). Create an account or sign in.
2. **Navigate to API Keys:** Go to the [API keys](https://platform.openai.com/api-keys) page.
3. **Create a Key:** Click "Create new secret key". Give your key a descriptive name (e.g., "Roo Code").
4. **Copy the Key:** **Important:** Copy the API key _immediately_. You will not be able to see it again. Store it securely.
---
## Available Models
Roo Code supports all models available through OpenAI's API.
For the complete, up-to-date model list and capabilities, see [OpenAI's models documentation](https://platform.openai.com/docs/models).
---
## Configuration in Roo Code
### Setup
1. **Open Roo Code Settings:** Click the gear icon (<Codicon name="gear" />) in the Roo Code panel.
2. **Select Provider:** Choose "OpenAI" from the "API Provider" dropdown.
3. **Enter API Key:** Paste your OpenAI API key into the "OpenAI API Key" field.
4. **Select Model:** Choose your desired model from the "Model" dropdown.
5. **(Optional) Base URL:** If you need to use a custom base URL, enter the URL. Most people won't need to adjust this.
---
## Advanced Features
### Reasoning Effort Control
For models that support reasoning (GPT-5, o1, o3, o4 families), you can control how deeply the model thinks:
**GPT-5 Models:**
- `minimal` - Fastest responses with basic reasoning
- `low` - Quick responses with light reasoning
- `medium` (default) - Balanced reasoning and response time
- `high` - Deep reasoning for complex problems
**o1/o3/o4 Models:**
- `low` - Minimal thinking time
- `medium` - Balanced approach
- `high` - Maximum thinking for complex problems
Some models have preset reasoning levels that cannot be changed.
### Verbosity Control
Available for GPT-5 models and select others, verbosity controls the detail level of responses:
- `low` - Concise, direct responses
- `medium` (default) - Balanced detail
- `high` - Comprehensive, detailed responses
### Temperature Settings
Temperature controls output randomness (0.0 to 2.0):
- **GPT-5 models:** Default 1.0 for balanced creativity
- **Other models:** Default 0.0 for deterministic output
- **Note:** Not available for o1/o3 reasoning models
### Conversation Continuity (GPT-5)
GPT-5 models maintain conversation context efficiently through response IDs, reducing token usage while preserving context. This happens automatically - no configuration needed.
---
## Tips and Notes
- **Pricing:** Refer to the [OpenAI Pricing](https://openai.com/pricing) page for current model costs and discounts, including prompt caching.
- **Azure OpenAI Service:** If you'd like to use the Azure OpenAI service, please see our section on [OpenAI-compatible](/providers/openai-compatible) providers.
- **Context Optimization:** For GPT-5-Codex, leverage prompt caching by maintaining consistent context across requests to reduce costs significantly.

Some files were not shown because too many files have changed in this diff Show more