# Roo Code: Comprehensive Knowledge Base

This document consolidates all information, features, concepts, and insights about Roo Code, derived from its official documentation.

## 1. Overview

*   **What is Roo Code?**
    *   Roo Code (formerly Roo Cline) is an AI-powered autonomous coding agent that lives in your editor.
*   **Core Purpose & Value Proposition:**
    *   Helps you code faster and smarter, whether you're starting a new project, maintaining existing code, or learning new technologies.
*   **Target Audience:**
    *   Developers, programmers, software engineers. (Inferred)

## 2. Core Concepts & Architecture

*   **How Roo Code Works:**
    *   Interaction with LLMs.
    *   **User Interaction Flow (from `docs/getting-started/your-first-task.md`):**
        1.  User opens Roo Code panel in VS Code.
        2.  User types task in natural language into chat box.
        3.  User sends task.
        4.  Roo Code analyzes request and proposes actions.
        5.  User reviews and approves/rejects each action (unless auto-approval is on).
        6.  Roo Code executes approved action and waits for feedback.
        7.  Process iterates until task completion.
    *   File system operations (read/write) - *Proposed Action Type*.
    *   Command execution - *Proposed Action Type*.
    *   Web browsing capabilities - *Proposed Action Type*.
    *   Model Context Protocol (MCP) - *Key Feature, enables external tools*.
    *   Chat interface interaction - *Primary method of user input and Roo Code output/proposals*.
*   **Key Terminology:**
    *   Modes (Code, Architect, Ask, Debug, Orchestrator, Custom)
    *   Smart Tools
    *   Context Mentions
    *   MCP (Model Context Protocol)
    *   Custom Instructions
    *   Local Models
    *   Auto-Approval Settings
    *   `.roorules` (Mentioned in FAQ, to be confirmed if in index.md scope)
    *   Checkpoints (Mentioned in FAQ, to be confirmed if in index.md scope)


## 3. Getting Started

*   **Quick Start Steps (from `docs/index.md`):**
    1.  [Install Roo Code](/getting-started/installing)
    2.  [Connect Your AI Provider](/getting-started/connecting-api-provider)
    3.  [Try Your First Task](/getting-started/your-first-task)
*   **Installation (from `docs/getting-started/installing.mdx`):**
    *   Roo Code is a VS Code extension published by RooVeterinaryInc.
    *   **VS Code Version Requirement**: 1.84.0 or later.
    *   **Installation Methods**:
        *   **VS Code Marketplace (Recommended)**:
            1.  Open VS Code, go to Extensions view (`Ctrl+Shift+X` or `Cmd+Shift+X`).
            2.  Search "Roo Code".
            3.  Select "Roo Code" by RooVeterinaryInc and click Install.
            4.  Reload VS Code if prompted.
            *   Suitable for standard VS Code and Cursor users.
        *   **Open VSX Registry**:
            1.  For VS Code-compatible editors (e.g., VSCodium, Windsurf).
            2.  Open editor, go to Extensions view.
            3.  Search "Roo Code".
            4.  Select "Roo Code" by RooVeterinaryInc and click Install.
            5.  Reload if prompted.
        *   **Manual Installation from VSIX**:
            1.  Download the `.vsix` file from the [Roo Code GitHub Releases page](https://github.com/RooVetGit/Roo-Code/releases) (latest release).
            2.  In VS Code: Extensions view -> "..." menu -> "Install from VSIX..." -> Select downloaded file.
        *   **Development Builds (For contributors)**:
            1.  Run `npm run build` in the project directory.
            2.  Find generated VSIX in `bin/` directory.
            3.  Install via "Install from VSIX..." in VS Code.
    *   **Post-Installation**: Find the Roo Code icon (<KangarooIcon />) in the Activity Bar to open the Roo Code panel.
    *   **Embedded Tutorial Video**: [Installing Roo Code](https://www.youtube.com/embed/Mcq3r1EPZ-4)
*   **Connecting to AI Providers (from `docs/getting-started/connecting-api-provider.md`):**
    *   **Requirement**: Roo Code requires an API key from an AI model provider to function.
    *   **Recommended Model**: **Claude 3.7 Sonnet** is strongly recommended. Roo Code is optimized for this model.
        *   Accessible via OpenRouter (model: `anthropic/claude-3.7-sonnet`)
        *   Accessible via Anthropic direct (model: `claude-3-7-sonnet-20250219`)
    *   **General Process**: Obtain an API key from a provider, then configure it in Roo Code (VS Code sidebar).
    *   **API Key Acquisition Options:**
        *   **LLM Routers (Recommended for quick start, multiple models, single key):**
            *   **OpenRouter:**
                1.  Go to [openrouter.ai](https://openrouter.ai/)
                2.  Sign in (Google/GitHub).
                3.  Navigate to [API keys page](https://openrouter.ai/keys) and create a new key.
                4.  Copy the API key.
            *   **Requesty:**
                1.  Go to [requesty.ai](https://requesty.ai/)
                2.  Sign in (Google/email).
                3.  Navigate to [API management page](https://app.requesty.ai/api-keys) and create a new key.
                4.  Copy API key immediately (shown only once).
        *   **Direct Providers (Full access to specific models):**
            *   **Anthropic:**
                1.  Go to [console.anthropic.com](https://console.anthropic.com/)
                2.  Sign up/log in.
                3.  Navigate to [API keys section](https://console.anthropic.com/settings/keys) and create a new key.
                4.  Copy API key immediately (shown only once).
                5.  Note: May have rate limits.
            *   **OpenAI:**
                1.  Go to [platform.openai.com](https://platform.openai.com/)
                2.  Sign up/log in.
                3.  Navigate to the [API keys section](https://platform.openai.com/api-keys) and create a new key.
                4.  Copy API key immediately (shown only once).
    *   **Configuring Roo Code in VS Code:**
        1.  Open Roo Code sidebar (KangarooIcon in Activity Bar).
        2.  In welcome screen, select API provider from dropdown.
        3.  Paste API key.
        4.  Select your model (e.g., `anthropic/claude-3.7-sonnet` for OpenRouter, `claude-3-7-sonnet-20250219` for Anthropic).
        5.  Click "Let's go!".
    *   **Model Selection Advice**:
        *   Claude 3.7 Sonnet "just works".
        *   Alternative models are an advanced feature; choose models designed for structured reasoning and tool use if experimenting.
    *   (Further details from `docs/providers/` to be added later)
*   **Your First Task (from `docs/getting-started/your-first-task.md`):**
    *   **Prerequisite**: AI provider and model configured.
    *   **Step 1: Open the Roo Code Panel**: Click Roo Code icon (<KangarooIcon />) in VS Code Activity Bar.
    *   **Step 2: Type Your Task**: Use clear, concise, plain English in the chat box. No special commands needed.
        *   Examples: "Create a file named `hello.txt` containing 'Hello, world!'."
    *   **Step 3: Send Your Task**: Press Enter or click Send icon (<Codicon name="send" />).
    *   **Step 4: Review and Approve Actions**:
        *   Roo Code proposes specific actions (reading files, writing files with diff, executing commands, browser actions, asking questions).
        *   Each action requires explicit user approval (Approve/Reject buttons) unless auto-approval is enabled.
    *   **Step 5: Iterate**: Roo Code works iteratively, waiting for feedback/approval after each action before proposing the next step, until the task is complete.
    *   **Core Learnings**: Natural language interaction, approval-based workflow (user in control), iterative problem-solving.

## 4. Basic Usage

*   **The Chat Interface (from `docs/basic-usage/the-chat-interface.md` and `docs/getting-started/your-first-task.md`):**
    *   **Access**: The primary way to interact with Roo Code, located in the `Roo Code Panel`. Open by clicking the Roo Code icon (<KangarooIcon />) in the VS Code Activity Bar.
    *   **Main Components**:
        1.  **Chat History**: Displays the conversation history (your requests, Roo Code's responses, actions taken).
        2.  **Input Field**: Where you type tasks and questions in plain English.
        3.  **Action Buttons**: Appear above the input field, allowing approval (`Save`) or rejection (`Reject`) of Roo Code's proposed actions. Context-dependent.
        4.  **Send Button**: Icon looks like a small plane (<Codicon name="send" />), located to the far right of the input field. Sends messages to Roo.
        5.  **Plus Button**: Located at the top in the header; resets the current Roo Code session.
        6.  **Settings Button**: Gear icon (<Codicon name="gear" />) in the header; opens Roo Code settings for customization.
        7.  **Mode Selector**: Dropdown menu located to the left of the chat input field; used for selecting Roo Code modes.
    *   **Interacting with Messages**:
        *   **Clickable Links**: File paths in chat open in the editor; URLs open in the default browser.
        *   **Copying Text**: Select text and use standard copy (Ctrl/Cmd + C). Code blocks often have a dedicated "Copy" button.
        *   **Expanding/Collapsing Messages**: Click on a message to toggle its expanded/collapsed state.
    *   **Status Indicators**:
        *   **Loading Spinner**: Indicates Roo Code is processing a request.
        *   **Error Messages**: Displayed in red if an error occurs.
        *   **Success Messages**: Displayed in green to indicate successful completion of actions.
*   **Typing Your Requests (from `docs/basic-usage/typing-your-requests.md`):**
    *   **Communication Style**: Interact with Roo Code using natural, plain English. No special commands or syntax are necessary.
    *   **Effective Request Strategies**:
        *   **Be Specific**: Clearly state the desired action and target. Instead of "Fix the code," use "Fix the bug in the `calculateTotal` function that causes incorrect results when input is negative."
        *   **Provide Context**: Utilize `@` [Context Mentions](/basic-usage/context-mentions) (see Section 4.5) to refer to specific files, folders, problems, or Git commits. This gives Roo Code the necessary information to understand your request accurately.
        *   **Break Down Tasks**: For complex tasks, submit them as a series of smaller, manageable steps rather than one large request.
        *   **Include Examples**: If you require a specific coding style, output format, or pattern, provide examples in your prompt.
    *   **Example Requests**: The source documentation provides several examples, such as creating a file with a function, changing a button color in a specific file using `@mention`, finding and replacing text, running terminal commands, explaining functions, and addressing `@problems`.
    *   **Common Pitfalls to Avoid**:
        *   **Vague Requests**: Instead, be precise about what needs to be done.
        *   **Assuming Context**: Explicitly reference files, functions, and other relevant information.
        *   **Excessive Technical Jargon**: Use clear, straightforward language.
        *   **Multiple Unrelated Tasks**: Submit one focused request at a time.
        *   **Proceeding Without Confirmation**: Always check the code and results Roo Code produces to ensure completeness and correctness before moving on.
*   **Using Modes (from `docs/basic-usage/using-modes.md` and `docs/index.md`):**
    *   **Definition**: Modes in Roo Code are specialized personas that tailor the assistant's behavior, capabilities, expertise, and access levels to specific tasks.
    *   **Sticky Models**: A key feature where each mode remembers the last AI model used with it. When switching modes, Roo automatically selects that model, allowing users to assign different models to different modes (e.g., a powerful model for `Architect` mode, a faster one for `Code` mode).
    *   **Benefits of Using Different Modes**:
        *   **Task Specialization**: Get assistance optimized for the current task.
        *   **Safety Controls**: Prevent unintended file modifications (e.g., `Ask` mode is read-only for code).
        *   **Focused Interactions**: Receive responses tailored to the current activity.
        *   **Workflow Optimization**: Seamlessly transition between planning, implementing, debugging, etc.
    *   **Switching Between Modes**:
        1.  **Dropdown Menu**: Click the mode selector to the left of the chat input.
        2.  **Slash Command**: Type `/` followed by the mode name (e.g., `/architect`, `/ask`, `/debug`, `/code`, `/orchestrator`).
        3.  **Toggle Command/Keyboard Shortcut**: Use `⌘ + .` (macOS) or `Ctrl + .` (Windows/Linux) to cycle through modes.
        4.  **Accepting Suggestions**: Roo Code may suggest a mode switch when appropriate.
    *   **Built-in Modes**:
        *   **`💻 Code` Mode (Default)**:
            *   **Persona**: Skilled software engineer.
            *   **Tool Access**: Full access to all tool groups (`read`, `edit`, `browser`, `command`, `mcp`).
            *   **Ideal For**: Writing code, implementing features, debugging, general development.
        *   **`❓ Ask` Mode**:
            *   **Persona**: Knowledgeable technical assistant for thorough answers, often uses diagrams.
            *   **Tool Access**: Limited (`read`, `browser`, `mcp` only; cannot edit files or run commands).
            *   **Ideal For**: Code explanation, concept exploration, technical learning.
        *   **`🏗️ Architect` Mode**:
            *   **Persona**: Experienced technical leader and planner.
            *   **Tool Access**: `read`, `browser`, `mcp`, and restricted `edit` (markdown files only).
            *   **Ideal For**: System design, high-level planning, architecture discussions.
        *   **`🪲 Debug` Mode**:
            *   **Persona**: Expert problem solver specializing in systematic troubleshooting.
            *   **Tool Access**: Full access to all tool groups.
            *   **Ideal For**: Tracking down bugs, diagnosing errors, resolving complex issues. Follows a methodical approach.
        *   **`🪃 Orchestrator` Mode (Boomerang Mode)**:
            *   **Persona**: Strategic workflow orchestrator.
            *   **Tool Access**: `read`, `browser`, `command`, `mcp`, and restricted `edit` (mode configuration files like `.roomodes`, `custom_modes.json` only).
            *   **Ideal For**: Managing multi-step projects, coordinating work by delegating subtasks to other modes using the `new_task` tool. (See Section 5.6 for Boomerang Tasks).
    *   **Customizing Modes**: Users can tailor Roo Code's behavior further by customizing existing modes or creating new specialized assistants. This includes defining tool access, file permissions, and specific behavioral instructions. (See Section 5.2 for Custom Modes).
*   **How Tools Work (from `docs/basic-usage/how-tools-work.md` and `docs/index.md`):**
    *   **Core Idea**: Roo Code uses specialized tools to interact with your code and environment, automating common development tasks.
    *   **Tool Workflow**:
        1.  User describes the desired outcome in natural language.
        2.  Roo Code selects the most appropriate tool for the job.
        3.  Roo Code presents the chosen tool and its parameters (often in an XML-like format) for user review.
        4.  The user explicitly approves (clicks "Save") or rejects the proposed tool use.
        5.  If approved, Roo Code executes the tool and displays the results.
        6.  This iterative process continues until the overall task is completed.
    *   **Tool Categories**:
        *   **Read**: Access file content and code structure (e.g., `read_file`, `search_files`, `list_files`, `list_code_definition_names`).
        *   **Edit**: Create or modify files and code (e.g., `write_to_file`, `apply_diff`).
        *   **Execute**: Run commands and perform system operations (e.g., `execute_command`).
        *   **Browser**: Interact with web content (e.g., `browser_action`).
        *   **Workflow**: Manage task flow and context (e.g., `ask_followup_question`, `attempt_completion`, `switch_mode`, `new_task`).
    *   **Tool Safety and Approval**:
        *   Every tool use requires explicit user approval via "Save" or "Reject" buttons in the `Tool Approval Interface (Roo Code UI)`.
        *   An optional "Auto-approve" setting is available for trusted operations, which bypasses the manual confirmation step. (See Section 5.4 for Auto-Approving Actions).
        *   This mechanism ensures users maintain control over changes to their codebase and system.
    *   **Core Tools Reference**: The documentation includes a table summarizing key tools. For detailed information on each tool, including parameters and advanced usage, refer to the [Tool Use Overview](/advanced-usage/available-tools/tool-use-overview) (Section 6.4).
    *   **MCP Tools**: Beyond built-in tools, Roo Code can use external tools via the [Model Context Protocol (MCP)](/features/mcp/overview). (See Section 5.5)
*   **Context Mentions (from `docs/basic-usage/context-mentions.md`):**
    *   **Purpose**: A powerful way to provide Roo Code with specific information about your project, enabling more accurate and efficient task performance.
    *   **Syntax**: Starts with the `@` symbol. Typing `@` in the chat input triggers a suggestions dropdown.
    *   **Types of Mentions**:
        *   **File (`@/path/to/file.ts`)**: Includes the complete contents of the specified file (text, PDF, DOCX) with line numbers. Path must start with `/` from workspace root. Large files may be truncated.
        *   **Folder (`@/path/to/folder`)**: Includes the complete contents of all non-binary text files directly within the specified folder (non-recursive, no trailing slash). Be mindful of context window limits.
        *   **Problems (`@problems`)**: Includes all errors and warnings from VS Code's Problems panel, grouped by file with paths and line numbers.
        *   **Terminal (`@terminal`)**: Includes the last command executed in the VS Code terminal and its complete output from the visible buffer.
        *   **Git Commit (`@commit-hash`)**: References a specific Git commit by its hash (e.g., `@a1b2c3d`), providing the commit message, author, date, and complete diff. Only works in Git repositories.
        *   **Git Changes (`@git-changes`)**: Shows uncommitted changes by providing `git status` output and a diff of the working tree. Only works in Git repositories.
        *   **URL (`@https://example.com`)**: Fetches content from the specified URL using a headless browser, removes scripts/styles/navigation, and converts the main content to Markdown. Complex pages may not convert perfectly.
    *   **Usage**:
        *   Type `@` to open the suggestions dropdown.
        *   The dropdown suggests recently opened files, visible folders, recent Git commits, special keywords (`problems`, `terminal`, `git-changes`), and all currently open files.
        *   Common directories like `node_modules`, `.git`, `dist`, `out` are filtered from suggestions but can be manually typed.
        *   Multiple mentions can be combined in a single request (e.g., "Fix @problems in @/src/component.ts").
    *   **Ignore File Interactions**:
        *   File and Folder `@mentions` **bypass** `.rooignore` and `.gitignore` rules when fetching content for context.
        *   Git-related mentions (`@git-changes`, `@commit-hash`) **respect** `.gitignore` rules as they rely on underlying Git commands.

## 5. Features

*   **Core Capabilities (from `docs/index.md`):**
    *   🚀 **Generate Code** from natural language descriptions.
    *   🔧 **Refactor & Debug** existing code.
    *   📝 **Write & Update** documentation.
    *   🤔 **Answer Questions** about your codebase.
    *   🔄 **Automate** repetitive tasks.
    *   🏗️ **Create** new files and projects.
*   **Custom Modes (from `docs/index.md`):**
    *   Create unlimited specialized personas for security auditing, performance optimization, documentation, or any other task.
    *   **Details (from `docs/features/custom-modes.mdx`):**
        *   **Definition**: Custom Modes allow tailoring Roo's behavior for specific tasks/workflows. They can be **global** (available across all projects) or **project-specific**.
        *   **Sticky Models**: Each mode (including custom) features Sticky Models, meaning Roo remembers and auto-selects the last AI model used with that mode.
        *   **Why Use Custom Modes?**:
            *   **Specialization**: Optimize for tasks like "Documentation Writer," "Test Engineer."
            *   **Safety**: Restrict access to sensitive files or commands (e.g., a read-only "Review Mode").
            *   **Experimentation**: Safely try different prompts/configurations.
            *   **Team Collaboration**: Share modes to standardize workflows.
        *   **Custom Mode Properties (JSON & UI fields)**:
            *   `slug` (string): Unique internal ID (lowercase, numbers, hyphens), used for linking mode-specific instruction files (e.g., `.roo/rules-{slug}/`).
            *   `name` (string): Display name in the UI.
            *   `roleDefinition` (string): Core identity and expertise of the mode. Placed at the start of the system prompt. The first sentence serves as a default summary unless `whenToUse` is defined.
            *   `groups` (array): Defines allowed toolsets (strings: "read", "edit", "browser", "command", "mcp"). File restrictions for the "edit" group can be specified using `fileRegex` (e.g., `["edit", { "fileRegex": "\\\\.md$", "description": "Markdown only" }]`). Regex patterns require double backslashes in JSON.
            *   `whenToUse` (string, optional): Guidance for Roo (especially Orchestrator mode via `new_task` or `switch_mode` tools) on when the mode is appropriate. If defined, this text is used for summarization, taking precedence over the first sentence of `roleDefinition`.
            *   `customInstructions` (string, optional): Specific behavioral guidelines for the mode, added near the end of the system prompt. Can be supplemented by file-based mode-specific instructions.
        *   **Methods for Creating/Configuring**:
            1.  **Ask Roo! (Recommended)**: Roo Code guides the creation process.
            2.  **Using the Prompts Tab UI**: (<Codicon name="notebook" /> icon) → <Codicon name="add" /> button. Provides fields for all key properties.
            3.  **Manual JSON Configuration**:
                *   Global Modes: Edit `custom_modes.json` (via Prompts Tab > Settings Menu <Codicon name="bracket" /> > "Edit Global Modes").
                *   Project Modes: Edit `.roomodes` file in project root (via Prompts Tab > Settings Menu <Codicon name="bracket" /> > "Edit Project Modes").
                *   Both files use a `customModes` array of mode objects.
        *   **Mode-Specific Instructions via Files/Directories**:
            *   Complements the JSON `customInstructions` property.
            *   Preferred: Directory `.roo/rules-{mode-slug}/` in workspace root (files read alphabetically, recursively).
            *   Fallback: Single file `.roorules-{mode-slug}` in workspace root.
            *   The directory method takes precedence if it exists and contains files.
        *   **Configuration Precedence**: Project-level (`.roomodes`) configurations override Global (`custom_modes.json`) configurations, which override Default built-in modes.
        *   **Overriding Default Modes**: Create a custom mode with the same `slug` as a default mode (e.g., `code`, `debug`, `orchestrator`) to customize its behavior globally or per-project.
        *   **Regex for File Restrictions (`fileRegex`)**:
            *   Used in the `groups` property for the "edit" tool to control which files the mode can modify.
            *   Requires double backslashes for special characters in JSON (e.g., `"\\\\.md$"`).
            *   Matches against the full relative file path from the workspace root.
            *   Case-sensitive by default.
            *   It's suggested to ask Roo to help generate complex regex patterns.
        *   **Community Resources**:
            *   [Custom Modes Gallery](/community/#custom-modes-gallery) for discovering and sharing.
            *   Tutorial Video: [Custom Modes in Roo Code](https://www.youtube.com/embed/qgqceCuhlRA).
    *   Purpose and benefits (Details from `docs/features/custom-modes.mdx`)
    *   How to create them (Details from `docs/features/custom-modes.mdx`)
    *   Limiting file edit permissions (Details from `docs/features/custom-modes.mdx`)
*   **Custom Instructions (from `docs/index.md`):**
    *   For personalized behavior.
    *   **Details (from `docs/features/custom-instructions.md`):**
        *   **Purpose**: Personalize Roo Code's behavior by providing specific guidance that shapes responses, coding style, decision-making processes, documentation standards, testing requirements, and workflow guidelines.
        *   **Types and Configuration**:
            *   **Global Custom Instructions**:
                *   Apply across all workspaces.
                *   Set in: Prompts Tab (<Codicon name="notebook" /> icon) → "Custom Instructions for All Modes" section.
            *   **Workspace-Level Instructions**: Apply only within the current workspace.
                *   **Workspace-Wide Instructions** (for all modes in the project):
                    *   Preferred: Directory `.roo/rules/` in workspace root. Instruction files (e.g., `.md`, `.txt`) within are read recursively and appended alphabetically by filename.
                    *   Fallback: Single file `.roorules` in workspace root (if `.roo/rules/` is absent or empty).
                *   **Mode-Specific Instructions** (for a particular mode):
                    *   **UI Method**: Prompts Tab → Select Mode → "Mode-specific Custom Instructions (optional)" text area. (Note: If the mode is global, these instructions also apply globally for that mode).
                    *   **File-Based Method** (in workspace root):
                        *   Preferred: Directory `.roo/rules-{modeSlug}/` (e.g., `.roo/rules-code/`). Files read recursively, appended alphabetically.
                        *   Fallback: Single file `.roorules-{modeSlug}` (e.g., `.roorules-code`) (if mode-specific directory is absent or empty).
        *   **Precedence & Combination Order in System Prompt**: Instructions are combined in a specific order:
            1.  Language Preference (if set).
            2.  Global Custom Instructions (from Prompts Tab).
            3.  Mode-specific Custom Instructions (from Prompts Tab for the current mode).
            4.  Mode-Specific Custom Instructions (from Files/Directories: `.roo/rules-{modeSlug}/` then `.roorules-{modeSlug}`).
            5.  Workspace-Wide Custom Instructions (from Files/Directories: `.roo/rules/` then `.roorules`).
            *   Directory-based rules take precedence over file-based fallbacks within each level. More specific (mode) instructions appear before general (workspace-wide).
        *   **Rules for `.rules` files**:
            *   Location: Preferred in `.roo/` subdirectories; fallbacks in workspace root.
            *   Empty/missing files are skipped.
            *   Content included with a source header.
            *   Mode-specific rules complement (add to) global/workspace-wide rules.
        *   **Examples**: "Always use 4 spaces for indentation", "Use camelCase for variables", "Write unit tests for all new functions."
        *   **Team Standards**: Recommended to use `.roo/rules/` (and mode-specific `.roo/rules-{modeSlug}/`) under version control for team consistency.
        *   **Interaction**: Can be combined with [Custom Modes](/features/custom-modes) for advanced specialization.
    *   General vs. mode-specific (Further details from `docs/features/custom-instructions.md`)
*   **Shell Integration (from `docs/features/shell-integration.md`):**
    *   **Core Functionality**:
        *   Automatically enabled feature connecting Roo to the terminal's command execution lifecycle.
        *   Enables Roo to execute commands (via `execute_command` tool), read output in real-time, automatically detect and fix errors, observe exit codes, track working directory changes, and react intelligently to terminal output.
        *   Allows stopping running commands directly from the chat interface using a stop button next to the command execution message.
    *   **Troubleshooting "Shell Integration Unavailable" / Command Issues**:
        *   Update VSCode/Cursor to the latest version (VSCode 1.93+ required).
        *   Ensure a compatible shell is selected (bash, zsh, PowerShell, or fish) via "Terminal: Select Default Profile".
        *   Windows PowerShell users: Run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` then restart VSCode.
        *   WSL users: Add `. "$(code --locate-shell-integration-path bash)"` to your `~/.bashrc`.
    *   **Command Execution Fallback**:
        *   If Roo is configured to use VS Code's terminal integration (by UNCHECKING "Disable terminal shell integration") and it fails, Roo may attempt to execute commands directly using a background process.
        *   This fallback has limited features (e.g., real-time output streaming or precise exit code detection might be limited).
        *   A notification may appear in chat.
    *   **Terminal Integration Settings (Roo Settings <Codicon name="gear" /> → Terminal group)**:
        *   **Basic Settings**:
            *   `Terminal Output Limit`: Controls how much output Roo captures (default: 500 lines).
            *   `Compress progress bar output`: Shows only the final state of dynamic output like progress bars (default: enabled).
        *   **Advanced Settings (Require terminal restart)**:
            *   `Inherit environment variables`: Mirrors VSCode's `terminal.integrated.inheritEnv` setting (default: enabled for VSCode).
            *   `Disable terminal shell integration` (Key Setting):
                *   **CHECKED (Recommended)**: Roo uses its built-in inline terminal, displaying output directly in the chat.
                *   **UNCHECKED**: Roo attempts to use your active VS Code terminal panel (can be less reliable).
            *   **Settings applicable ONLY if "Disable terminal shell integration" is UNCHECKED**:
                *   `Terminal shell integration timeout`: For slow-loading shells (default: 15s).
                *   `Terminal command delay`: If output seems incomplete (default: 0ms).
                *   `Enable PowerShell counter workaround`: For issues with repeated PowerShell commands.
                *   `Clear ZSH EOL mark`: If Zsh's end-of-line marker (`%`) causes issues.
                *   `Enable Oh My Zsh integration`: For compatibility with Oh My Zsh.
                *   `Enable Powerlevel10k integration`: For compatibility with the Powerlevel10k Zsh theme.
                *   `Enable ZDOTDIR handling`: For custom Zsh startup file locations.
    *   **How Shell Integration Works**: VS Code establishes a connection with your shell, monitoring prompts, command execution (start, finish, success/failure), and current directory.
    *   **Manual Shell Integration Installation**: If automatic setup fails, the docs provide lines to add to shell configuration files (`.bashrc`, `.zshrc`, PowerShell `$Profile`, `config.fish`).
    *   **WSL (Windows Subsystem for Linux) Integration**:
        *   Recommended to launch VSCode from within WSL (e.g., `code .` in your project directory within WSL) for optimal performance and reliability.
    *   **Known Issues and Workarounds**:
        *   **Ctrl+C Behavior**: Roo may press Ctrl+C to clear the line before running a command if text is present, potentially interrupting existing processes. Ensure prompt is clear.
        *   **Multi-line Commands**: Can confuse Roo. Use command chaining (`&&`) instead.
        *   **PowerShell Issues**: Premature completion or refusal to run same command twice. Use "PowerShell counter workaround" and `Terminal command delay`.
        *   **Incomplete Terminal Output**: Try closing and reopening the terminal tab.
    *   **Troubleshooting Resources**:
        *   VSCode Developer Tools Console (Help → Toggle Developer Tools → Console, look for `[Terminal Process]`).
        *   [VSCode Terminal Integration Test Extension](https://github.com/KJ7LNW/vsce-test-terminal-integration).
*   **Auto-Approving Actions (from `docs/index.md`):**
    *   For faster workflows.
    *   **Details (from `docs/features/auto-approving-actions.md`):**
        *   **SECURITY WARNING**: Bypasses confirmation prompts, giving Roo direct system access. Can result in data loss, file corruption, or worse. Command line access is particularly dangerous. Enable only for trusted actions.
        *   **Purpose**: Speeds up workflow by eliminating repetitive confirmation prompts.
        *   **Configuration Methods**:
            *   **Auto-Approve Toolbar** (above chat input):
                *   Click to expand/collapse.
                *   Configure individual permissions.
                *   **Master Toggle** (leftmost checkbox): Quickly enable/disable all permissions.
            *   **Advanced Settings Panel** (Gear icon <Codicon name="gear" /> → Auto-Approve Settings):
                *   Detailed control with security context.
        *   **Available Permissions & Risk Levels**:
            *   **Read files and directories**: Medium risk. (Could expose sensitive data).
            *   **Edit files**: High risk.
                *   Allows modification without confirmation.
                *   Includes a 'Delay after writes' slider (default 1000ms) for VSCode Problems pane diagnostics (Roo checks Problems pane during this delay).
            *   **Execute approved commands**: High risk.
                *   Runs whitelisted terminal commands automatically.
                *   Uses a command prefix whitelist; '*' allows all (use with extreme caution).
            *   **Use the browser**: Medium risk. (Allows headless browser interaction).
            *   **Use MCP servers**: Medium-High risk (depends on configured tools).
                *   Requires both global setting and the tool's individual 'Always allow' checkbox.
            *   **Switch modes**: Low risk.
            *   **Create & complete subtasks**: Low risk.
            *   **Retry failed API requests**: Low risk.
                *   Includes 'Delay before retrying the request' slider (default 5s).
    *   Settings and implications (Further details from `docs/features/auto-approving-actions.md`)
    *   Cautionary notes (Emphasized throughout `docs/features/auto-approving-actions.md`)
*   **Model Context Protocol (MCP) (from `docs/index.md` and `docs/features/mcp/overview.md`):**
    *   **Definition**: MCP is a standard for extending Roo Code's capabilities by connecting to external tools and services.
    *   **MCP Servers**: These external servers provide additional tools and resources to Roo Code, such as accessing databases, custom APIs, and specialized functionality, thereby augmenting Roo's built-in capabilities.
    *   **Core Idea**: Allows integration with unlimited custom tools, enabling connections to external APIs, databases, or specialized development utilities.
    *   **Documentation Overview (found in `docs/features/mcp/`):**
        *   **Using MCP in Roo Code (from `docs/features/mcp/using-mcp-in-roo.mdx`)**:
            *   **Server Configuration**:
                *   **Levels**: Global (in `mcp_settings.json`, accessible via VS Code settings) and Project-level (in `.roo/mcp.json` at project root). Project-level overrides global for same server names.
                *   **Editing**: Both global and project files can be edited via Roo Code's MCP settings panel (<Codicon name="server" /> icon → "Edit Global MCP" / "Edit Project MCP").
                *   **JSON Structure**: A `mcpServers` object containing named server configurations.
            *   **Transport Type Configuration Parameters**:
                *   **STDIO (Local)**: `command` (required executable), `args` (array), `cwd` (working directory), `env` (environment variables), `alwaysAllow` (array of tool names for auto-approval), `disabled` (boolean).
                *   **SSE (Remote)**: `url` (required server URL), `headers` (custom HTTP headers), `alwaysAllow`, `disabled`.
            *   **Enabling/Disabling MCP Functionality (MCP Settings Panel)**:
                *   `Enable MCP Servers` toggle: Master switch. Disabling removes MCP logic from system prompt (reduces token usage).
                *   `Enable MCP Server Creation` toggle: Removes server creation instructions from system prompt (reduces token usage).
            *   **Roo Creating MCP Servers**:
                *   Requires "Enable MCP Server Creation" to be ON.
                *   Roo scaffolds a server (usually TypeScript) in a default directory (e.g., `~/Documents/Cline/MCP` on macOS) or user-specified path.
                *   Roo writes tool code, handles secrets by asking the user (via `ask_followup_question` tool), auto-configures the server in the JSON settings, and attempts to activate it.
            *   **Managing Individual MCP Servers (MCP Settings Panel)**:
                *   **Delete**: Trash icon (<Codicon name="trash" />) with confirmation.
                *   **Restart**: Refresh icon (<Codicon name="refresh" />).
                *   **Enable/Disable Server**: Activate toggle (<Codicon name="activate" />).
                *   **Network Timeout**: Per-server dropdown (30s - 5m, default 1m).
                *   **Auto Approve Tools**: Per-tool `Always allow` checkbox. This requires the global "Use MCP servers" auto-approval option (in general Auto-Approve Settings) to also be enabled.
            *   **Finding/Installing Servers**: Roo Code doesn't pre-install servers. Users can find community servers, ask Roo to create one, or build their own (SDK: `https://github.com/modelcontextprotocol/`).
            *   **Using MCP Tools**: Roo automatically detects tools from active servers; user approves use unless auto-approved.
            *   **Troubleshooting**: Common issues include server not responding, permission errors, tool unavailability, slow performance.
            *   **Platform-Specific & Runtime Manager Configurations**: Examples provided for Windows (`cmd /c npx ...`), macOS/Linux (`npx ...`), and using version managers like `mise` or `asdf`.
        *   **What is MCP? (from `docs/features/mcp/what-is-mcp.md`)**:
            *   **Definition**: MCP (Model Context Protocol) is a standardized communication protocol designed for LLM (Large Language Model) systems to interact with external tools and services. It acts as a universal adapter.
            *   **How It Works**: It uses a client-server architecture:
                1.  The AI assistant (e.g., Roo Code) acts as the client and connects to MCP servers.
                2.  Each MCP server provides specific capabilities (e.g., 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.
            *   **Analogy**: Similar to a USB-C port, allowing any compatible LLM to connect to any MCP server for its functionality, standardizing tool integration.
            *   **Common Questions Clarified**:
                *   **Deployment**: MCP servers can run locally or remotely (as cloud services).
                *   **Relation to Other Methods**: MCP complements existing integration methods like API plugins and Retrieval-Augmented Generation (RAG); it doesn't replace them but provides a standard protocol for tool interaction.
                *   **Security**: Users control which MCP servers they connect to and their permissions. It's crucial to use trusted sources and configure appropriate access controls.
            *   **MCP in Roo Code**:
                *   Roo Code implements MCP to connect to both local and remote MCP servers.
                *   It provides a consistent interface for accessing tools from these servers.
                *   This allows Roo Code's functionality to be extended without modifying its core code.
                *   Enables specialized capabilities to be available on demand.
            *   **Overall Purpose**: To offer a standardized way for AI systems to interact with external tools and services, making complex integrations more accessible and consistent.
        *   **STDIO & SSE Transports (from `docs/features/mcp/server-transports.md`)**: MCP supports two primary transport mechanisms:
            *   **STDIO (Standard Input/Output) Transport**:
                *   **Mechanism**: Runs locally. Roo Code spawns the MCP server as a child process. Communication occurs via the server's STDIN (client-to-server) and STDOUT (server-to-client) streams, using newline-delimited JSON-RPC 2.0 messages.
                *   **Characteristics**: Local execution, very low latency, simple setup (no network configuration), one-to-one client-server relationship, inherently more secure due to no network exposure.
                *   **Use Cases**: Ideal for local integrations, tools running on the same machine, security-sensitive operations, low-latency requirements, single-client scenarios (one Roo instance per server), and command-line tools or IDE extensions.
                *   **Deployment (Local Model)**: Requires per-user installation and updates of the server executable, uses local machine resources, relies on local filesystem permissions, and its lifecycle is often tied to Roo Code.
                *   **SDK Component**: `@modelcontextprotocol/sdk/server/stdio`.
            *   **SSE (Server-Sent Events) Transport**:
                *   **Mechanism**: Runs on a remote server. Roo Code (client) connects to the server's SSE endpoint via an HTTP GET request, establishing a persistent connection for the server to push events (messages) to the client. Client-to-server communication uses separate HTTP POST requests to a different message endpoint.
                *   **Characteristics**: Enables remote access, scalable to handle multiple client connections, works over standard HTTP/HTTPS, maintains a persistent connection for server-to-client messages, and can use standard HTTP authentication.
                *   **Use Cases**: Better for remote access across networks, multi-client scenarios, public services, centralized tools accessed by many users, and integration with web services.
                *   **Deployment (Hosted Model)**: Involves centralized server installation and updates, uses server resources, managed by server-side access control, and runs as an independent, often continuously available, service.
                *   **SDK Component**: `@modelcontextprotocol/sdk/server/sse` (example often shown with Express.js).
            *   **Hybrid Approaches**: The documentation also mentions the possibility of hybrid approaches, like a local STDIO server acting as a proxy to remote SSE services.
            *   **Choosing**: A detailed comparison table in the docs helps decide based on factors like location, client numbers, performance, setup complexity, security, network needs, scalability, deployment, updates, resource usage, and dependencies.
            *   **Configuration in Roo Code**: Detailed setup for these transports in Roo Code is covered in the "Using MCP in Roo Code" guide, specifically the "Understanding Transport Types" section.
        *   **MCP vs API**: Analyzes the distinction between MCP and traditional REST APIs, highlighting their different operational layers concerning AI systems.
        *   **Recommended MCP Servers (from `docs/features/mcp/recommended-mcp-servers.md`)**:
            *   **Context7**:
                *   **Status**: First-choice general-purpose MCP server recommended for Roo Code.
                *   **Key Advantages**:
                    *   One-command install (`npx -y @upstash/context7-mcp@latest`).
                    *   Cross-platform (macOS, Windows, Linux, Docker).
                    *   Actively maintained by the Upstash team.
                    *   Rich toolset including database access, web-search, and text utilities.
                    *   Open source (MIT license).
                *   **Installation in Roo Code**:
                    *   **Global Configuration**: Via Roo Code MCP settings panel (<Codicon name="server" /> icon) → "Edit Global MCP". Add JSON to `mcpServers` (e.g., `{"context7": {"command": "npx", "args": ["-y", "@upstash/context7-mcp@latest"]}}`). Windows `cmd.exe` variant provided.
                    *   **Project-Level Configuration**: Create `.roo/mcp.json` in project root with the same JSON structure.
                    *   **Precedence**: Project-level configuration overrides global for servers with the same name.
                *   **Verification**:
                    1.  Ensure "Enable MCP Servers" is ON in MCP settings.
                    2.  Context7 should appear in the server list; activate if needed (<Codicon name="activate" /> toggle).
                    3.  Approve the first tool invocation from Context7.
                *   **Post-Setup**: Browse available tools, configure "Always allow" for frequently used ones.
    *   **MCP vs. REST APIs (from `docs/features/mcp/mcp-vs-api.md`)**:
        *   **Fundamental Distinction**: Comparing MCP to REST APIs is a category error. They operate at different layers of abstraction and serve fundamentally different purposes in AI systems.
        *   **Architectural Differences**:
            *   **MCP**: Stateful, maintains context across interactions; uses persistent, bidirectional JSON-RPC based connections with ongoing sessions; context handling is intrinsic; allows runtime discovery and integration of tools.
            *   **REST APIs**: Stateless, each request is independent; uses one-way HTTP request/response; context must be manually managed; requires design-time integration with prior knowledge of tools/APIs.
        *   **Different Layers, Different Purposes**:
            *   REST APIs are a low-level web communication pattern exposing operations on resources.
            *   MCP is a high-level AI protocol that orchestrates tool usage and maintains context. MCP often uses REST APIs internally but abstracts them away for the AI.
        *   **Context Preservation**: MCP's stateful design is critical for AI, maintaining context across multiple tool uses within a session. REST's statelessness requires manual context passing between steps.
        *   **Dynamic Tool Discovery**: MCP enables an AI to discover and use tools at runtime. New tools can be added without redeploying or modifying the AI itself.
        *   **Why Roo Code Uses MCP**:
            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.
        *   **Conclusion**: MCP and REST APIs are complementary, not competing. MCP builds upon REST, providing an AI-native, stateful interaction layer that AI agents need to function effectively.
    *   (Further details from specific MCP sub-pages to be added as they are processed).
*   **API Configuration Profiles (from `docs/features/api-configuration-profiles.md`):**
    *   **Definition**: Allow creating and switching between different sets of AI settings (provider, API key, model, temperature, thinking budgets, provider-specific settings, diff editing config, rate limits).
    *   **Benefit**: Quickly switch setups without full reconfiguration; optimize experience per task.
    *   **Profile Contents**: Each profile can store its own:
        *   API provider (OpenAI, Anthropic, OpenRouter, etc.)
        *   API key and authentication details
        *   Model selections (e.g., o3-mini-high, Claude 3.7 Sonnet)
        *   [Temperature settings](/features/model-temperature)
        *   Thinking budgets
        *   Provider-specific settings (Note: available settings vary by provider/model)
        *   Diff editing configuration (v3.12+)
        *   Rate limit settings (minimum time in seconds between API requests for the profile, 0=disabled/default).
    *   **Creating a Profile**:
        1.  Open Settings (gear icon <Codicon name="gear" /> → Providers).
        2.  Click "+" button next to profile selector.
        3.  Enter profile name.
        4.  Configure settings (provider, key, model, rate limit, parameters).
    *   **Switching Profiles**:
        *   From Settings panel: Select from dropdown.
        *   During chat: Access API Configuration dropdown in chat interface.
    *   **Pinning and Sorting Profiles**:
        *   Hover over a profile in the dropdown to reveal pin icon.
        *   Pinned profiles appear at the top, sorted alphabetically.
        *   Unpinned profiles below, also sorted alphabetically.
    *   **Editing and Deleting Profiles**:
        *   Edit: Select profile in Settings to modify.
        *   Rename: Click pencil icon.
        *   Delete: Click trash icon (cannot delete the only profile).
    *   **Linking Profiles to Modes**:
        *   In Prompts tab (<Codicon name="notebook" />), explicitly associate a Configuration Profile with each Mode.
        *   System also remembers the last used profile for each mode.
    *   **Security**: API keys are stored securely in VSCode's Secret Storage and are never exposed in plain text.
    *   **Related Features**: Works with custom modes, local models, temperature settings per mode, usage tracking/cost info, per-profile diff editing configuration.
*   **Boomerang Tasks (Subtasks/Task Orchestration) (from `docs/features/boomerang-tasks.mdx`):**
    *   **Definition**: Allows breaking down complex projects into smaller, manageable pieces using the built-in **`🪃 Orchestrator` Mode** (aka Boomerang Mode). The Orchestrator mode delegates parts of the work (subtasks) to specialized Roo Code modes (e.g., `💻 Code`, `🏗️ Architect`, `🪲 Debug`).
    *   **Benefits**:
        *   **Tackle Complexity**: Manages large, multi-step projects.
        *   **Use Specialized Modes**: Leverages the best mode for each specific part of the work.
        *   **Maintain Focus & Efficiency**: Subtasks operate in isolated contexts with separate conversation histories. The parent (Orchestrator) task focuses on high-level workflow using concise summaries from completed subtasks.
        *   **Streamline Workflows**: Results from one subtask can be passed to the next.
    *   **How It Works**:
        1.  The `🪃 Orchestrator` Mode analyzes a complex task and suggests breaking it into a subtask (using the `new_task` internal tool, passing context via `message` parameter and specifying the specialized mode via `mode` parameter).
        2.  The parent task (in Orchestrator mode) pauses.
        3.  The new subtask begins in the designated specialized mode.
        4.  When the subtask's goal is achieved, it signals completion.
        5.  The parent task resumes, receiving only the summary of the subtask (passed via the `result` parameter of the `attempt_completion` internal tool by the subtask mode).
    *   **Key Considerations**:
        *   **Approval Required**: By default, user approval is needed for creating and completing each subtask. This can be automated via [Auto-Approving Actions](/features/auto-approving-actions#subtasks).
        *   **Context Isolation and Transfer**: Each subtask has its own isolated context and conversation history. Information must be explicitly passed:
            *   Down to subtask: Via initial instructions during subtask creation.
            *   Up to parent: Via the final summary upon subtask completion.
        *   **Navigation**: Roo Code's interface displays the task hierarchy (parent/children) and allows navigation between active and paused tasks.
    *   **Tutorial Video**: [Boomerang Tasks Orchestration](https://www.youtube.com/embed/RX862U09fnE)
*   **Browser Use / Automation (from `docs/features/browser-use.mdx`):**
    *   **Purpose**: Enables Roo Code to interact with websites directly from VS Code for testing web applications, automating browser tasks, and capturing screenshots.
    *   **Model Requirement**: Requires Claude Sonnet 3.5 or 3.7.
    *   **Default Operation**: Uses a built-in browser that launches automatically, captures screenshots, allows interaction with web elements, and runs invisibly in the background.
    *   **Typical Workflow**:
        1.  User asks Roo to visit a website (e.g., "Open the browser and view our site.", "Can you check if my website at https://roocode.com is displaying correctly?").
        2.  Roo launches the browser and shows a screenshot.
        3.  User requests additional actions (clicking, typing, scrolling).
        4.  Roo closes the browser when finished.
    *   **`browser_action` Tool**:
        *   Controls the browser instance.
        *   Returns screenshots and console logs after each action.
        *   **Workflow Rules**:
            *   Each browser session must start with `launch` and end with `close`.
            *   Only one browser action can be used per message.
            *   While the browser is active, no other tools can be used.
            *   User must wait for the response (screenshot and logs) before performing the next action.
        *   **Available Actions**:
            *   `launch`: Opens a browser at a URL.
            *   `click`: Clicks at specific coordinates.
            *   `type`: Types text into the active element.
            *   `scroll_down`: Scrolls down by one page.
            *   `scroll_up`: Scrolls up by one page.
            *   `close`: Closes the browser.
    *   **Configuration Settings** (Gear icon <Codicon name="gear" /> → Browser / Computer Use):
        *   **Enable browser tool**: Master toggle (Default: Enabled).
        *   **Viewport size**: Determines browser resolution.
            *   Default: Small Desktop (900x600).
            *   Options: Large Desktop (1280x800), Tablet (768x1024), Mobile (360x640).
            *   Tradeoff: Higher values provide a larger viewport but increase token usage.
        *   **Screenshot quality**: Controls WebP compression quality (1-100%).
            *   Default: 75%.
            *   Tradeoff: Higher values provide clearer screenshots but increase token usage.
        *   **Remote Browser Connection**: (Default: Disabled).
            *   Allows Roo to connect to an existing Chrome browser instance (running with remote debugging, typically on port 9222).
            *   Benefits: Useful for containerized environments, remote development, maintaining authenticated sessions, and using custom browser profiles/extensions.
            *   Setup: Checkbox in settings, "Test Connection" button. Commands provided in docs for launching Chrome with remote debugging on macOS, Windows, and Linux.
    *   **Tutorial Video**: [Browser Use in Roo Code](https://www.youtube.com/embed/SJae206swxA)
*   **`.rooignore` File (from `docs/features/rooignore.md`):**
    *   **Purpose**: To control Roo Code's access to project files and directories, similar to `.gitignore`. It helps protect sensitive information, prevent accidental changes to build artifacts or large assets, and define Roo's operational scope.
    *   **Usage**: Create a file named `.rooignore` in the root directory of the VS Code workspace. List patterns in this file (syntax identical to `.gitignore`) to specify items Roo should ignore.
    *   **Monitoring**: Roo Code actively monitors the `.rooignore` file, and changes are reloaded automatically. The `.rooignore` file itself is implicitly ignored by Roo.
    *   **Tool Interaction**:
        *   **Strict Enforcement (Read/Write Blocking)**: Tools like `read_file`, `write_to_file`, `apply_diff`, and `list_code_definition_names` will not operate on ignored files.
        *   **Potential Write Bypass (Current Limitation)**: Tools like `insert_content` and `search_and_replace` might bypass `.rooignore` rules during their final write operation.
        *   **File Discovery (`list_files`)**: Typically omits ignored files or marks them with a 🔒 symbol (visibility controlled by `showRooIgnoredFiles` setting, default true). Environment Details provided to Roo are also filtered.
        *   **Command Execution (`execute_command`)**: Checks if predefined file-reading commands (e.g., `cat`, `grep`) target an ignored file and blocks if so. This protection is limited to a predefined list of commands.
    *   **Limitations & Scope**:
        *   Applies only to files/directories within the current VS Code workspace root.
        *   Not a full system-level sandbox.
    *   **User Experience**:
        *   Visual cue (🔒) for ignored files in listings.
        *   Error messages to Roo and chat notifications to the user when an action is blocked.
*   **Fast Edits (from `docs/features/fast-edits.md`):**
    *   **Setting**: "Enable editing through diffs" (located in Settings <Codicon name="gear" /> → Advanced). Enabled by default.
    *   **Mechanism**:
        *   When enabled, Roo Code modifies files by applying diffs (differences) using an internal `apply_diff` tool, instead of rewriting entire files.
        *   **Benefits**: Faster file editing and prevention of truncated/corrupted writes (system detects and rejects AI attempts to write incomplete content).
        *   If disabled, Roo reverts to writing the entire file content for every edit using the `write_to_file` internal tool (slower, higher token usage).
    *   **Match Precision (Slider Setting)**:
        *   Controls how closely the code sections identified by the AI must match the actual code in the file before a diff is applied.
        *   **100% (Default)**: Requires an exact match (safest).
        *   **Lower Values (80%-99%)**: Allows "fuzzy" matching for minor differences. This can be useful if the file has been slightly modified but **increases the risk** of applying changes in the wrong place. Use with extreme caution.
        *   Internally, this adjusts a `fuzzyMatchThreshold` potentially used with algorithms like Levenshtein distance.
*   **Enhance Prompt (from `docs/features/enhance-prompt.md`):**
    *   **Purpose**: An experimental feature to improve the quality and effectiveness of user prompts before sending them to the AI model. Accessed by clicking the <Codicon name="sparkle" /> icon in the chat input.
    *   **Benefits**:
        *   Improved clarity and rephrasing for better AI understanding.
        *   Addition of relevant context (e.g., current file path, selected code).
        *   Inclusion of instructions to guide the AI towards specific formatting or detail levels.
        *   Reduction of ambiguity in user requests.
        *   Consistent prompt formatting.
    *   **How to Use**:
        1.  Type initial prompt in the Roo Code chat input.
        2.  Click the <Codicon name="sparkle" /> icon (bottom right of chat input).
        3.  Roo Code replaces the original prompt with an enhanced version. Review and optionally refine this enhanced prompt.
        4.  Send the enhanced prompt (Enter or Send icon <Codicon name="send" />).
    *   **Customizing the Enhancement Process**:
        *   Uses a customizable prompt template found in the **Prompts Tab** (<Codicon name="notebook" /> icon) → **"ENHANCE" Tab**.
        *   Edit the "Prompt" field; the default template includes the placeholder `${userInput}` which is replaced with the user's original prompt.
    *   **API Configuration for Enhance Prompt**:
        *   By default, uses the same API configuration selected for general Roo Code tasks.
        *   Can be changed independently in the **Prompts Tab** → **"ENHANCE" Tab** via the "API Configuration" dropdown, allowing selection of a different existing API Configuration Profile.
    *   **Limitations & Best Practices**:
        *   It's an experimental feature; enhanced prompt quality may vary.
        *   Always review the enhanced prompt carefully before sending.
        *   Can be used multiple times iteratively to refine a prompt.
        *   It is not a replacement for writing clear and specific initial prompts.
*   **Code Actions Integration (from `docs/features/code-actions.md`):**
    *   **VS Code Code Actions**: A standard VS Code feature (lightbulb icon 💡, right-click context menu, or keyboard shortcut `Ctrl+.` / `Cmd+.`) providing quick fixes, refactorings, etc., triggered by code selection or problems.
    *   **Roo Code's Provided Code Actions**:
        *   **`Add to Context`**: Quickly adds the selected code snippet to the Roo chat. Importantly, it includes the filename and line numbers, giving Roo precise context. This action is listed first in the Code Actions menu.
        *   **`Explain Code`**: Asks Roo Code to provide an explanation for the selected code.
        *   **`Improve Code`**: Asks Roo Code to suggest improvements for the selected code.
    *   **How to Use Roo Code's Code Actions**:
        1.  **From the Lightbulb (💡)**: Select code -> lightbulb appears -> click lightbulb -> choose Roo action.
        2.  **From the Right-Click Context Menu**: Select code -> right-click -> choose "Roo Code" submenu -> select action.
        3.  **From the Command Palette**: Select code -> `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS) -> type "Roo Code" -> choose relevant action.
    *   **Workflow**: After invoking a Roo Code Action, Roo Code will propose a solution or response in its chat panel, which the user then reviews and approves or rejects.
    *   **Customizing Code Action Prompts**:
        *   The prompts used by these Code Actions (specifically "Enhance Prompt", "Explain Code", and "Improve Code" which likely correspond to "Improve Code" and "Explain Code" actions) can be customized.
        *   This is done in the **Prompts Tab** (accessed via the <Codicon name="notebook" /> icon in the Roo Code top menu bar) under "Support Prompts".
        *   Placeholders like `${filePath}` and `${selectedText}` can be used in custom prompts to include contextual information.
*   **`.roorules` Files:**
    *   Purpose and usage
*   **Keyboard Shortcuts (from `docs/features/keyboard-shortcuts.md`):**
    *   **Purpose**: Streamline workflow, reduce mouse dependence, improve accessibility.
    *   **Available Keyboard Commands**:
        *   `roo.acceptInput`: Submits text from input area or accepts the primary suggestion/button. No default shortcut (user-configurable).
        *   `roo.focus`: Focuses the Roo Code input box. No default shortcut (user-configurable).
    *   **Setting up `roo.acceptInput`**:
        *   **Via VS Code UI**: Command Palette → "Preferences: Open Keyboard Shortcuts" → Search "roo.acceptInput" → Assign desired key combination (e.g., `Alt+Enter`, `Ctrl+Enter`, `Ctrl+Space`).
        *   **Via `keybindings.json`**: Command Palette → "Preferences: Open Keyboard Shortcuts (JSON)" → Add entry like:
            ```json
            {
              "key": "ctrl+enter", // Or your preferred combination
              "command": "roo.acceptInput",
              "when": "rooViewFocused" // Or "webviewViewFocus && webviewViewId == 'roo-cline.SidebarProvider'"
            }
            ```
    *   **Use Cases for `roo.acceptInput`**: Quick text submission, action confirmations, multi-step processes, keyboard-centric development (Vim/Neovim like), code reviews, documentation writing.
    *   **Accessibility Benefits**: Reduces mouse dependence and physical strain.
    *   **Troubleshooting**: Ensure Roo panel is focused; command selects primary button if multiple; check for shortcut conflicts; `when` clause in `keybindings.json` must be correct.
    *   **Limitations of `roo.acceptInput`**: Works only when Roo interface is active; no effect if no inputs/suggestions available; prioritizes the primary (first) button.
*   **Sticky Models:**
    *   Assigning specific models to modes.
*   **Checkpoints (from `docs/features/checkpoints.md`):**
    *   **Purpose**: Automatically versions workspace files during Roo Code tasks, enabling non-destructive exploration of AI suggestions and easy recovery from unwanted changes.
    *   **Benefits**: Safe experimentation, easy recovery from undesired modifications, comparison of different implementation approaches, ability to revert to previous project states.
    *   **Key Requirements & Notes**:
        *   Enabled by default.
        *   **Git must be installed** on the system for checkpoints to function.
        *   No GitHub account or remote repository is required.
        *   The shadow Git repository used by checkpoints operates independently from the project's existing Git configuration.
    *   **Configuration**: Can be enabled/disabled in Roo Code Settings (Gear icon <Codicon name="gear" /> → Checkpoints) via "Enable automatic checkpoints" checkbox.
    *   **How It Works**:
        *   Roo Code captures snapshots (checkpoints) of the project's state using a **shadow Git repository**.
        *   Checkpoints are stored as Git commits in this shadow repository.
        *   Automatically records changes when tasks begin, files change, or commands run.
        *   Captures file content changes, new files, deleted files, renamed files, and binary file changes.
    *   **Working with Checkpoints (via Chat Interface)**:
        *   **Initial Checkpoint**: Marks the project state at the beginning of a task.
        *   **Regular Checkpoints**: Appear in chat history after file modifications or command execution.
        *   **`View Differences` Button**: Allows comparison of the current workspace with a previous checkpoint, showing a detailed diff.
        *   **`Restore Checkpoint` Button**:
            *   **`Restore Files Only` Option**: Reverts only workspace files to the checkpoint state, preserving conversation history. No confirmation needed. Ideal for comparing alternatives.
            *   **`Restore Files & Task` Option**: Reverts both workspace files AND removes all subsequent conversation messages. Resets code and conversation to the checkpoint's point in time. Requires confirmation as it's irreversible.
    *   **Limitations & Considerations**:
        *   **Scope**: Checkpoints only capture changes made during active Roo Code tasks.
        *   **External Changes**: Modifications made outside of Roo Code tasks (e.g., manual edits) are not included.
        *   **Large Files**: Very large binary files might impact performance.
        *   **Unsaved Work**: Restoring a checkpoint will overwrite any unsaved changes in the workspace.
    *   **Technical Implementation Highlights**:
        *   **Architecture**: Shadow Git Repository, Checkpoint Service (handles Git ops, state management using `simple-git` library), UI Components in chat.
        *   **File Exclusion**: Uses built-in exclusion patterns (for `node_modules`, `dist/`, media, cache, `.env`, etc.) stored in the shadow repo's `.git/info/exclude`. Also respects the workspace's `.gitignore` file. The `.rooignore` file (for AI access) is separate and does not affect checkpoint versioning.
        *   **Nested Git Repositories**: Handled by temporarily renaming nested `.git` directories.
        *   **Concurrency Control**: Operations are queued to prevent corruption.
    *   **Git Installation**: The documentation provides instructions for installing Git on macOS, Windows, and Linux, as it's a prerequisite.
*   **Settings Management (Import, Export, Reset) (from `docs/features/settings-management.md`):**
    *   **Location**: Options are found at the bottom of the Roo Code settings page (accessed via the gear icon <i class="codicon codicon-gear"></i> in the Roo Code chat view).
    *   **Export Settings**:
        *   Saves current Roo Code settings to a JSON file (default: `roo-code-settings.json`).
        *   **Exported Content**: API Provider Profiles and Global Settings (UI preferences, mode configurations, context settings, etc.).
        *   **Security Warning**: The exported JSON file contains **API keys in plaintext**. This file should be treated as highly sensitive and not shared publicly or with untrusted individuals.
    *   **Import Settings**:
        *   Loads settings from a previously exported JSON file.
        *   **Behavior**: Merges configurations – adds new API profiles/settings and updates existing ones based on the file. It does not delete configurations currently in Roo Code but missing from the imported file.
        *   **Validation**: Only valid settings matching Roo Code's internal schema can be imported.
    *   **Reset Settings**:
        *   Completely clears all Roo Code configuration data and returns the extension to its default, freshly installed state.
        *   **Warning**: This action is **irreversible** and requires confirmation.
        *   **What is Reset**:
            *   All API Provider Profiles (deleted from settings and secret storage).
            *   All Global Settings (reset to defaults).
            *   All user-defined Custom Modes.
            *   All API keys and other secrets from VSCode's Secret Storage managed by Roo Code.
            *   The current task stack (task history).
        *   **Recommendation**: Use only for troubleshooting or starting fresh. Consider exporting settings first for potential restoration.
*   **Additional Features (from `docs/features/more-features.md` and `docs/features/suggested-responses.md`):**
    *   **Suggested Responses**:
        *   **Purpose**: When Roo needs more information and uses the [`ask_followup_question` tool](/advanced-usage/available-tools/ask-followup-question), it can provide suggested answers to make responding easier and faster.
        *   **Appearance**: Clickable buttons directly below Roo's question in the chat interface.
        *   **Interaction Methods**:
            1.  **Direct Selection**: Click the button containing the desired answer. The selected answer is immediately sent to Roo.
            2.  **Keyboard Shortcut**: Use the `roo.acceptInput` command (with a user-configured keyboard shortcut) to automatically select and send the primary (first) suggestion.
            3.  **Edit Before Sending**:
                *   Hold down `Shift` and click the suggestion button, OR
                *   Hover over the suggestion button and click the pencil icon (<Codicon name="edit" />) that appears.
                *   This copies the suggestion's text into the chat input box, allowing modification before sending.
        *   **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.
    *   **Text to Speech (TTS)**:
        *   **Purpose**: Reads AI responses aloud; useful for accessibility, learning, or change of pace.
        *   **Configuration**: Enabled in Roo Code settings.
        *   **Interaction**: Once enabled, a speaker icon appears next to each AI response in the chat; click the icon to start listening.
    *   **Global Language Support**:
        *   **Purpose**: Makes Roo Code accessible to a wider global range of users.
        *   **Supported Languages (14)**: Simplified Chinese, Traditional Chinese, Spanish, Hindi, French, Portuguese, German, Japanese, Korean, Italian, Turkish, Vietnamese, Polish, Catalan.
        *   **Configuration**: Changed in Roo Code settings → Advanced Settings > Language.
*   **Model Temperature (from `docs/features/model-temperature.md`):**
    *   **Definition**: A setting (usually 0.0 to 2.0) that controls the randomness or predictability of AI model outputs. Lower values (e.g., 0.0) make output more focused and consistent; higher values (e.g., 1.0+) encourage more creativity and variation.
    *   **Important Note**: Temperature controls output randomness, not directly code quality or accuracy. Accuracy depends on the model's training and prompt clarity.
    *   **Default Values in Roo Code**:
        *   Most models (OpenAI, Anthropic non-thinking variants, LM Studio): **0.0** (for maximum determinism).
        *   DeepSeek R1 models and certain reasoning-focused models: **0.6**.
        *   Thinking-enabled models (with `:thinking` flag): Fixed at **1.0** (cannot be changed by user).
        *   Some models may not support temperature adjustment; Roo Code respects these limitations.
    *   **When to Adjust (Example Suggestions)**:
        *   Code Mode: 0.0-0.3 (for precise, deterministic code).
        *   Architect Mode: 0.4-0.7 (for brainstorming, balanced creativity).
        *   Ask Mode: 0.7-1.0 (for diverse, insightful explanations).
        *   Debug Mode: 0.0-0.3 (for consistent, precise troubleshooting).
    *   **How to Adjust**:
        1.  Open Roo Code Panel → Settings (<Codicon name="gear" /> icon) → Providers section.
        2.  Check the "Use custom temperature" box.
        3.  Adjust the slider to the preferred value.
    *   **Using API Configuration Profiles for Temperature**:
        *   Create multiple [API configuration profiles](/features/api-configuration-profiles) with different temperature settings (e.g., "Code - Low Temp" at 0.1, "Ask - High Temp" at 0.8).
        *   Switch between these profiles or set them as defaults for specific modes to automatically apply the desired temperature when changing modes.
    *   **Experimentation**: Recommended to find optimal settings for specific needs by starting with defaults, making incremental adjustments, testing consistently, documenting results, and saving effective settings in API configuration profiles.
    *   **Related Features**: Works with all API providers, complements custom instructions, and works alongside custom modes.
*   **Footgun Prompting (System Prompt Override) (from `docs/features/footgun-prompting.md`):**
    *   **Definition**: An advanced feature allowing users to replace the default system prompt for a specific Roo Code mode.
    *   **Warning**: Termed a "footgun" due to the high risk of unexpected behavior or breaking functionality (especially tool usage and response consistency) if not implemented carefully. A warning icon appears in the chat input area when an override is active for the current mode.
    *   **How It Works**:
        1.  User creates an override file named `.roo/system-prompt-{mode-slug}` in the workspace root (e.g., `.roo/system-prompt-code`).
        2.  The content of this file becomes the new core system prompt for that specific mode.
        3.  Roo Code automatically detects and uses this file if it exists and is not empty.
        4.  When active, this override replaces most standard system prompt sections (like tool descriptions, general rules, capabilities).
        5.  **Preserved Sections**: The mode's original `roleDefinition` and any `customInstructions` (from Prompts Tab or files) are retained and structured around the override content.
        6.  **Final Prompt Structure**: `${roleDefinition}\n\n${content_of_override_file}\n\n${customInstructions}`.
    *   **Accessing the Feature**:
        *   In the Prompts Tab (<Codicon name="notebook" /> icon), expand the "Advanced: Override System Prompt" section.
        *   Clicking the file path link in this section will open or create the correct override file for the currently selected mode.
    *   **Context Variables for Override Files**: Placeholders that Roo Code replaces with dynamic information:
        *   `{{mode}}`: Slug of the current mode.
        *   `{{language}}`: VS Code display language.
        *   `{{shell}}`: VS Code default terminal shell.
        *   `{{operatingSystem}}`: OS type (e.g., `Linux`, `Darwin`, `Windows_NT`).
        *   `{{workspace}}`: File path to the current project workspace root.
    *   **Key Considerations & Warnings**:
        *   Intended for advanced users familiar with Roo Code's prompting system.
        *   Mode-specific: Each override file affects only the mode specified in its filename.
        *   If the override file doesn't exist or is blank, the standard system prompt is used.
        *   Roo Code ensures the `.roo` directory exists.
        *   Use with extreme caution as it can significantly degrade performance and reliability.
*   **Experimental Features (Overview) (from `docs/features/experimental/experimental-features.md`):**
    *   **Nature**: These are features still under active development. They might be unstable, undergo significant changes, or be removed in future Roo Code versions.
    *   **Warning**: Users should enable and use experimental features at their own risk, being aware of potential unexpected behavior, data loss, or security vulnerabilities.
    *   **Enabling**: Experimental features can be enabled or disabled via: Roo Code Settings (<Codicon name="gear" /> icon) → "Advanced Settings" section → "Experimental Features" subsection.
    *   **Currently Listed Experimental Features** (details to be added from their respective pages):
        *   **Intelligent Context Condensation (`autoCondenseContext`)**:
            *   **Purpose**: Proactively manages lengthy conversation histories to prevent context loss as the LLM's context window limit is approached.
            *   **Mechanism**: When the context window is nearly full, Roo Code automatically uses an LLM to summarize the existing conversation history. This aims to reduce the token count while preserving essential information, thus preventing overflow and the silent dropping of older messages.
            *   **Message Handling**:
                *   Original messages are fully preserved when rewinding to old [Checkpoints](/features/checkpoints).
                *   However, messages that existed *before* the most recent summarization event are **not** included in subsequent API calls to the primary LLM; the summary effectively replaces them for ongoing context.
            *   **Cost Implication**: The LLM call performing the summarization incurs a cost. This cost is currently **not** reflected in the usage/cost figures displayed in the Roo Code UI.
            *   **Enabling**: Toggled via Roo Code Settings (<Codicon name="gear" />) → "Advanced Settings" → "Experimental Features" area → "Intelligently condense the context window" option.
            *   **Future Enhancements (Considered)**: Manual trigger for condensation, UI indicator of condensation events, user configuration for trigger conditions, and telemetry for evaluation.
            *   **Feedback**: Report issues/suggestions on the [Roo Code GitHub Issues page](https://github.com/RooVetGit/Roo-Code/issues).
        *   **Power Steering (`POWER_STEERING`)**:
            *   **Purpose**: Designed to enhance the consistency of Roo Code's responses by more frequently reminding the underlying LLM about its current mode definition (`modeDetails.roleDefinition`) and any custom instructions (`modeDetails.customInstructions`).
            *   **Mechanism**: When enabled, Roo Code explicitly includes the current mode's `roleDefinition` and `customInstructions` (wrapped in `<environment_details>` tags) within the information sent to the LLM with each interaction. The `getEnvironmentDetails` internal function checks the feature's status.
            *   **Goal**: To ensure the LLM adheres more strictly to its defined persona and follows user-specific instructions more consistently.
            *   **Trade-offs**:
                *   Increased token usage per message.
                *   Potentially higher operational costs.
                *   The context window may be filled more quickly.
            *   **Default Status**: Disabled.
            *   **Enabling**: Toggled via Roo Code Settings (<Codicon name="gear" />) → "Advanced Settings" → "Experimental Features" area → "Power Steering" option.
            *   **Feedback**: Report issues/suggestions on the [Roo Code GitHub Issues page](https://github.com/RooVetGit/Roo-Code/issues).
    *   **Feedback**: Issues or suggestions regarding experimental features should be reported on the [Roo Code GitHub Issues page](https://github.com/RooVetGit/Roo-Code/issues).

## 6. Advanced Usage

*   **Context Poisoning (from `docs/advanced-usage/context-poisoning.md`)**:
    *   **Definition**: Occurs when inaccurate or irrelevant data contaminates the LLM's active context, leading to incorrect conclusions, tool misuse, and progressive deviation from the intended task.
    *   **Persistence**: It's a persistent issue within a given chat session. Once a session's context is compromised, it should be treated as disposable.
    *   **Symptoms**:
        *   Degraded output quality (suggestions become nonsensical, repetitive, or irrelevant).
        *   Tool misalignment (tool calls no longer correspond to user requests).
        *   Orchestration failures (e.g., Orchestrator mode chains may stall, loop, or fail).
        *   Temporary fixes from re-prompting (issues resurface quickly).
        *   Model confusion about how to use tools defined in the system prompt.
    *   **Common Causes**:
        *   **Model Hallucination**: The LLM generates incorrect information and subsequently treats it as factual.
        *   **Code Comments**: Outdated, incorrect, or ambiguous comments in the codebase are misinterpreted.
        *   **Contaminated User Input**: Pasting logs or text containing hidden or rogue control characters.
        *   **Context Window Overflow**: As a session grows, older, useful information may be pushed out, allowing "poisoned" data to have a greater relative impact.
    *   **Ineffectiveness of "Wake-Up Prompts"**: Corrective prompts might offer temporary relief, but the problematic data remains in the conversational buffer. The model will likely revert to the poisoned state.
    *   **Effective Recovery Strategies**:
        *   **Hard Reset Session**: The most dependable solution is to start a new chat session, clearing the contaminated context entirely.
        *   **Minimize Manual Data Dumps**: When pasting logs or other data, be selective and only include essential information.
        *   **Manage Context Window Size**: For large or complex tasks, consider breaking them into smaller, focused chat sessions.
        *   **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.
    *   **"Magic Bullet" Prompt Myth**: No single prompt offers a lasting fix due to the persistence of corrupted history. The only robust solution is to discard the compromised session and start a new one with a clean prompt and correct tool definitions.
*   **Local Models (from `docs/advanced-usage/local-models.md` and `docs/index.md`):**
    *   **Overview**: Roo Code supports running language models locally on your own machine.
    *   **Advantages**:
        *   **Privacy**: Code and data remain on the user's computer.
        *   **Offline Access**: Roo Code can be used without an internet connection.
        *   **Cost Savings**: Avoids API usage fees from cloud-based models.
        *   **Customization**: Allows experimentation with different models and configurations.
    *   **Drawbacks**:
        *   **Resource Requirements**: Can be resource-intensive, needing a powerful computer (good CPU, ideally a dedicated GPU).
        *   **Setup Complexity**: Can be more complex than using cloud APIs.
        *   **Model Performance**: Performance varies; local models may not always match capabilities of large cloud models.
        *   **Limited Features**: Local models (and many online models) often don't support advanced Roo Code features like prompt caching or computer use.
    *   **Supported Local Model Providers**:
        1.  **Ollama** ([ollama.com](https://ollama.com/)):
            *   Popular open-source tool for running LLMs locally.
            *   Supports a wide range of models.
            *   Primarily command-line interface.
            *   Setup guide: See [Setting up Ollama](/providers/ollama).
        2.  **LM Studio** ([lmstudio.ai](https://lmstudio.ai/)):
            *   User-friendly desktop application for downloading, configuring, and running local models.
            *   Provides a local server that emulates the OpenAI API.
            *   Graphical user interface.
            *   Setup guide: See [Setting up LM Studio](/providers/lmstudio).
    *   **Troubleshooting**:
        *   **"No connection could be made..."**: Usually means the Ollama/LM Studio server isn't running or is on a different port/address than Roo Code is configured for (check Base URL setting).
        *   **Slow Response Times**: Can occur on less powerful hardware; try a smaller model.
        *   **Model Not Found**: Double-check model name spelling (for Ollama, use the name from the `ollama run` command).
*   **Managing Large Files:**
    *   `File read auto-truncate threshold` setting.
*   **Parallel Workflows:**
    *   Using multiple repository checkouts.
*   **Working with Large Projects (from `docs/advanced-usage/large-projects.md`)**:
    *   **Understanding Context Limits**: LLMs have a limited context window (max text/tokens processed at once). In Roo Code, this includes the system prompt, conversation history, content of `@` mentioned files, and output of commands/tools.
    *   **Strategies for Managing Context**:
        1.  **Be Specific**: Use specific file paths and function names in requests; avoid vague references.
    *   **Prompt Engineering Tips (from `docs/advanced-usage/prompt-engineering.md`)**:
        *   **Definition**: The art of crafting effective instructions for AI models like Roo Code to achieve 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. (e.g., Good: "Fix the bug in `calculateTotal` function...", Bad: "Fix the code.")
            *   **Provide Context**: Use [Context Mentions](/basic-usage/context-mentions) to refer to specific files, folders, or problems (e.g., `'src/utils.ts' (see below for file content) Refactor...`).
            *   **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 in your prompt.
            *   **Specify Output Format**: If you need output in a particular format (e.g., JSON, Markdown), specify it.
            *   **Iterate**: Don't be afraid to refine your prompt if initial results aren't as expected.
        *   **"Think-Then-Do" Process**: A helpful approach:
            1.  **Analyze**: Ask Roo Code to analyze current code, identify problems, or plan its approach.
            2.  **Plan**: Have Roo Code outline the steps it will take.
            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**:
            *   Global or Mode-Specific instructions can be used to provide persistent guidance (coding style, preferred libraries, project conventions, AI tone/personality). See [Custom Instructions](/features/custom-instructions).
        *   **Handling Ambiguity**:
            *   If a request is ambiguous, Roo Code might make assumptions (which could be incorrect) or use the `ask_followup_question` tool to clarify.
            *   It's generally better to provide clear, specific instructions initially.
        *   **Providing Feedback**:
            *   **Rejecting Actions**: Click "Reject" for unwanted proposed actions.
            *   **Providing Explanations**: When rejecting, explain *why* to help Roo Code learn.
            *   **Rewording Your Request**: Try rephrasing the task or adding more specific instructions.
            *   **Manually Correcting**: For minor issues, directly modify code before accepting changes.
        *   **Examples**: The document provides several good vs. bad prompt examples.
            *   Good: `'src/components/Button.tsx' (see below for file content) Refactor the Button component to use the useState hook...`
            *   Bad: `Fix the button.`
            *   Good: `Create a new file named utils.py and add a function called calculate_average...`
            *   Bad: `Write some Python code.`
            *   Good: `Workspace Problems (see below for diagnostics) Address all errors and warnings in the current file.`
            *   Bad: `Fix everything.`
    *   **Tool Use Overview (from `docs/advanced-usage/available-tools/tool-use-overview.md`)**:
        *   **Core Concepts**:
                *   **Tool Groups**: Tools are organized by functionality:
                *   **Read Group**: For file system reading/searching. Used for code exploration/analysis.
                    *   **`read_file` (from `docs/advanced-usage/available-tools/read-file.md`)**:
                        *   **Purpose**: Examines file contents (code, configuration, documents) to provide context to Roo Code. Returns content with line numbers.
                        *   **Parameters**: `path` (required string: relative file path), `start_line` (optional number: 1-based start line), `end_line` (optional number: 1-based inclusive end line).
                        *   **Key Features**: Provides line-numbered output. Supports reading specific line ranges (efficiently streams only requested lines). Extracts readable text from PDF and DOCX files. Automatically truncates large text files when no line range is specified (shows initial lines up to an internal limit like `maxReadFileLine` ~500 lines, and may append a summary of code definitions for code files).
                        *   **Reading Strategy Priority**: 1. Explicit Line Range (if `start_line` or `end_line` provided). 2. Automatic Truncation (for large text files without a range). 3. Full File Read (if neither of the above applies, or for supported binary types like PDF/DOCX).
                        *   **Limitations**: Can be inefficient for very large files if line range parameters are not used. For most binary files (excluding PDF and DOCX), it may return content that isn't human-readable. Respects `.rooignore` rules (returns error if access denied).
                    *   **`search_files` (from `docs/advanced-usage/available-tools/search-files.md`)**:
                        *   **Purpose**: Performs regex searches across multiple files in a project, showing each match with surrounding context (typically 1 line before and after).
                        *   **Parameters**: `path` (required string: directory to search in, relative to CWD), `regex` (required string: Rust regex syntax pattern), `file_pattern` (optional string: glob pattern to filter files, e.g., `*.ts`).
                        *   **Key Features**: Uses Ripgrep (`rg`) for high-performance searching. Shows context around matches. Filters files by type using glob patterns. Provides line numbers. Output limited to 300 results by default (with notification). Lines longer than 500 characters are truncated. Intelligently combines nearby matches into single blocks.
                        *   **Limitations**: Best with text-based files. Performance may slow with extremely large codebases. Uses Rust regex syntax, which may differ from other regex implementations. Cannot search within compressed files. Default context size is fixed (1 line before/after), though displayed context can vary if matches are close due to grouping.
                        *   **Workflow**: Parameter Validation → Path Resolution → Search Execution (Ripgrep, applies file pattern, collects matches with context) → Result Formatting (file paths, line numbers, context, `----` separator, result limit notice, line truncation, merges nearby matches).
                    *   **`list_files` (from `docs/advanced-usage/available-tools/list-files.md`)**:
                        *   **Purpose**: Displays files and directories within a specified location, helping Roo understand project structure.
                        *   **Parameters**: `path` (required string: directory path relative to CWD), `recursive` (optional boolean: `true` for recursive, `false`/omit for top-level).
                        *   **Key Features**: Lists files and directories (directories marked with `/`). Supports recursive and non-recursive modes. In recursive mode, intelligently ignores common large directories (e.g., `node_modules`, `.git`) and respects `.gitignore` rules. Marks files ignored by `.rooignore` with a 🔒 symbol if the `showRooIgnoredFiles` setting is enabled. Uses `ripgrep` for performance. Sorts results logically (directories before their contents).
                        *   **Limitations**: Output capped at ~200 files by default (with a note to use on subdirectories if limit is hit). The underlying `ripgrep` process has a 10-second timeout; partial results may be returned if exceeded. Cannot list root or home directories for security reasons. Not designed for confirming the existence of files just created by Roo.
                        *   **Workflow**: Parameter Validation → Path Resolution → Security Checks → Directory/File Scanning (using `ripgrep` and Node.js `fs`) → Result Filtering (common ignores, `.gitignore`, `.rooignore`) → Formatting and Output.
                    *   **`list_code_definition_names` (from `docs/advanced-usage/available-tools/list-code-definition-names.md`)**:
                        *   **Purpose**: Provides a structural overview of a codebase by listing top-level code definitions (classes, functions, interfaces, etc.) with line numbers and actual code snippets from source files found at the top level of a specified directory.
                        *   **Parameters**: `path` (required string: directory path relative to CWD).
                        *   **Key Features**: Extracts various definition types, shows line numbers and source code, supports multiple programming languages (JS, TS, Python, Rust, Go, C++, C, C#, Ruby, Java, PHP, Swift, Kotlin), processes a maximum of 50 files per request, focuses on top-level definitions, uses Tree-sitter for parsing.
                        *   **Limitations**: Only identifies top-level definitions (not nested ones). Scans only the top level of the specified directory (not recursive). Limited to processing a maximum of 50 files. Parsing quality is dependent on Tree-sitter's support for the specific language syntax. Does not provide information on how definitions are used or runtime behavior.
                        *   **Workflow**: Parameter Validation (`path`) → Path Resolution → Directory Scanning (top-level) → File Filtering (max 50) → Language Detection (by extension) → Code Parsing (Tree-sitter: AST → language-specific query → sort captures) → Result Formatting.
                        *   **Output Format**: Shows file paths followed by `START_LINE--END_LINE | definition_code_line`.
                *   **Edit Group**: For file system modifications. Used for code changes/file manipulation.
                    *   **`apply_diff` (from `docs/advanced-usage/available-tools/apply-diff.md`)**:
                        *   **Purpose**: Makes precise, surgical changes to files by specifying exact content to replace, using fuzzy matching guided by line number hints.
                        *   **Parameters**: `path` (required), `diff` (required, specific format). Optional top-level `start_line`/`end_line` seem unused by the main strategy, which relies on `:start_line:` within the diff content.
                        *   **Mechanism**: Uses fuzzy matching (e.g., Levenshtein distance on normalized strings) guided by a mandatory `:start_line:NUMBER` hint within each SEARCH block of the `diff` parameter. It searches middle-out within a context window (`BUFFER_LINES`, default 40) around the hinted line, based on a confidence threshold.
                        *   **Key Features**: Preserves formatting by replacing exact blocks, shows changes in a diff view for user review and editing, tracks `consecutiveMistakeCountForApplyDiff` per file to prevent repeated failures, respects `.rooignore` rules, handles multi-line edits.
                        *   **Diff Format**: Requires `<<<<<<< SEARCH ... ======= ... >>>>>>> REPLACE` blocks. Each SEARCH block must include a `:start_line:NUMBER` hint and a `-------` separator before the search content. `<<<<<<<` characters within the file's actual content must be escaped as `\\\\<<<<<<<` in the SEARCH block. Multiple change blocks can be submitted in one request.
                    *   **`insert_content` (from `docs/advanced-usage/available-tools/insert-content.md`)**:
                        *   **Purpose**: Adds new lines of content into an existing file at a specified location (or appends to the end) without modifying the original content. Ideal for inserting code blocks, configuration entries, or log lines.
                        *   **Parameters**: `path` (required, relative file path), `line` (required, 1-based line number *before* which to insert; `0` to append), `content` (required, text to insert).
                        *   **Key Features**: Targeted insertion/append, preserves existing content, shows proposed insertions in a diff view for interactive user approval (allows editing in diff view), tracks file context, handles errors.
                        *   **Limitations**: Insert-only (cannot replace or delete existing content). The target file must exist. Mandatory diff view approval step.
                        *   **Workflow**: Parameter Validation → File Reading → Insertion Point Calculation → Content Insertion (using internal `insertGroups` utility) → Diff View Interaction (using `cline.diffViewProvider`) → User Approval (via `askApproval`) → Saving Changes → File Context Tracking → Result Reporting.
                    *   **`search_and_replace` (from `docs/advanced-usage/available-tools/search-and-replace.md`)**:
                        *   **Purpose**: Finds and replaces text within a single file. Supports both literal strings and regular expression patterns, with options for case sensitivity and limiting the scope to specific line ranges.
                        *   **Parameters**:
                            *   `path` (required string): Relative file path.
                            *   `search` (required string): Text string or regex pattern to find.
                            *   `replace` (required string): Text to replace matches with.
                            *   `start_line` (optional number): 1-based start line for search scope.
                            *   `end_line` (optional number): 1-based inclusive end line for search scope.
                            *   `use_regex` (optional boolean string "true"/"false", default "false"): Treats `search` as regex if "true".
                            *   `ignore_case` (optional boolean string "true"/"false", default "false"): Performs case-insensitive search if "true".
                        *   **Key Features**: Flexible search (literal/regex), case sensitivity control, scoped replacements (line range), global replacement by default (within the defined scope), interactive approval via diff view (which allows user edits), context tracking.
                        *   **Limitations**: Operates on only one file at a time. Mandatory diff view approval step adds an interactive overhead. Complex regex patterns can be challenging to construct correctly.
                        *   **Workflow**: Parameter Validation → File Reading → Regex Construction (escapes search string if not regex; adds `g` and optionally `i` flags) → Replacement Execution (on full content or isolated line-scoped section) → Diff View Interaction → User Approval → Saving Changes → File Context Tracking → Result Reporting.
                    *   **`write_to_file` (from `docs/advanced-usage/available-tools/write-to-file.md`)**:
                        *   **Purpose**: Creates new files or completely replaces existing file content, with an interactive approval process via a diff view.
                        *   **Parameters**: `path` (required string: relative file path), `content` (required string: complete content to write), `line_count` (required number: number of lines in the content, including empty lines, used for truncation detection).
                        *   **Key Features**: Interactive approval with user edit support in the diff view. Safety measures include code omission/truncation detection (using `line_count`), path validation (e.g., `isOutsideWorkspace` check). Performs content preprocessing (removes AI artifacts like code block markers, handles HTML entities, strips line numbers). Validates against `.rooignore` restrictions. May handle parent directory creation.
                        *   **Limitations**: Not suitable for modifying existing files (slower and less efficient than `apply_diff`). Performance can degrade with large files. Completely overwrites existing file content. Requires `line_count`. Interactive only due to mandatory diff view approval.
                        *   **Workflow**: Parameter Validation → Content Preprocessing → Diff View Generation → User Approval Process → Safety Validation → File Writing.
                *   **Browser Group**: For web automation. Used for web testing/interaction.
                    *   **`browser_action` (from `docs/advanced-usage/available-tools/browser-action.md`)**:
                        *   **Purpose**: Enables web automation and interaction via a Puppeteer-controlled browser. Allows Roo to launch browsers, navigate, click elements, type text, and scroll, with visual feedback (screenshots) and console logs.
                        *   **Parameters**:
                            *   `action` (required): `launch`, `click`, `type`, `scroll_down`, `scroll_up`, `close`.
                            *   `url` (optional): For `launch` action.
                            *   `coordinate` (optional): For `click` action (e.g., "450,300").
                            *   `text` (optional): For `type` action.
                        *   **Key Features**: Visual feedback (screenshots, console logs), supports Local (default, sandboxed Puppeteer) and Remote (connects to existing Chrome with remote debugging) browser modes, uses `waitTillHTMLStable` algorithm for page load stability, manages session state.
                        *   **Limitations**: Only `browser_action` tool can be used while a browser session is active. Coordinates are viewport-relative. Clicks must target visible elements. Browser sessions must be explicitly closed with the `close` action before other tools can be used. Window size is configurable (default 900x600). Chrome/Chromium browsers only. Local mode has no access to existing cookies.
                        *   **Workflow**: Strict sequence: `launch` → interaction sub-actions (`click`, `type`, `scroll_down`, `scroll_up`) → `close`.
                *   **Command Group**: For system command execution. Used for running scripts/building projects.
                    *   **`execute_command` (from `docs/advanced-usage/available-tools/execute-command.md`)**:
                        *   **Purpose**: Runs CLI commands on the user's system (e.g., install dependencies, build projects, start servers).
                        *   **Parameters**: `command` (required string: CLI command), `cwd` (optional string: working directory).
                        *   **Key Features**: Integrates with VS Code's shell API for reliable execution, reuses terminal instances (via TerminalRegistry), captures real-time output, supports long-running and interactive commands, allows custom working directories, maintains terminal history/state, handles complex command chains, provides detailed completion status and exit code interpretation, security validation (using `shell-quote` to parse and block dangerous patterns like subshells), respects `.rooignore` for file access control, handles terminal escape sequences for clean output.
                        *   **Limitations**: Command access may be restricted by `.rooignore` or security validations; commands needing elevated permissions might require user-side configuration; behavior can vary across OS; very long-running commands may need specific handling; file paths in commands need proper OS-specific escaping.
                        *   **Workflow**: Command Validation & Security Checks (parsing, subshell blocking, `.rooignore` check) → Terminal Management (TerminalRegistry gets/creates terminal, sets CWD, shows terminal) → Command Execution & Monitoring (via VS Code shellIntegration API, captures output, throttled handling) → Result Processing (strips escape sequences, interprets exit codes, tracks CWD changes).
                *   **MCP Group**: For external tool integration via MCP. Used for specialized functionality.
                    *   **`use_mcp_tool` (from `docs/advanced-usage/available-tools/use-mcp-tool.md`)**:
                        *   **Purpose**: Enables interaction with external tools provided by connected Model Context Protocol (MCP) servers, extending Roo's capabilities with domain-specific functionality.
                        *   **Parameters**: `server_name` (required string: name of the MCP server), `tool_name` (required string: name of the tool on the server), `arguments` (JSON object, required/optional based on the external tool's schema: input parameters for the tool).
                        *   **Key Features**: Uses the `@modelcontextprotocol/sdk` library for standardized communication. Supports multiple transport mechanisms (StdioClientTransport for local servers, SSEClientTransport for remote). Validates arguments using Zod schema validation on both client and server sides. Processes multiple response content types: text, image, and resource references (which can be used by `access_mcp_resource`). Manages server lifecycle with automatic restarts when server code changes (via file watchers). Provides an "always allow" mechanism to bypass user approval for trusted tools. Supports configurable timeouts (1-3600 seconds, default 60s).
                        *   **Limitations**: Dependent on external MCP servers being available and connected. Limited to the tools provided by connected (and not disabled) servers. Network issues can affect reliability. Requires user approval before execution (unless the tool is on the "always allow" list for that server). Cannot execute multiple MCP tool operations simultaneously.
                        *   **Server Configuration**: MCP servers can be configured globally (in `mcp_settings.json` via Roo Code settings) or at the project level (in `.roo/mcp.json` at project root, which takes precedence and is shareable via VCS).
                        *   **Workflow**: Initialization & Validation (MCP hub checks server/tool, validates args against schema, gets timeout) → Execution & Communication (selects transport, sends request via SDK, tracks with timeout) → Response Processing (handles text/image/resource URI, checks `isError` flag) → Resource & Error Handling (uses WeakRef for memory, consecutive mistake counter, file watchers for server restarts).
                    *   **`access_mcp_resource` (from `docs/advanced-usage/available-tools/access-mcp-resource.md`)**:
                        *   **Purpose**: Retrieves data (context) from resources exposed by connected MCP servers (e.g., files, API responses, documentation, system information). Distinct from `use_mcp_tool` which executes actions.
                        *   **Parameters**: `server_name` (required), `uri` (required).
                        *   **Key Features**: Requires user approval, uses URI-based addressing, integrates with MCP SDK, handles text/image data, supports timeouts, discovers available resources, processes structured responses with metadata, special rendering for images.
                        *   **Limitations**: Dependent on MCP server availability and connection; limited to resources exposed by connected (and not disabled) servers; network issues can affect reliability; subject to configured timeouts; URI formats are server-implementation dependent; no offline or cached resource access.
                        *   **Workflow**: 1. Connection Validation (hub, server exists, server enabled). 2. User Approval (server name & URI shown). 3. Resource Request (uses MCP SDK, `resources/read` request to server via hub, applies timeouts). 4. Response Processing (handles structured response, text/image content).
                        *   **MCP Resource Types**: Servers can expose:
                            *   **Standard Resources**: Fixed URIs, defined name/description/MIME type, direct access (for static/real-time data).
                            *   **Resource Templates**: Parameterized URIs for dynamic resource generation (e.g., queries, filtered data views).
                *   **Workflow Group**: For mode and task management. Used for context switching/task organization.
                    *   **`ask_followup_question` (from `docs/advanced-usage/available-tools/ask-followup-question.md`)**:
                        *   **Purpose**: Enables interactive communication by asking specific questions to gather additional information, clarification, or user preferences.
                        *   **Parameters**: `question` (required string), `follow_up` (optional list of 2-4 suggested answers in `<suggest>` tags).
                        *   **Key Features**: Presents suggested answers as UI buttons, maintains conversation history, supports image/code snippet responses, is an "Always Available Tool", wraps user's response in `<answer>` tags, and resets a consecutive error counter upon successful use.
                        *   **Limitations**: One question per use; suggestions are UI-only options and must be complete (no placeholders); cannot force structured responses or validate them. Excessive use can slow down tasks.
                        *   **Workflow**: Validates parameters (parses suggestions from `follow_up` using `fast-xml-parser`), transforms to JSON for UI, integrates with UI (via `ask("followup", ...)` method), collects user response (text/images), wraps response in `<answer>` tags, adds to history, and resets error counter.
                    *   **`attempt_completion` (from `docs/advanced-usage/available-tools/attempt-completion.md`)**:
                        *   **Purpose**: Signals that Roo believes a task is complete, presents a summary of accomplishments, optionally includes a command to demonstrate the result, and supports continued refinement through user feedback.
                        *   **Parameters**: `result` (required string: summary of accomplishments), `command` (optional string: CLI command to demonstrate result).
                        *   **Key Features**: Clear completion signal, concise summary, optional command demo, enables user feedback, special "completion_result" UI format, captures task completion telemetry, supports subtask completion, "Always Available Tool".
                        *   **Limitations**: Guideline to confirm previous tool success (not programmatically enforced); single demo command; commands require user approval; demo limited to CLI-showable results; not for partial task updates; result formatting automatically strips XML closing tags (via internal `removeClosingTag` function).
                        *   **Workflow**: (Guideline: Confirm prior tool success) → Result Presentation (special UI, `removeClosingTag`) → Optional Command Execution (if provided and approved by user) → Feedback Collection (waits for user feedback, returns to AI) → Task Completion Signaling (system, telemetry, subtask handling).
                        *   **Result Formatting**: Should be clear, concise, value-focused, professional, easy to scan, and acknowledge feedback possibility.
                        *   **Command Selection**: Prefer commands that visually demonstrate results (e.g., `open index.html`, `npm start`), avoid text-only commands (`echo`, `cat`).
                    *   **`switch_mode` (from `docs/advanced-usage/available-tools/switch-mode.md`)**:
                        *   **Purpose**: Enables Roo to change between different operational modes (e.g., Code, Architect, Ask, Debug, Custom) to leverage specialized capabilities for different task phases, maintaining context.
                        *   **Parameters**: `mode_slug` (required string: slug of the target mode), `reason` (optional string: context for the user about the switch).
                        *   **Key Features**: Context continuity across transitions, user approval required for all mode changes, enforces mode-specific tool group and file type restrictions (e.g., Architect mode can only edit `.md` files), adapts tool availability, works with standard and custom modes, applies a 500ms delay after switching to allow changes to take effect. It's an "Always Available Tool".
                        *   **Limitations**: Target mode must exist. Mode preservation for task resumption (returning to a parent task's original mode) is specific to subtasks created by the `new_task` tool, not general `switch_mode` calls.
                        *   **Workflow**: Request Validation (mode exists, params valid) → Mode Transition Preparation (presents for user approval) → Mode Activation (upon approval: updates UI, adjusts tools/prompt, applies delay, enforces restrictions) → Continuation in new mode.
                    *   **`new_task` (from `docs/advanced-usage/available-tools/new-task.md`)**:
                        *   **Purpose**: Creates subtasks with specialized modes, breaking down complex projects. The parent task is paused while the subtask runs, and results are transferred back to the parent upon subtask completion. This is the core mechanism for Boomerang Tasks / Orchestrator Mode functionality.
                        *   **Parameters**: `mode` (required string: slug of the mode for the new subtask, e.g., "code", "ask"), `message` (required string: initial instructions for the new subtask).
                        *   **Key Features**: Creates subtasks with their own isolated conversation history and specified mode; pauses the parent task for later resumption; maintains hierarchical task relationships for UI navigation; transfers results from the completed subtask back to the parent (internally via `finishSubTask()`, using the `attempt_completion` result from the subtask); requires explicit user approval for subtask creation.
                        *   **Limitations**: The specified mode must exist; user approval is needed for each new task creation (unless automated); deeply nested subtasks can become complex to manage; subtasks inherit some workspace/extension configurations from parents; context might need re-establishment when switching between deeply nested tasks; subtask completion needs to be explicitly signaled (e.g., via `attempt_completion`) for the parent task to resume correctly.
                        *   **Workflow**: Parameter Validation (mode exists, message provided) → Task Stack Management (tracks active/paused tasks, preserves parent mode, pauses parent) → Task Context Management (creates new task context with unique IDs, captures telemetry) → Mode Switching and Integration (switches to specified mode, initializes the new task with the provided message) → Subtask Completion and Result Transfer (subtask result via `finishSubTask()` to parent, parent resumes, history/metrics updated, `taskCompleted` event emitted).
            *   **Always Available Tools**: `ask_followup_question`, `attempt_completion`, `switch_mode`, `new_task` are accessible regardless of the current mode.
        *   **Tool Calling Mechanism**:
            *   **Complex Tasks**: For operations like `create_mcp_server` (an internal plan, not a direct tool call), Roo follows predefined internal plans. These plans orchestrate standard, documented tools (like `execute_command`, `write_to_file`, `ask_followup_question`) in sequence. Roo uses an internal `fetch_instructions` tool to retrieve these plans.
            *   **When Tools Are Called**: Based on direct task requirements (LLM decision, user request, automated workflows), mode-based availability, and context-dependent situations (workspace state, system events, error handling).
            *   **Decision Process**: Involves mode validation (e.g., via an internal `isToolAllowedForMode` function), requirement checking (system capability, resource availability, permissions), and parameter validation.
        *   **Technical Implementation**:
            *   **Tool Call Processing**: Involves initialization (validation), execution (represented by a tool_call object with `name`, `input`/arguments, `callId`), and result handling (success/failure, formatting, errors).
            *   **Security and Permissions**: Includes access controls (filesystem, command, network) and validation layers (tool-specific, mode-based, system-level).
        *   **Mode Integration**:
            *   Tool access is mode-dependent (e.g., Code Mode has full file access, Ask Mode is read-only). Custom Modes can have specific tool permissions.
            *   Switching modes updates tool availability and context.
        *   **Best Practices**:
            *   **Efficiency**: Use specific tools, avoid redundancy, batch operations.
            *   **Security**: Validate inputs, use minimum required permissions.
            *   **Error Handling**: Implement proper error checking and graceful failure handling.
        *   **Common Tool Patterns (Sequences)**:
            *   Information Gathering: `ask_followup_question` → `read_file` → `search_files`.
            *   Code Modification: `read_file` → `apply_diff` → `attempt_completion`.
            *   Task Management: `new_task` → `switch_mode` → `execute_command`.
        *   **Error Handling and Recovery**:
            *   **Error Types**: Tool-Specific, System (permissions, resources, network), Context (invalid mode, missing requirements).
            *   **Recovery Strategies**: Automatic (retry, fallback, state restoration) and User Intervention (notifications, suggestions, manual actions).
    *   **Prompt Structure (from `docs/advanced-usage/prompt-structure.md`)**:
        *   **Core Message Types for LLM Communication**:
            *   **System Prompt**: The initial set of instructions defining Roo's capabilities, persona (based on selected mode), operational rules, tool descriptions and guidelines, list of available modes, system information (OS, shell, CWD), and all applicable custom instructions. It's generated dynamically for each interaction.
                *   **Custom System Prompts**: Advanced users can override the default system prompt for a specific mode by creating a `.roo/system-prompt-<mode_slug>` file in their workspace root (see [Footgun Prompting](/features/footgun-prompting)).
            *   **User Messages**: Contain the user's typed query, any included images (for supported models), and automatically appended **Environment Details** (open files/tabs, cursor position, active terminal output, recently modified files, current time, token/cost info, current mode, and an initial file listing upon connection).
            *   **Assistant Messages**: These are the LLM's responses, which can include direct text answers, visible thinking processes (if enabled), and tool calls (requests to use specific tools).
            *   **Tool Messages (API Level)**: Contain the results returned from tool executions. These are sent back to the LLM as input for its next reasoning step, separate from Assistant Messages.
        *   **Message Flow (Simplified)**:
            1.  Initial Setup: Roo generates the System Prompt.
            2.  User Input: User sends a message, which Roo enriches with Environment Details.
            3.  LLM Processing: The LLM receives all previous messages (System, User, Assistant, Tool) plus the new user input.
            4.  Assistant Response: LLM generates a response, possibly including tool calls.
            5.  Tool Execution: If a tool is called, Roo executes it.
            6.  Tool Message: The result of the tool execution is sent back to the LLM.
            7.  Conversation History: All messages are maintained for context.
        *   **Technical Implementation (Internal Components Mentioned)**:
            *   `SYSTEM_PROMPT` function (in `src/core/prompts/system.ts`): Assembles the complete system prompt.
            *   Section Generators: Specialized functions that 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.
            *   `loadSystemPromptFile` function: Checks for and processes custom system prompt override files.
        *   **Support Prompts**:
            *   Specialized, template-based prompts used for specific Code Actions (e.g., "Explain Code", "Improve Code", "Add to Context").
            *   Generated from templates in `src/shared/support-prompt.ts`.
            *   Often operate with an independent context, separate from the main chat history, and are optimized for the specific code task.
        *   **Understanding Benefits**: Knowing this structure helps in writing better prompts, troubleshooting, creating effective custom modes, and using custom system prompts.
    *   **Rate Limits, Token Usage, and Costs (from `docs/advanced-usage/rate-limits-costs.md`)**:
        *   **Rate Limits**:
            *   Configured per [API Configuration Profile](/features/api-configuration-profiles#creating-a-profile).
            *   Default to 0 (disabled) and typically don't need adjustment.
        *   **Token Usage**:
            *   Roo Code interacts with AI models using tokens (pieces of words).
            *   Usage affects processing time and cost.
            *   **Input Tokens**: Tokens in the prompt (system prompt, user instructions, context like `@files`).
            *   **Output Tokens**: Tokens generated by the AI model in its response.
            *   Both input and output token counts are displayed in the chat history for each interaction.
        *   **Cost Calculation**:
            *   Most AI providers charge based on token usage (pricing varies by provider and model).
            *   Roo Code automatically estimates the cost of each API request based on the configured model's pricing and displays this in the chat history.
            *   **Note**: This is an *estimate*; actual costs may vary. Some providers offer free tiers/credits or prompt caching, which can lower costs.
        *   **Tips for Optimizing Token Usage**:
            1.  **Be Concise**: Use clear, concise language in prompts.
            2.  **Provide Only Relevant Context**: Use context mentions (`@file.ts`, `@folder/`) selectively.
            3.  **Break Down Tasks**: Divide large tasks into smaller, focused sub-tasks.
            4.  **Use Custom Instructions**: Guide Roo's behavior to reduce lengthy explanations in each prompt.
            5.  **Choose the Right Model**: Consider smaller, faster models for tasks not requiring the full power of larger models.
            6.  **Use Modes Strategically**: E.g., `Architect` mode for analysis (cannot modify code, potentially avoiding expensive operations).
            7.  **Disable MCP If Not Used**: Disabling MCP features (especially [server creation](/features/mcp/using-mcp-in-roo#enabling-or-disabling-mcp-server-creation)) can significantly reduce system prompt size.

## 7. Supported AI Providers
        2.  **Use Context Mentions Effectively**: Utilize `'path/to/file.ts`' (see below for file content) for specific files, `@problems` for current errors/warnings, and `@commit-hash` for specific Git commits.
        3.  **Break Down Tasks**: Divide large tasks into smaller, more manageable sub-tasks to keep the context focused.
        4.  **Summarize Code**: Instead of including entire large code blocks in prompts, summarize the relevant parts.
        5.  **Prioritize Recent History / Re-include Context**: Be mindful that Roo Code automatically truncates older messages. If important older context is needed, re-include it in your prompts.
        6.  **Use Prompt Caching**: If your API provider supports it (e.g., Anthropic, OpenAI, OpenRouter, Requesty), this feature can cache prompts, reducing cost and latency for future similar requests.
    *   **Example Workflow (Refactoring a Large File)**:
        1.  Start with an overview request (e.g., `'src/components/MyComponent.tsx' (see below for file content) List the functions and classes in this file.`).
        2.  Target specific functions for refactoring (e.g., `'src/components/MyComponent.tsx' (see below for file content) Refactor the processData function to use async/await...`).
        3.  Make small, iterative changes, reviewing and approving each step.

## 7. Supported AI Providers

*   **Anthropic (Claude) (from `docs/providers/anthropic.md`)**
    *   **Website**: [https://www.anthropic.com/](https://www.anthropic.com/)
    *   **API Key Acquisition**: From the [Anthropic Console](https://console.anthropic.com/settings/keys). The API key is shown only once upon creation and must be stored securely.
    *   **Supported Models in Roo Code**:
        *   `claude-3-7-sonnet-20250219` (Recommended for Roo Code)
        *   `claude-3-7-sonnet-20250219:thinking` (Extended Thinking variant)
        *   `claude-3-5-sonnet-20241022`
        *   `claude-3-5-haiku-20241022`
        *   `claude-3-opus-20240229`
        *   `claude-3-haiku-20240307`
    *   **Configuration in Roo Code**: Select "Anthropic" as the API Provider, enter the API key, and choose the desired Claude model. A custom base URL can be optionally configured.
    *   **Key Features/Notes**:
        *   **Prompt Caching**: Claude 3 models support prompt caching, which can reduce costs and latency for repeated prompts.
        *   **Context Window**: Claude models feature large context windows (e.g., 200,000 tokens).
        *   **Pricing**: Refer to [Anthropic Pricing](https://www.anthropic.com/pricing).
        *   **Rate Limits**: Anthropic enforces rate limits based on usage tiers. If issues arise, consider accessing Claude models via OpenRouter or Requesty.
*   **AWS Bedrock (from `docs/providers/bedrock.md`)**
    *   **Website**: [https://aws.amazon.com/bedrock/](https://aws.amazon.com/bedrock/)
    *   **Prerequisites**: Active AWS account, granted access to Amazon Bedrock service, and specific model access requested within Bedrock. AWS CLI should be configured (`aws configure`).
    *   **Credentials**:
        *   **AWS Access Keys (Recommended for Development)**: Create an IAM user with `bedrock:InvokeModel` permission, then generate an Access Key ID and Secret Access Key (and optional Session Token if needed).
        *   **AWS Profile**: Use a named AWS profile configured via AWS CLI or credentials file.
    *   **Supported Models (Examples - use Model ID in Roo Code)**:
        *   Amazon: `amazon.nova-pro-v1:0`, `amazon.titan-text-lite-v1:0`
        *   Anthropic: `anthropic.claude-3-7-sonnet-20250219-v1:0`, `anthropic.claude-3-opus-20240229-v1:0`
        *   DeepSeek: `deepseek.r1-v1:0`
        *   Meta: `meta.llama3-3-70b-instruct-v1:0`, `meta.llama3-70b-instruct-v1:0`
    *   **Configuration in Roo Code**: Select "Bedrock" provider. Choose Authentication Method (AWS Credentials or AWS Profile) and provide necessary details. Select AWS Region. Optionally, enable "Use cross-region inference". Select the desired Model ID.
    *   **Key Features/Notes**: Ensure IAM user/role has `bedrock:InvokeModel` permission. Refer to [Amazon Bedrock pricing](https://aws.amazon.com/bedrock/pricing/). Cross-region inference might increase latency.
*   **Chutes AI (from `docs/providers/chutes.md`)**
    *   **Website**: [https://chutes.ai/](https://chutes.ai/)
    *   **Key Offering**: Provides free API access to a curated set of open-source and proprietary LLMs, potentially with specific capabilities or regional language support.
    *   **API Key Acquisition**: From the Chutes AI platform (account dashboard/settings after sign-up/login).
    *   **Supported Models**: Roo Code attempts to fetch the list of available models dynamically from the Chutes AI API. Users should refer to official Chutes AI documentation or their dashboard for an up-to-date list.
    *   **Configuration in Roo Code**: Select "Chutes AI" as the API Provider, enter the API key, and choose a model from the dynamically fetched list in the dropdown.
*   **DeepSeek (from `docs/providers/deepseek.md`)**
    *   **Website**: [https://platform.deepseek.com/](https://platform.deepseek.com/)
    *   **API Key Acquisition**: From the [DeepSeek Platform API keys page](https://platform.deepseek.com/api_keys). The API key is shown only once upon creation.
    *   **Supported Models in Roo Code**:
        *   `deepseek-chat` (Recommended for coding tasks)
        *   `deepseek-reasoner` (Recommended for reasoning tasks)
    *   **Configuration in Roo Code**: Select "DeepSeek" as the API Provider, enter the API key, and choose the desired model from the dropdown.
    *   **Pricing**: Refer to the [DeepSeek Pricing page](https://api-docs.deepseek.com/quick_start/pricing/).
*   **Google Gemini (from `docs/providers/gemini.md`)**
    *   **Website**: [https://ai.google.dev/](https://ai.google.dev/)
    *   **API Key Acquisition**: From [Google AI Studio](https://ai.google.dev/) after signing in with a Google account.
    *   **Supported Models in Roo Code (Examples)**:
        *   `gemini-2.5-pro-exp-03-25`
        *   `gemini-2.0-flash-001`
        *   `gemini-1.5-pro-002`
        *   (Many other experimental and versioned models are listed in the docs).
    *   **Configuration in Roo Code**: Select "Google Gemini" as the API Provider, enter the API key, and choose the desired Gemini model.
    *   **Key Features/Notes**:
        *   **Prompt Caching**: Available for supported Gemini 2.5 models, but for the direct Google Gemini provider in Roo Code, it is **not enabled by default**. It must be manually checked in the provider settings. This is a temporary workaround due to potential response delays observed with Google's caching mechanism when accessed directly.
        *   **Pricing**: Based on input/output tokens. Refer to the [Gemini pricing page](https://ai.google.dev/pricing).
*   **OpenRouter (from `docs/providers/openrouter.md`)**
    *   **Website**: [https://openrouter.ai/](https://openrouter.ai/)
    *   **Key Offering**: An AI platform providing access to a wide variety of language models from different providers through a single API. This simplifies setup and allows easy experimentation with different models.
    *   **API Key Acquisition**: From the [OpenRouter keys page](https://openrouter.ai/keys) after signing in (Google/GitHub).
    *   **Supported Models**: Roo Code automatically fetches the list of available models. Refer to the [OpenRouter Models page](https://openrouter.ai/models) for the complete list.
    *   **Configuration in Roo Code**:
        1.  Select "OpenRouter" as the API Provider.
        2.  Enter your OpenRouter API key.
        3.  Choose the desired model from the dynamically fetched list.
        4.  Optionally, configure a custom Base URL (most users leave blank).
        5.  Optionally, enable Prompt Caching for supported models (manual activation required for Gemini models via OpenRouter).
    *   **Supported Transforms**: OpenRouter offers an optional "middle-out" message transform to help with prompts exceeding a model's context size, configurable in Roo Code via the "Compress prompts and message chains to the context size" checkbox.
    *   **Tips/Notes**:
        *   **Pricing**: Based on the underlying model's pricing (details on OpenRouter Models page).
        *   **Prompt Caching**: OpenRouter passes caching requests to underlying models that support it. For most models, caching is automatic if supported by the model itself. **Exception**: For Gemini models accessed via OpenRouter, manual activation of the "Enable Prompt Caching" checkbox in Roo Code's OpenRouter provider settings is required due to potential Google caching delays.
*   **OpenAI (Official API) (from `docs/providers/openai.md`)**
    *   **Website**: [https://openai.com/](https://openai.com/)
    *   **API Key Acquisition**: From the [OpenAI Platform API keys page](https://platform.openai.com/api-keys). The API key is shown only once upon creation and must be stored securely.
    *   **Supported Models in Roo Code (Examples)**:
        *   `o3-mini` (medium reasoning effort)
        *   `o3-mini-high` (high reasoning effort)
        *   `o3-mini-low` (low reasoning effort)
        *   `o1`
        *   `o1-preview`
        *   `o1-mini`
        *   `gpt-4.5-preview`
        *   `gpt-4o`
        *   `gpt-4o-mini`
        *   Refer to [OpenAI Models documentation](https://platform.openai.com/docs/models) for the latest list.
    *   **Configuration in Roo Code**:
        1.  Select "OpenAI" as the API Provider.
        2.  Enter your OpenAI API key.
        3.  Choose the desired model from the dropdown.
        4.  Optionally, configure a custom Base URL (most users won't need this).
    *   **Notes**:
        *   **Pricing**: Refer to the [OpenAI Pricing page](https://openai.com/pricing).
        *   **Azure OpenAI Service**: Users wishing to use Azure OpenAI Service should configure it using the "OpenAI Compatible" provider type in Roo Code, not this direct OpenAI provider.
*   **Glama (from `docs/providers/glama.md`)**
    *   **Website**: [https://glama.ai/](https://glama.ai/)
    *   **Key Offering**: Provides unified API access to a variety of language models (e.g., from Anthropic, OpenAI, and others), featuring prompt caching and cost tracking.
    *   **API Key Acquisition**: From the [Glama API Keys page](https://glama.ai/settings/gateway/api-keys) after signing up/logging in.
    *   **Supported Models**: Roo Code attempts to fetch the list of available models dynamically from the Glama API. Commonly available models include Anthropic Claude models (e.g., `anthropic/claude-3-5-sonnet`, generally recommended for Roo Code) and OpenAI models (e.g., `openai/o3-mini-high`). Users should refer to [Glama model documentation](https://glama.ai/models) for an up-to-date list.
    *   **Configuration in Roo Code**: Select "Glama" as the API Provider, enter the API key, and choose a model from the dynamically fetched list in the dropdown.
    *   **Tips/Notes**:
        *   **Pricing**: Operates on a pay-per-use basis, with pricing varying by the chosen model.
        *   **Prompt Caching**: Supported by Glama, which can reduce costs and improve performance for repeated prompts.
*   **OpenAI Compatible (Provider Type) (from `docs/providers/openai-compatible.md`)**
    *   **Purpose**: Allows Roo Code to connect to a wide range of AI model providers that offer APIs compatible with the OpenAI API standard. This includes local model servers (like Ollama, LM Studio) and various cloud providers (e.g., Perplexity AI, Together AI, Anyscale), distinct from the official OpenAI API.
    *   **General Configuration in Roo Code**:
        1.  Select "OpenAI Compatible" as the API Provider.
        2.  **Base URL**: Enter the API endpoint URL of the chosen compatible provider (this is crucial and will *not* be the official OpenAI URL).
        3.  **API Key**: Enter the API key obtained from the chosen compatible provider.
        4.  **Model ID**: Enter the model name/ID as recognized by the chosen compatible provider.
        5.  **Model Configuration (Advanced)**: Optionally, customize settings like Max Output Tokens, Context Window, Image Support, Computer Use capability, and Input/Output Prices for the selected model via this provider type.
    *   **Supported Models**: While this provider type is generic, if connecting to an endpoint that mirrors the official OpenAI API, Roo Code recognizes specific model IDs like `o3-mini`, `gpt-4o`, etc. (from `openAiNativeModels` in Roo's source). For other compatible providers, available model IDs will vary; always consult the specific provider's documentation.
    *   **Troubleshooting**: Common issues include invalid API keys, incorrect model IDs for the provider, wrong Base URL, or provider accessibility problems.
*   **Mistral AI (from `docs/providers/mistral.md`)**
    *   **Website**: [https://mistral.ai/](https://mistral.ai/)
    *   **API Key Acquisition**: From the [Mistral Platform](https://console.mistral.ai/). Separate keys/pages may exist for general models ([La Plateforme API Key](https://console.mistral.ai/api-keys/)) and Codestral models ([Codestral API Key](https://console.mistral.ai/codestral)).
    *   **Supported Models in Roo Code (Examples & Features)**:
        *   `codestral-latest` (Default Temp: 0.3, Function Calling: ✅, Vision: ❌) - Specialized for code generation.
        *   `mistral-large-latest` (Default Temp: 0.7, FC: ✅, Vision: ❌)
        *   `ministral-8b-latest` (Default Temp: 0.3, FC: ✅, Vision: ❌) - *Note: 'ministral' name as per docs.*
        *   `ministral-3b-latest` (Default Temp: 0.3, FC: ✅, Vision: ❌) - *Note: 'ministral' name as per docs.*
        *   `mistral-small-latest` (Default Temp: 0.3, FC: ✅, Vision: ❌)
        *   `pixtral-large-latest` (Default Temp: 0.7, FC: ✅, Vision: ✅)
        *   Roo Code's default temperature is 0.0; experimentation with model-specific defaults is encouraged.
    *   **Configuration in Roo Code**:
        1.  Select "Mistral" as the API Provider.
        2.  Enter the appropriate Mistral API key.
        3.  Select the desired model.
    *   **Using Codestral**:
        *   Select "Mistral" provider and a Codestral model.
        *   Enter either a Codestral-specific API key or a La Plateforme API key.
        *   If using a La Plateforme API key for Codestral, the **Codestral Base Url** setting in Roo Code must be changed to `https://api.mistral.ai` (default is `codestral.mistral.ai`).
    *   **Documentation**: Refer to [Mistral API Docs](https://docs.mistral.ai/api/) and [Model Overview](https://docs.mistral.ai/getting-started/models/models_overview/).
*   **LiteLLM (from `docs/providers/litellm.md`)**
    *   **Website**: [https://litellm.ai/](https://litellm.ai/) (Docs: [https://docs.litellm.ai/](https://docs.litellm.ai/))
    *   **Key Offering**: A versatile tool providing a unified OpenAI-compatible API to over 100 LLMs (from OpenAI, Anthropic, Cohere, HuggingFace, etc.). Requires the user to set up and run their own LiteLLM server locally. This server then proxies requests to the configured underlying model providers. Offers centralized credential management and cost tracking features.
    *   **Setup**: Users must install and configure their LiteLLM server with desired models and the API keys for those downstream providers. The server typically runs on `http://localhost:4000`.
    *   **Configuration in Roo Code**:
        1.  Select "LiteLLM" as the API Provider.
        2.  Enter the Base URL of the user's LiteLLM server (defaults to `http://localhost:4000`).
        3.  Optionally, enter an API Key if the LiteLLM server itself is configured to require one (Roo uses "dummy-key" if blank).
        4.  Select a model from the list dynamically fetched by Roo Code from the LiteLLM server's `${baseUrl}/v1/model/info` endpoint. If no model is selected, Roo defaults to `anthropic/claude-3-7-sonnet-20250219` (`litellmDefaultModelId`).
    *   **Model Information Handling**: Roo Code interprets model properties (like `maxTokens`, `contextWindow`, `supportsImages`, `supportsPromptCache`, pricing) from the LiteLLM server's `/v1/model/info` response, using defaults if specific values are not provided by LiteLLM. The `supportsComputerUse` flag is determined based on an internal Roo Code list of Anthropic model IDs (`COMPUTER_USE_MODELS`) if the underlying model ID matches.
    *   **Notes**: The primary configuration of models and downstream API keys is managed on the user's LiteLLM server. Model availability in Roo Code depends on what the LiteLLM server exposes. Ensure the LiteLLM server is network accessible.
*   **Groq (from `docs/providers/groq.md`)**
    *   **Website**: [https://groq.com/](https://groq.com/)
    *   **Key Offering**: Specializes in very high-speed inference for Large Language Models (LLMs), utilizing their custom-built Language Processing Units (LPUs).
    *   **API Key Acquisition**: From the [GroqCloud Console](https://console.groq.com/) (API Keys section after sign-up/login).
    *   **Supported Models**: Roo Code attempts to fetch the list of available models dynamically from the Groq API. Common models available include:
        *   `llama3-8b-8192`
        *   `llama3-70b-8192`
        *   `mixtral-8x7b-32768`
        *   `gemma-7b-it`
        *   Users should refer to [Groq Model Documentation](https://console.groq.com/docs/models) for an up-to-date list.
    *   **Configuration in Roo Code**: Select "Groq" as the API Provider, enter the API key, and choose a model from the dynamically fetched list in the dropdown.
*   **Requesty (from `docs/providers/requesty.md`)**
    *   **Website**: [https://www.requesty.ai/](https://www.requesty.ai/)
    *   **Key Offering**: Provides an easy and optimized API for interacting with 150+ Large Language Models (LLMs). Features include in-flight cost optimizations, unified and simplified billing (with automatic balance top-ups), cost tracking (via dashboard and a separate Requesty VS Code extension), usage statistics, LLM interaction logs, and fallback policies for provider outages.
    *   **API Key Acquisition**: From the [API Management page](https://app.requesty.ai/manage-api) on the Requesty dashboard.
    *   **Supported Models**: Roo Code automatically fetches the latest list of available models. The full list can be viewed on the [Requesty Model List page](https://app.requesty.ai/router/list).
    *   **Configuration in Roo Code**:
        1.  Select "Requesty" as the API Provider.
        2.  Enter your Requesty API key.
        3.  Choose the desired model from the dynamically fetched list.
    *   **Tips/Notes**:
        *   **Prompt Caching**: Supported for some underlying models (searchable on the Requesty model list).
        *   **Relevant Resources**: [Requesty YouTube channel](https://www.youtube.com/@requestyAI), [Requesty Discord](https://requesty.ai/discord).
*   **GCP Vertex AI (from `docs/providers/vertex.md`)**
    *   **Website**: [https://cloud.google.com/vertex-ai](https://cloud.google.com/vertex-ai)
    *   **Key Offering**: Google Cloud Platform's managed machine learning platform, providing access to various foundation models, including Google Gemini and Anthropic Claude families.
    *   **Prerequisites**:
        *   Active Google Cloud Platform (GCP) account.
        *   A GCP project with the Vertex AI API enabled.
        *   Access granted to the specific models on Vertex AI you intend to use.
        *   Authentication configured:
            *   **Application Default Credentials (ADC) (Recommended)**: Set up using `gcloud auth application-default login` via the Google Cloud CLI.
            *   **Service Account Key (Alternative)**: A JSON key file generated from your GCP project.
    *   **Supported Models (Examples via Vertex AI)**:
        *   Google Gemini Models: `gemini-2.0-flash-001`, `gemini-2.5-pro-exp-03-25`.
        *   Anthropic Claude Models: `claude-3-7-sonnet@20250219`, `claude-3-opus@20240229` (note the `@version` or `vX:Y` format for some model IDs on Vertex AI).
    *   **Configuration in Roo Code**:
        1.  Select "GCP Vertex AI" as the API Provider.
        2.  **Authentication**: If ADC is configured, no further action is needed in Roo settings. Otherwise, either paste the content of your Service Account JSON key file into the "Google Cloud Credentials" field or provide the absolute path to the key file in the "Google Cloud Key File Path" field.
        3.  Enter your GCP Project ID.
        4.  Select the GCP Region where your Vertex AI resources are located (e.g., `us-east5`).
        5.  Choose the desired model from the dropdown.
    *   **Tips/Notes**: Ensure your GCP account has necessary permissions for Vertex AI and the specific models. Refer to [Vertex AI pricing](https://cloud.google.com/vertex-ai/pricing).
*   **Unbound (from `docs/providers/unbound.md`)**
    *   **Website**: [https://getunbound.ai/](https://getunbound.ai/)
    *   **Key Offering**: A platform focusing on secure and reliable gateway access to a variety of LLMs (e.g., from Anthropic, OpenAI). It emphasizes security and compliance features, making it suitable for enterprise use.
    *   **API Key Acquisition**:
        1.  Sign up/Sign in at the [Unbound gateway](https://gateway.getunbound.ai).
        2.  Create an "Application" on the [Applications page](https://gateway.getunbound.ai/ai-gateway-applications).
        3.  Copy the API key generated for this Unbound Application.
    *   **Supported Models**: Users configure a list of supported models within their Unbound Application settings. Roo Code then automatically fetches this list from the Unbound API.
    *   **Configuration in Roo Code**:
        1.  Select "Unbound" as the API Provider.
        2.  Enter the Unbound Application API key.
        3.  Choose a model from the dynamically fetched list (models configured in the user's Unbound Application).
        *   **Tips/Notes**: Unbound's strong security focus makes it a good option for enterprises with strict AI usage requirements.
*   **xAI (Grok) (from `docs/providers/xai.md`)**
    *   **Website**: [https://x.ai/](https://x.ai/)
    *   **API Key Acquisition**: From the [xAI Console](https://console.x.ai/) (API keys section). The API key is shown only once upon creation.
    *   **Supported Models in Roo Code (Examples)**:
        *   **Grok-3 Models (131K context)**: `grok-3-beta` (Default), `grok-3-fast-beta`, `grok-3-mini-beta` (Reasoning), `grok-3-mini-fast-beta` (Reasoning).
        *   **Grok-2 Models (131K context)**: `grok-2-latest`, `grok-2`, `grok-2-1212`.
        *   **Grok Vision Models**: `grok-2-vision-latest` (32K context, Image Support), `grok-2-vision` (32K, Image), `grok-2-vision-1212` (32K, Image), `grok-vision-beta` (8K, Image).
        *   **Legacy**: `grok-beta` (131K context).
    *   **Configuration in Roo Code**: Select "xAI" as the API Provider, enter your xAI API key, and choose the desired Grok model.
    *   **Reasoning Capabilities (Grok 3 Mini models only)**:
        *   Supported by: `grok-3-mini-beta`, `grok-3-mini-fast-beta`.
        *   NOT supported by: `grok-3-beta`, `grok-3-fast-beta`.
        *   Controlled by `reasoning_effort` parameter (`low` or `high`).
        *   Features: Step-by-step problem solving, math/quantitative strength, reasoning trace access via `reasoning_content` field in response.
    *   **Tips/Notes**: Most Grok models feature large context windows (up to 131K tokens). Vision models support image input. Pricing varies. "Fast" variants are quicker but may cost more; "mini" variants are more economical but may have reduced capabilities.
*   **Ollama (from `docs/providers/ollama.md`)**
    *   **Website**: [https://ollama.com/](https://ollama.com/)
    *   **Key Offering**: A tool for running Large Language Models (LLMs) locally, providing privacy, offline access, and potentially lower costs. Requires user setup and a powerful computer.
    *   **Setup**:
        1.  Download and install Ollama. Ensure the Ollama server is running (command: `ollama serve`).
        2.  Download a model using `ollama pull <model_name>` (e.g., `codellama:7b-code`, `qwen2.5-coder:32b`).
        3.  **Crucially, configure the model's context window size**: Ollama's default (2048 tokens) is too small for Roo Code. Roo needs at least 12k, ideally 32k tokens.
            *   Run the base model: `ollama run <base_model_name>`
            *   Inside Ollama's interactive prompt, set the context size: `/set parameter num_ctx 32768` (or desired size).
            *   Save this configured model with a new name: `/save your_custom_model_name`.
    *   **Configuration in Roo Code**:
        1.  Select "ollama" as the API Provider.
        2.  Enter the *new model name* (e.g., `your_custom_model_name`) created in the Ollama setup step.
        3.  Optionally, configure the Base URL if your Ollama server is not running on the default `http://localhost:11434`.
        4.  Optionally, configure the Model context size in Roo Code's Advanced settings so Roo knows how to manage its sliding window for this model.
    *   **Tips/Notes**: Running local models is resource-intensive. Experiment with different models. Once a model is downloaded and configured, it can be used offline with Roo Code. Refer to [Ollama documentation](https://ollama.com/docs) for more details.
*   **LM Studio (from `docs/providers/lmstudio.md`)**
    *   **Website**: [https://lmstudio.ai/](https://lmstudio.ai/)
    *   **Key Offering**: A user-friendly desktop application for downloading, configuring, and running local language models. It includes a built-in local inference server that emulates the OpenAI API, making it easy to integrate with Roo Code for local model usage.
    *   **Setup**:
        1.  Download and install the LM Studio application.
        2.  Use the LM Studio interface to download a model (GGUF format is recommended, e.g., CodeLlama, Mistral, DeepSeek Coder models).
        3.  In LM Studio, go to the "Local Server" tab, select the downloaded model, and click "Start Server".
    *   **Configuration in Roo Code**:
        1.  Select "LM Studio" as the API Provider.
        2.  Enter the *filename* of the model loaded in LM Studio (e.g., `codellama-7b.Q4_0.gguf`) as the "Model ID". This can be found in LM Studio's "Local Server" tab.
        3.  Optionally, provide the Base URL if LM Studio's server is not running on the default `http://localhost:1234`.
    *   **Tips/Notes**: Running LLMs locally can be resource-intensive. Ensure the LM Studio local server is running for Roo Code to connect. Refer to [LM Studio documentation](https://lmstudio.ai/docs) for more details. If encountering errors like "Please check the LM Studio developer logs...", context length settings in LM Studio might need adjustment.
*   **VS Code Language Model API (Experimental) (from `docs/providers/vscode-lm.md`)**
    *   **Purpose**: Allows Roo Code to use models provided by other VS Code extensions (e.g., GitHub Copilot) that implement the native VS Code Language Model API.
    *   **Prerequisites**: VS Code (not Cursor); an installed and enabled language model provider extension (e.g., GitHub Copilot and GitHub Copilot Chat).
    *   **Configuration in Roo Code**:
        1.  Select "VS Code LM API" as the API Provider.
        2.  Select the desired model from the dropdown (model IDs are typically in `vendor/family` format, e.g., `copilot - claude-3.5-sonnet`).
    *   **Limitations**: This integration is highly experimental and depends on the stability and correct implementation of the VS Code Language Model API by other extensions. May not support all features of direct API providers (e.g., image input, streaming, detailed usage info). Cost control is subject to the provider extension's terms. GitHub Copilot rate limits apply if using Copilot models.
    *   **Troubleshooting**: If no models appear, ensure VS Code and the provider extension are installed/enabled. For Copilot, try sending a Copilot Chat message with the desired model first.
*   **Human Relay (from `docs/providers/human-relay.md`)**
    *   **Purpose**: Allows using web-based AI models (e.g., ChatGPT, Claude web UI) with Roo Code without needing an API key. It relies on the user to manually relay messages between Roo Code and the AI's web interface.
    *   **How it Works**:
        1.  Select "Human Relay" as the API provider in Roo Code settings (no API key required).
        2.  Initiate a request in Roo Code.
        3.  A dialog box appears in VS Code; Roo's message to the AI is automatically copied to the clipboard.
        4.  User pastes this message into the web interface of their chosen AI (e.g., chat.openai.com, claude.ai).
        5.  User copies the AI's complete response from the web.
        6.  User pastes the AI's response back into the VS Code dialog and confirms.
        7.  Roo Code processes the response.
    *   **Use Cases**: Useful for models without direct API access, if preferring not to manage API keys, or to leverage specific capabilities/context available only in certain web UIs.
    *   **Limitations**: Requires constant manual copy-pasting, significantly slower interaction than direct API integration, and potential for errors or omissions during manual transfer.
*   OpenAI
*   OpenRouter
*   AWS Bedrock
*   GCP Vertex AI
*   Ollama
*   LM Studio
*   DeepSeek
*   Mistral
*   Unbound
*   Requesty
*   VS Code Language Model API
*   (Detailed information for each provider from `docs/providers/` directory, OpenRouter, Requesty, Anthropic, OpenAI details added from `connecting-api-provider.md`)

## 7.1. FAQ Summary (from `docs/faq.md`)

The FAQ provides a broad overview of Roo Code, reiterating many concepts detailed elsewhere in this document and offering quick answers to common user questions.

*   **General Understanding**:
    *   **What Roo Code Is**: An AI-powered autonomous coding agent for your editor. (See Section 1)
    *   **How It Works**: Uses LLMs, interacts via chat, proposes actions (file operations, command execution, web browsing, MCP tool use) for user approval. (See Section 2)
    *   **Capabilities**: Code generation, refactoring, bug fixing, documentation, code explanation, Q&A, task automation, file/project creation. (See Section 5.1)
    *   **Cost**: The Roo Code extension is free and open-source, but relies on external API providers which typically charge for usage. Users need their own API keys. (See Section 7 for provider details)
    *   **Risks**: Roo Code can make mistakes (always review changes), execute commands (use auto-approval cautiously), and access the internet (if enabled).
*   **Setup & Installation**:
    *   **Installation**: Refer to the [Installation Guide](/getting-started/installing). (See Section 3.2)
    *   **Supported API Providers**: A comprehensive list is provided, including Anthropic, OpenAI, OpenRouter, Google Gemini, local model solutions like Ollama and LM Studio, and others. (See Section 7 for full list and details)
    *   **API Keys**: Users must obtain API keys from their chosen provider. (See Section 3.3 and individual provider details in Section 7)
    *   **Local Models**: Supported via Ollama and LM Studio. (See Section 6.2 and provider details in Section 7)
*   **Usage**:
    *   **Starting Tasks**: Type tasks in natural language in the Roo Code panel. (See Section 3.4)
    *   **Modes**: Roo Code uses different personas (Code, Architect, Ask, Debug, etc.) for specialized tasks. Custom modes can be created. (See Section 4.3 and 5.2)
    *   **Tools**: Roo Code automatically selects and uses tools to interact with the system, requiring user approval. (See Section 4.4)
    *   **Context Mentions**: Use `@` to provide specific context like files or problems. (See Section 4.5)
    *   **Internet & Terminal Access**: Possible with user approval and appropriate provider/model capabilities. (See Section 5.5 for Browser, Section 5.3 for Shell Integration)
    *   **Customization**: Through Custom Instructions, Custom Modes, `.roorules` files, and various settings. (See Section 5.2, 5.3, and FAQ mentions `.roorules`)
    *   **Auto-Approval**: Settings exist to auto-approve certain actions. (See Section 5.4)
*   **Advanced Features**:
    *   **Offline Use**: Possible with local models. (See Section 6.2)
    *   **MCP (Model Context Protocol)**: Extends Roo Code with custom tools and resources via external servers. Users can create their own MCP servers. (See Section 5.5)
*   **Troubleshooting**:
    *   **Common Issues**: Roo not responding (check API key, internet, provider status), error messages.
    *   **Undoing Changes**: Standard editor undo (Ctrl/Cmd+Z). Experimental [Checkpoints](/features/checkpoints) feature can also revert file changes. (See Section 5.10)
    *   **Reporting Bugs/Features**: Use the Roo Code GitHub Issues page or Discussions. (See Section 10)

This summary highlights key points from the FAQ. For detailed information on any topic, please refer to the respective sections linked or detailed throughout this document.

## 8. Tips & Tricks (from `docs/tips-and-tricks.md`)

This section provides a collection of quick tips to enhance the Roo Code experience:

*   **UI & Interaction**:
    *   Drag the Roo Code panel to VS Code's Secondary Sidebar for better visibility alongside Explorer, Search, etc.
    *   Drag files (single, or multiple holding Shift) from the Explorer into the Roo chat window to add their content as context.
    *   Set up a keyboard shortcut for the `roo.acceptInput` command for faster interactions (accepting suggestions, submitting input).
*   **Performance, Cost, and Context Management**:
    *   If not using [MCP](/features/mcp/overview), turn it off in the <Codicon name="server" /> MCP Servers tab to significantly reduce system prompt size and token costs.
    *   Be thoughtful about `Max Tokens` / `Max Thinking Tokens` settings. Use high values sparingly (e.g., for Architect, Debug modes) and keep Code mode lower (e.g., ≤ 16k max tokens) to preserve conversation history space.
    *   To recover from `input length and max tokens exceed context limit` errors:
        1.  Delete a message from the chat history.
        2.  Roll back to a previous [checkpoint](/features/checkpoints).
        3.  Temporarily switch to an AI model with a larger context window (e.g., Gemini), if available.
    *   Adjust the `File read auto-truncate threshold` setting (in Advanced Settings) to manage how large files are read, balancing performance and context needs.
*   **Custom Mode Usage**:
    *   To keep [custom modes](/features/custom-modes) focused, limit the types of files they are allowed to edit.
    *   To create a new custom mode based on a real-world role, try asking Code mode: `Create a custom mode based on the job posting at @[url_of_job_posting]`.
*   **Workflow Optimization & Acceleration**:
    *   For intensive tasks, consider checking out multiple copies of your repository and running Roo Code instances in parallel, using Git to resolve any conflicts.
    *   When using Debug mode, start a new task specifically for the debugging session (e.g., "start a new task in Debug mode with all of the necessary context needed to figure out X") to isolate its context window and prevent polluting the main task's context.
    *   Utilize **Sticky Models**: Assign specialized AI models to different modes (e.g., a reasoning model for planning, a coding-focused model for implementation). Roo Code will automatically switch to the mode's last-used model.
*   **Community Contribution**: Users can add their own tips by clicking the "Edit this page" link on the source documentation page.

## 9. Troubleshooting

*   **Installation Issues (from `docs/getting-started/installing.mdx`):**
    *   **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").
    *   **General 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.
*   Common issues and solutions (e.g., Roo not responding, error messages, unwanted changes)
    *   (Details from `docs/faq.md`)

## 10. Community & Resources (from `docs/index.md`)

*   **Documentation Links:**
    *   [Basic Usage Guide](/basic-usage/the-chat-interface)
    *   [Advanced Features](/features/auto-approving-actions)
    *   [Frequently Asked Questions](/faq)
*   **Community & Socials:**
    *   **Discord:** [Join our Discord server](https://discord.gg/roocode) for real-time help and discussions.
    *   **Reddit:** [Visit our subreddit](https://www.reddit.com/r/RooCode) to share experiences and tips.
    *   **GitHub:** Report [issues](https://github.com/RooVetGit/Roo-Code/issues) or request [features](https://github.com/RooVetGit/Roo-Code/discussions/categories/feature-requests?discussions_q=is%3Aopen+category%3A%22Feature+Requests%22+sort%3Atop). (Also a support channel for installation)
    *   **X (Twitter):** [Follow @roo_code](https://x.com/roo_code).
    *   **Bluesky:** [Follow roocode.bsky.social](https://bsky.app/profile/roocode.bsky.social).
    *   **LinkedIn:** [Follow Roo Code](https://www.linkedin.com/company/roo-code).
*   **Tutorial Videos (from `docs/tutorial-videos.json` and `docs/tutorial-videos.mdx`)**:
    *   The `docs/tutorial-videos.mdx` page serves as the display page for tutorial videos, utilizing a `<VideoGrid />` component (likely defined in `@site/src/components/VideoGrid`) to render the video information.
    *   The actual data for the videos (IDs, titles) is sourced from `docs/tutorial-videos.json`.
    *   Listed Videos (from JSON):
        *   **Title**: "Custom Modes in Roo Code | Official Tutorial "
            *   **YouTube ID**: `qgqceCuhlRA`
            *   **URL**: [https://www.youtube.com/watch?v=qgqceCuhlRA](https://www.youtube.com/watch?v=qgqceCuhlRA)
        *   **Title**: "Installing Roo Code in VS Code"
            *   **YouTube ID**: `Mcq3r1EPZ-4`
            *   **URL**: [https://www.youtube.com/watch?v=Mcq3r1EPZ-4](https://www.youtube.com/watch?v=Mcq3r1EPZ-4) (Already linked in Installation section)
        *   **Title**: "Setting up MCP server in Roo"
            *   **YouTube ID**: `QDy3dm1xJ6Y`
            *   **URL**: [https://www.youtube.com/watch?v=QDy3dm1xJ6Y](https://www.youtube.com/watch?v=QDy3dm1xJ6Y)
*   **Community Projects & Contributions (from `docs/community/index.md`)**:
    *   The community section highlights various projects and custom modes developed by users to extend Roo Code's capabilities.
    *   **Key Community Projects Include**:
        *   **SPARC (from `docs/community/sparc.md`)**:
            *   **Author**: ruvnet
            *   **GitHub**: [https://github.com/ruvnet/rUv-dev](https://github.com/ruvnet/rUv-dev) (NPM: `create-sparc`)
            *   **Core Idea**: Orchestrates "set and forget" agentic development workflows using a structured framework and Roo Code Boomerang Tasks. Aims to automate complex code development while maintaining developer control.
            *   **Key Features**:
                *   **Scaffolding**: `npx create-sparc init` generates project structures, configurations, and boilerplate.
                *   **Prompting Templates**: Optimized for consistent, high-quality code generation.
                *   **SPARC Boomerang Mode**: A continuous feedback loop (define requirements → generate → review → refine).
                *   **Boomerang Tasks Usage**: Leverages Roo Code's Boomerang Tasks for focused problem-solving.
                *   **Workflow Orchestration**: Coordinates complex sequences with task chains and dependency management.
                *   **MCP Services Integration**: Extends Roo's capabilities.
                *   **SPARC Mode Management**: Context-aware settings to optimize Roo Code behavior for different development phases.
            *   **Quick Start**: Initialize with `npx create-sparc init`.
        *   **Memory Bank Project (from `docs/community/memory-bank.md`)**:
            *   **Author**: GreatScottyMac
            *   **GitHub**: [https://github.com/GreatScottyMac/roo-code-memory-bank](https://github.com/GreatScottyMac/roo-code-memory-bank)
            *   **Problem Solved**: Maintaining context across Roo Code sessions.
            *   **Core Idea**: Provides a structured memory system integrated with VS Code.
            *   **Key Features**:
                *   Persistent Context: Remembers project details across sessions.
                *   Smart Workflows: Mode-based operation, automatic context switching, project-specific customization.
                *   Knowledge Management: Structured documentation, technical decision tracking, automated progress monitoring.
        *   **Roo Code Tips & Tricks (Community Project) (from `docs/community/tips-and-tricks.md`)**:
            *   **Author**: Michaelzag
            *   **GitHub**: [https://github.com/Michaelzag/RooCode-Tips-Tricks](https://github.com/Michaelzag/RooCode-Tips-Tricks)
            *   **Core Idea**: A collection of files designed to supercharge the Roo Code experience and maximize productivity.
            *   **Highlighted Feature - Handoff System**:
                *   A simple yet powerful way to maintain optimal LLM performance during extended projects.
                *   Automatically creates valuable documentation as part of its process.
                *   More details: [Handoff System on GitHub](https://github.com/Michaelzag/RooCode-Tips-Tricks/blob/main/handoffs/handoff-system.md).
        *   **Roo Code Dynamic Rules**: By cannuri, allows on-the-fly rule definition for `.clinerules` via chat commands (`RULE:`, `NORULE:`). (GitHub: [cannuri/roo-code-dynamic-rules](https://github.com/cannuri/roo-code-dynamic-rules)).
        *   **Roo Commander Project (from `docs/community/roo-commander.md`)**:
            *   **Author**: jezweb
            *   **GitHub**: [https://github.com/jezweb/roo-commander](https://github.com/jezweb/roo-commander)
            *   **Core Idea**: A sophisticated collection of custom Roo Code modes designed to manage software development projects using a structured, multi-agent (virtual team) approach.
            *   **Orchestration**: Introduces a central "👑 Roo Commander" mode to orchestrate these specialized roles.
            *   **Key Features**: Leverages specialized roles (custom modes) and a structured project journal for enhanced context management and workflow organization.
        *   **Maestro Project (from `docs/community/maestro.md`)**:
            *   **Author**: shariqriazz
            *   **GitHub**: [https://github.com/shariqriazz/maestro](https://github.com/shariqriazz/maestro)
            *   **Core Idea**: A comprehensive system of over 30 highly specialized Roo modes functioning as an integrated development team.
            *   **Orchestration**: A central `Maestro Mode (Maestro Project)` analyzes requests, decomposes tasks, and delegates to specialized modes (e.g., `Visionary Mode` for architecture, `ReactMaster Mode` for React, `SqlMaster Mode` for SQL).
            *   **Features**: Structured workflow, defined protocols for delegation and collaboration, different `Interaction Modes (Maestro Project)` (e.g., `YOLO MVP`, `Follow Production`) to control autonomy, and an extensible design.
            *   **Prerequisites**: Relies on its own [Maestro Mode Repository](https://github.com/shariqriazz/maestro) and potentially the [Vertex AI MCP Server by shariqriazz](https://github.com/shariqriazz/vertex-ai-mcp-server) for full functionality of certain modes (like a Researcher mode).
            *   **Goal**: Enhance development consistency, quality, and coverage.
    *   **Custom Modes Gallery**:
        *   A showcase of custom modes shared by the community. Users can also contribute their own.
        *   Examples include:
            *   **Jest Test Engineer (Custom Mode) (from `docs/community/custom-modes/jest-test-engineer.md`)**:
                *   **Author**: @mrubens.
                *   **Purpose**: A specialized mode for writing and maintaining Jest test suites with TypeScript support.
                *   **Focus**: TDD practices, test organization, TypeScript-aware test writing, mocking, code coverage, and test performance.
                *   **Tool Access**: `read`, `browser`, `command`, and `edit` restricted to test-related files (e.g., `__tests__/`, `__mocks__/`, `*.test.ts`, `jest.config.js`).
                *   **Custom Instructions**: Emphasize clear test structure (describe/it), meaningful descriptions, test isolation (beforeEach/afterEach), error case handling, JSDoc for complex scenarios, typed mocks, and verification of positive/negative cases.
            *   **ResearchMode (Custom Mode) (from `docs/community/custom-modes/research-mode.md`)**:
                *   **Author**: @JamesCherished.
                *   **Project GitHub**: [James-Cherished-Inc/roo-research-mode](https://github.com/James-Cherished-Inc/roo-research-mode).
                *   **Purpose**: Integrates Perplexity API (via a local MCP server or CLI script `node ./index.js`) for web search and Lynx (text-based browser via CLI) for page analysis, enabling autonomous research-augmented software engineering.
                *   **Workflow**: Involves defining research goals, using Perplexity for search, Lynx for deep page analysis and code extraction, meticulously documenting research influences (in code comments with source URLs, `research-log.md`, and `technical_decisions.md`), and validating/integrating findings.
                *   **Tool Access**: Full (`read`, `edit`, `command`, `browser`, `mcp`).
                *   **Note**: The mode is designed to check if its research capabilities (Perplexity MCP server, Lynx) are set up in the workspace and implement them if not.
            *   **VibeMode (Custom Mode) (from `docs/community/custom-modes/vibe-mode.md`)**:
                *   **Author**: @richardwhiteii.
                *   **Purpose**: Transforms natural language descriptions into working code, embracing an intuitive and flow-based development philosophy ("vibe coding").
                *   **Focus**: Understanding user intent over technical specifics, ensuring functionality through continuous testing, rapid iteration, and autonomous error resolution when possible. Supports voice-to-text via SuperWhisper integration and emphasizes Test-Driven Development.
                *   **Tool Access**: Full (`read`, `edit`, `browser`, `command`, `mcp`).
                *   **Custom Instructions**: Prioritize working solutions, maintain a conversational tone, suggest improvements without breaking flow, document key decisions, and can switch to Architect, Ask, or Code modes as needed.
            *   **Documentation Writer (Custom Mode) (from `docs/community/custom-modes/documentation-writer.md`)**:
                *   **Author**: jsonify.
                *   **Purpose**: A specialized technical documentation expert.
                *   **Focus**: Creating clear, concise, and maintainable documentation (READMEs, API docs, user guides), adhering to best practices and consistent style guidelines. Emphasizes effective Markdown usage and logical organization.
                *   **Tool Access**: `read`, `edit`, `command`.
            *   **Junior Developer Code Reviewer (Custom Mode) (from `docs/community/custom-modes/junior-developer-code-reviewer.md`)**:
                *   **Author**: jsonify.
                *   **Purpose**: A supportive mentor-reviewer providing educational, encouraging code reviews focused on junior developers' growth.
                *   **Focus**: Educational feedback, positive reinforcement, fundamental best practices, clear examples, and structured learning. Aims to explain the 'why' behind suggestions.
                *   **Tool Access**: `read`, `command`, and `edit` restricted to Markdown files (`.md`) only (likely for writing review comments).
            *   **Senior Developer Code Reviewer (Custom Mode) (from `docs/community/custom-modes/senior-developer-code-reviewer.md`)**:
                *   **Author**: jsonify.
                *   **Purpose**: A technical architect persona for conducting high-level code reviews.
                *   **Focus**: Architectural impact, system scalability, security vulnerabilities, performance optimizations, long-term maintainability, error handling, edge cases, and strategic improvements/trade-offs.
                *   **Tool Access**: `read`, `command`, and `edit` restricted to Markdown files (`.md`) only.
            *   **User Story Creator (Custom Mode) (from `docs/community/custom-modes/user-story-creator.md`)**:
                *   **Author**: jsonify.
                *   **Purpose**: An agile requirements specialist focused on creating clear, valuable user stories.
                *   **Focus**: Crafting well-structured user stories (Title, As a..., I want to..., So that..., Acceptance Criteria), breaking down complex requirements, identifying acceptance criteria/edge cases, and ensuring stories deliver business value. Considers various story types (Functional, Non-functional, Epic Breakdown, Technical) and edge cases.
                *   **Tool Access**: `read`, `edit`, `command`.
            *   **Orchestrator (Custom Mode by mrubens) (from `docs/community/custom-modes/orchestrator.md`)**:
                *   **Author**: @mrubens.
                *   **Purpose**: A strategic workflow orchestrator that delegates subtasks to other specialized modes and reasons about results and next steps.
                *   **File Editing**: Restricted to creating/updating custom mode definitions (e.g., `.roomodes`, `custom_modes.json`).
                *   **Tool Access**: `read`, and `edit` (mode configuration files only).
                *   **Note**: This is a community version by @mrubens. The built-in `🪃 Orchestrator` mode has broader tool access (including `command` and `mcp`). The `Advanced Orchestrator (Custom Mode)` by iiwish is based on this mrubens design.
            *   **Advanced Orchestrator (Custom Mode) (from `docs/community/custom-modes/advanced-orchestrator.md`)**:
                *   **Author**: iiwish (based on an original design by @mrubens).
                *   **Purpose**: An enhanced workflow orchestration mode for complex task management. It acts as a strategic coordinator, breaking down projects into subtasks, delegating them to specialized modes, and managing the overall workflow.
                *   **Key Enhancements**: Granular task decomposition (optimized for context length), structured dependency management (with checkpoint validation), improved cross-mode communication protocols, tools for workflow documentation and visualization, and techniques for context preservation in multi-stage tasks.
                *   **Tool Access**: `read` (all files), `edit` (restricted to mode configuration files: `.roomodes`, `custom_modes.json`/`cline_custom_modes.json`).
                *   **JSON Configuration**: The source document provides the full JSON configuration including a detailed `roleDefinition` and extensive `customInstructions` for task breakdown, delegation using `new_task`, progress tracking, communication, and managing other custom modes.
        *   Detailed information for each mode is typically found on its dedicated page within the `/community/custom-modes/` directory.
        *   Refer to the [Custom Modes documentation](/features/custom-modes) (Section 5.2) for how to create and configure custom modes.

## 11. Update Notes (from `docs/update-notes/index.md`)

*   The `docs/update-notes/` directory contains detailed release notes for various versions of Roo Code.
*   An `index.md` file within this directory serves as a master list, providing links to individual markdown files for each specific version update (e.g., `v3.17.0.md`, `v3.16.6.md`, etc.).
*   These notes cover versions from v2.1.x up to the latest documented version (v3.17.x as per the `index.md` processed).
*   For specific changes, bug fixes, and new features introduced in a particular version, users should consult the corresponding markdown file in this section of the documentation.

## 12. Ideas & Connections

*   (This section will be for synthesizing information, noting relationships between features, and potential advanced use-cases or ideas that emerge during analysis, especially relevant to the user's end goals.)

## Appendix

*   **Glossary of Terms:** (If needed)
*   **MCP Server Creation Notes:** (If relevant details are found)