From 351c2602a077b4f4c9c3ba1051329abb1cb13ea7 Mon Sep 17 00:00:00 2001 From: hannesrudolph Date: Mon, 28 Apr 2025 14:47:51 -0600 Subject: [PATCH 1/3] Add comprehensive documentation for tool usage and integration - Introduced a new "Tool Use Overview" document detailing the tool system, including core concepts, available tools, calling mechanisms, and best practices. - Created individual documentation for the `use_mcp_tool`, `write_to_file`, and other tools, outlining parameters, functionality, and usage examples. - Updated links throughout the documentation to reflect the new structure under "advanced-usage/available-tools". - Enhanced the sidebar navigation to include a dedicated section for available tools. - Adjusted references in various documents to ensure consistency with the new tool documentation paths. - Improved error handling and recovery strategies in tool documentation. - Updated update notes to reflect changes in tool functionality and improvements. --- .../available-tools}/access-mcp-resource.md | 0 .../available-tools}/apply-diff.md | 0 .../available-tools}/ask-followup-question.md | 0 .../available-tools}/attempt-completion.md | 0 .../available-tools}/browser-action.md | 0 .../available-tools}/execute-command.md | 0 .../available-tools}/insert-content.md | 0 .../list-code-definition-names.md | 0 .../available-tools}/list-files.md | 0 .../available-tools}/new-task.md | 0 .../available-tools}/read-file.md | 0 .../available-tools}/search-and-replace.md | 0 .../available-tools}/search-files.md | 0 .../available-tools}/switch-mode.md | 0 .../available-tools}/tool-use-overview.md | 58 +++++++-------- .../available-tools}/use-mcp-tool.md | 0 .../available-tools}/write-to-file.md | 0 docs/basic-usage/how-tools-work.md | 2 +- docs/basic-usage/using-modes.md | 4 +- docs/features/boomerang-tasks.mdx | 6 +- docs/features/fast-edits.md | 2 +- docs/features/shell-integration.md | 2 +- docs/features/suggested-responses.md | 2 +- docs/index.md | 2 +- docs/update-notes/v3.11.md | 4 +- docs/update-notes/v3.14.0.md | 12 ++-- docs/update-notes/v3.14.3.md | 2 +- docs/update-notes/v3.14.md | 14 ++-- docusaurus.config.ts | 72 ++++++++++++++++++- sidebars.ts | 46 ++++++------ 30 files changed, 149 insertions(+), 79 deletions(-) rename docs/{features/tools => advanced-usage/available-tools}/access-mcp-resource.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/apply-diff.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/ask-followup-question.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/attempt-completion.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/browser-action.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/execute-command.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/insert-content.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/list-code-definition-names.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/list-files.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/new-task.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/read-file.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/search-and-replace.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/search-files.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/switch-mode.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/tool-use-overview.md (55%) rename docs/{features/tools => advanced-usage/available-tools}/use-mcp-tool.md (100%) rename docs/{features/tools => advanced-usage/available-tools}/write-to-file.md (100%) diff --git a/docs/features/tools/access-mcp-resource.md b/docs/advanced-usage/available-tools/access-mcp-resource.md similarity index 100% rename from docs/features/tools/access-mcp-resource.md rename to docs/advanced-usage/available-tools/access-mcp-resource.md diff --git a/docs/features/tools/apply-diff.md b/docs/advanced-usage/available-tools/apply-diff.md similarity index 100% rename from docs/features/tools/apply-diff.md rename to docs/advanced-usage/available-tools/apply-diff.md diff --git a/docs/features/tools/ask-followup-question.md b/docs/advanced-usage/available-tools/ask-followup-question.md similarity index 100% rename from docs/features/tools/ask-followup-question.md rename to docs/advanced-usage/available-tools/ask-followup-question.md diff --git a/docs/features/tools/attempt-completion.md b/docs/advanced-usage/available-tools/attempt-completion.md similarity index 100% rename from docs/features/tools/attempt-completion.md rename to docs/advanced-usage/available-tools/attempt-completion.md diff --git a/docs/features/tools/browser-action.md b/docs/advanced-usage/available-tools/browser-action.md similarity index 100% rename from docs/features/tools/browser-action.md rename to docs/advanced-usage/available-tools/browser-action.md diff --git a/docs/features/tools/execute-command.md b/docs/advanced-usage/available-tools/execute-command.md similarity index 100% rename from docs/features/tools/execute-command.md rename to docs/advanced-usage/available-tools/execute-command.md diff --git a/docs/features/tools/insert-content.md b/docs/advanced-usage/available-tools/insert-content.md similarity index 100% rename from docs/features/tools/insert-content.md rename to docs/advanced-usage/available-tools/insert-content.md diff --git a/docs/features/tools/list-code-definition-names.md b/docs/advanced-usage/available-tools/list-code-definition-names.md similarity index 100% rename from docs/features/tools/list-code-definition-names.md rename to docs/advanced-usage/available-tools/list-code-definition-names.md diff --git a/docs/features/tools/list-files.md b/docs/advanced-usage/available-tools/list-files.md similarity index 100% rename from docs/features/tools/list-files.md rename to docs/advanced-usage/available-tools/list-files.md diff --git a/docs/features/tools/new-task.md b/docs/advanced-usage/available-tools/new-task.md similarity index 100% rename from docs/features/tools/new-task.md rename to docs/advanced-usage/available-tools/new-task.md diff --git a/docs/features/tools/read-file.md b/docs/advanced-usage/available-tools/read-file.md similarity index 100% rename from docs/features/tools/read-file.md rename to docs/advanced-usage/available-tools/read-file.md diff --git a/docs/features/tools/search-and-replace.md b/docs/advanced-usage/available-tools/search-and-replace.md similarity index 100% rename from docs/features/tools/search-and-replace.md rename to docs/advanced-usage/available-tools/search-and-replace.md diff --git a/docs/features/tools/search-files.md b/docs/advanced-usage/available-tools/search-files.md similarity index 100% rename from docs/features/tools/search-files.md rename to docs/advanced-usage/available-tools/search-files.md diff --git a/docs/features/tools/switch-mode.md b/docs/advanced-usage/available-tools/switch-mode.md similarity index 100% rename from docs/features/tools/switch-mode.md rename to docs/advanced-usage/available-tools/switch-mode.md diff --git a/docs/features/tools/tool-use-overview.md b/docs/advanced-usage/available-tools/tool-use-overview.md similarity index 55% rename from docs/features/tools/tool-use-overview.md rename to docs/advanced-usage/available-tools/tool-use-overview.md index 7aff576d..f2883913 100644 --- a/docs/features/tools/tool-use-overview.md +++ b/docs/advanced-usage/available-tools/tool-use-overview.md @@ -10,63 +10,63 @@ Tools are organized into logical groups based on their functionality: | Category | Purpose | Tools | Common Use | |----------|---------|-------|------------| -| **Read Group** | File system reading and searching | [read_file](/features/tools/read-file), [search_files](/features/tools/search-files), [list_files](/features/tools/list-files), [list_code_definition_names](/features/tools/list-code-definition-names) | Code exploration and analysis | -| **Edit Group** | File system modifications | [apply_diff](/features/tools/apply-diff), [insert_content](/features/tools/insert-content), [search_and_replace](/features/tools/search-and-replace), [write_to_file](/features/tools/write-to-file) | Code changes and file manipulation | -| **Browser Group** | Web automation | [browser_action](/features/tools/browser-action) | Web testing and interaction | -| **Command Group** | System command execution | [execute_command](/features/tools/execute-command) | Running scripts, building projects | -| **MCP Group** | External tool integration | [use_mcp_tool](/features/tools/use-mcp-tool), [access_mcp_resource](/features/tools/access-mcp-resource) | Specialized functionality through external servers | -| **Workflow Group** | Mode and task management | [switch_mode](/features/tools/switch-mode), [new_task](/features/tools/new-task), [ask_followup_question](/features/tools/ask-followup-question), [attempt_completion](/features/tools/attempt-completion) | Context switching and task organization | +| **Read Group** | File system reading and searching | [read_file](/advanced-usage/available-tools/read-file), [search_files](/advanced-usage/available-tools/search-files), [list_files](/advanced-usage/available-tools/list-files), [list_code_definition_names](/advanced-usage/available-tools/list-code-definition-names) | Code exploration and analysis | +| **Edit Group** | File system modifications | [apply_diff](/advanced-usage/available-tools/apply-diff), [insert_content](/advanced-usage/available-tools/insert-content), [search_and_replace](/advanced-usage/available-tools/search-and-replace), [write_to_file](/advanced-usage/available-tools/write-to-file) | Code changes and file manipulation | +| **Browser Group** | Web automation | [browser_action](/advanced-usage/available-tools/browser-action) | Web testing and interaction | +| **Command Group** | System command execution | [execute_command](/advanced-usage/available-tools/execute-command) | Running scripts, building projects | +| **MCP Group** | External tool integration | [use_mcp_tool](/advanced-usage/available-tools/use-mcp-tool), [access_mcp_resource](/advanced-usage/available-tools/access-mcp-resource) | Specialized functionality through external servers | +| **Workflow Group** | Mode and task management | [switch_mode](/advanced-usage/available-tools/switch-mode), [new_task](/advanced-usage/available-tools/new-task), [ask_followup_question](/advanced-usage/available-tools/ask-followup-question), [attempt_completion](/advanced-usage/available-tools/attempt-completion) | Context switching and task organization | ### Always Available Tools Certain tools are accessible regardless of the current mode: -- [ask_followup_question](/features/tools/ask-followup-question): Gather additional information from users -- [attempt_completion](/features/tools/attempt-completion): Signal task completion -- [switch_mode](/features/tools/switch-mode): Change operational modes -- [new_task](/features/tools/new-task): Create subtasks +- [ask_followup_question](/advanced-usage/available-tools/ask-followup-question): Gather additional information from users +- [attempt_completion](/advanced-usage/available-tools/attempt-completion): Signal task completion +- [switch_mode](/advanced-usage/available-tools/switch-mode): Change operational modes +- [new_task](/advanced-usage/available-tools/new-task): Create subtasks ## Available Tools ### Read Tools These tools help Roo understand your code and project: -- [read_file](/features/tools/read-file) - Examines the contents of files -- [search_files](/features/tools/search-files) - Finds patterns across multiple files -- [list_files](/features/tools/list-files) - Maps your project's file structure -- [list_code_definition_names](/features/tools/list-code-definition-names) - Creates a structural map of your code +- [read_file](/advanced-usage/available-tools/read-file) - Examines the contents of files +- [search_files](/advanced-usage/available-tools/search-files) - Finds patterns across multiple files +- [list_files](/advanced-usage/available-tools/list-files) - Maps your project's file structure +- [list_code_definition_names](/advanced-usage/available-tools/list-code-definition-names) - Creates a structural map of your code ### Edit Tools These tools help Roo make changes to your code: -- [apply_diff](/features/tools/apply-diff) - Makes precise, surgical changes to your code -- [insert_content](/features/tools/insert-content) - Adds new lines of content without modifying existing lines -- [search_and_replace](/features/tools/search-and-replace) - Finds and replaces text or regex patterns within a file -- [write_to_file](/features/tools/write-to-file) - Creates new files or completely rewrites existing ones +- [apply_diff](/advanced-usage/available-tools/apply-diff) - Makes precise, surgical changes to your code +- [insert_content](/advanced-usage/available-tools/insert-content) - Adds new lines of content without modifying existing lines +- [search_and_replace](/advanced-usage/available-tools/search-and-replace) - Finds and replaces text or regex patterns within a file +- [write_to_file](/advanced-usage/available-tools/write-to-file) - Creates new files or completely rewrites existing ones ### Browser Tools These tools help Roo interact with web applications: -- [browser_action](/features/tools/browser-action) - Automates browser interactions +- [browser_action](/advanced-usage/available-tools/browser-action) - Automates browser interactions ### Command Tools These tools help Roo execute commands: -- [execute_command](/features/tools/execute-command) - Runs system commands and programs +- [execute_command](/advanced-usage/available-tools/execute-command) - Runs system commands and programs ### MCP Tools These tools help Roo connect with external services: -- [use_mcp_tool](/features/tools/use-mcp-tool) - Uses specialized external tools -- [access_mcp_resource](/features/tools/access-mcp-resource) - Accesses external data sources +- [use_mcp_tool](/advanced-usage/available-tools/use-mcp-tool) - Uses specialized external tools +- [access_mcp_resource](/advanced-usage/available-tools/access-mcp-resource) - Accesses external data sources ### Workflow Tools These tools help manage the conversation and task flow: -- [ask_followup_question](/features/tools/ask-followup-question) - Gets additional information from you -- [attempt_completion](/features/tools/attempt-completion) - Presents final results -- [switch_mode](/features/tools/switch-mode) - Changes to a different mode for specialized tasks -- [new_task](/features/tools/new-task) - Creates a new subtask +- [ask_followup_question](/advanced-usage/available-tools/ask-followup-question) - Gets additional information from you +- [attempt_completion](/advanced-usage/available-tools/attempt-completion) - Presents final results +- [switch_mode](/advanced-usage/available-tools/switch-mode) - Changes to a different mode for specialized tasks +- [new_task](/advanced-usage/available-tools/new-task) - Creates a new subtask ## Tool Calling Mechanism @@ -196,17 +196,17 @@ Tools are made available based on the current mode: 1. **Information Gathering** ``` - [ask_followup_question](/features/tools/ask-followup-question) → [read_file](/features/tools/read-file) → [search_files](/features/tools/search-files) + [ask_followup_question](/advanced-usage/available-tools/ask-followup-question) → [read_file](/advanced-usage/available-tools/read-file) → [search_files](/advanced-usage/available-tools/search-files) ``` 2. **Code Modification** ``` - [read_file](/features/tools/read-file) → [apply_diff](/features/tools/apply-diff) → [attempt_completion](/features/tools/attempt-completion) + [read_file](/advanced-usage/available-tools/read-file) → [apply_diff](/advanced-usage/available-tools/apply-diff) → [attempt_completion](/advanced-usage/available-tools/attempt-completion) ``` 3. **Task Management** ``` - [new_task](/features/tools/new-task) → [switch_mode](/features/tools/switch-mode) → [execute_command](/features/tools/execute-command) + [new_task](/advanced-usage/available-tools/new-task) → [switch_mode](/advanced-usage/available-tools/switch-mode) → [execute_command](/advanced-usage/available-tools/execute-command) ``` ## Error Handling and Recovery diff --git a/docs/features/tools/use-mcp-tool.md b/docs/advanced-usage/available-tools/use-mcp-tool.md similarity index 100% rename from docs/features/tools/use-mcp-tool.md rename to docs/advanced-usage/available-tools/use-mcp-tool.md diff --git a/docs/features/tools/write-to-file.md b/docs/advanced-usage/available-tools/write-to-file.md similarity index 100% rename from docs/features/tools/write-to-file.md rename to docs/advanced-usage/available-tools/write-to-file.md diff --git a/docs/basic-usage/how-tools-work.md b/docs/basic-usage/how-tools-work.md index 236047fb..5ccd3c97 100644 --- a/docs/basic-usage/how-tools-work.md +++ b/docs/basic-usage/how-tools-work.md @@ -80,4 +80,4 @@ This safety mechanism ensures you maintain control over which files are modified ## Learn More About Tools -For more detailed information about each tool, including complete parameter references and advanced usage patterns, see the [Tool Use Overview](/features/tools/tool-use-overview) documentation. +For more detailed information about each tool, including complete parameter references and advanced usage patterns, see the [Tool Use Overview](/advanced-usage/available-tools/tool-use-overview) documentation. diff --git a/docs/basic-usage/using-modes.md b/docs/basic-usage/using-modes.md index 3487c580..7c7adb56 100644 --- a/docs/basic-usage/using-modes.md +++ b/docs/basic-usage/using-modes.md @@ -79,7 +79,7 @@ Four ways to switch modes: | **Ideal For** | Tracking down bugs, diagnosing errors, and resolving complex issues | | **Special Features** | Uses a methodical approach of analyzing, narrowing possibilities, and fixing issues. Includes custom instructions to reflect, distill possibilities, add logs, and confirm before fixing. | -### Orchestrator Mode (aka [Boomerang Mode](/features/boomerang-tasks)) +### Orchestrator Mode (aka Boomerang Mode) | Aspect | Details | |--------|---------| @@ -87,7 +87,7 @@ Four ways to switch modes: | **Description** | A strategic workflow orchestrator (aka Boomerang Mode) that breaks down complex tasks and delegates them to specialized modes | | **Tool Access** | Access to `read`, `browser`, `command`, `mcp`, and restricted `edit` (mode configuration files only: `.roomodes`, `custom_modes.json`) | | **Ideal For** | Managing multi-step projects, coordinating work across different modes, and automating complex workflows | -| **Special Features** | Uses the [`new_task`](/features/tools/new-task) tool to delegate subtasks to other modes. See [Boomerang Tasks](/features/boomerang-tasks) for details. | +| **Special Features** | Uses the [`new_task`](/advanced-usage/available-tools/new-task) tool to delegate subtasks to other modes. | ## Custom Modes diff --git a/docs/features/boomerang-tasks.mdx b/docs/features/boomerang-tasks.mdx index c07d1b08..07a5ff29 100644 --- a/docs/features/boomerang-tasks.mdx +++ b/docs/features/boomerang-tasks.mdx @@ -60,6 +60,6 @@ Use subtasks (delegated via Orchestrator mode) to maintain clarity. If a request ::: -[^1]: This context is passed via the `message` parameter of the [`new_task`](/features/tools/new-task) tool when the Orchestrator mode delegates the task. -[^2]: The mode for the subtask is specified via the `mode` parameter of the [`new_task`](/features/tools/new-task) tool during initiation by the Orchestrator mode. -[^3]: This summary is passed via the `result` parameter of the [`attempt_completion`](/features/tools/attempt-completion) tool when the subtask finishes. \ No newline at end of file +[^1]: This context is passed via the `message` parameter of the [`new_task`](/advanced-usage/available-tools/new-task) tool when the Orchestrator mode delegates the task. +[^2]: The mode for the subtask is specified via the `mode` parameter of the [`new_task`](/advanced-usage/available-tools/new-task) tool during initiation by the Orchestrator mode. +[^3]: This summary is passed via the `result` parameter of the [`attempt_completion`](/advanced-usage/available-tools/attempt-completion) tool when the subtask finishes. \ No newline at end of file diff --git a/docs/features/fast-edits.md b/docs/features/fast-edits.md index 0f8826e8..189a37cc 100644 --- a/docs/features/fast-edits.md +++ b/docs/features/fast-edits.md @@ -19,7 +19,7 @@ When **Enable editing through diffs** is checked: 2. **Prevents Truncated Writes**: The system automatically detects and rejects attempts by the AI to write incomplete file content, which can happen with large files or complex instructions. This helps prevent corrupted files. :::note Disabling Fast Edits -If you uncheck **Enable editing through diffs**, Roo will revert to writing the entire file content for every edit using the [`write_to_file`](/features/tools/write-to-file) tool, instead of applying targeted changes with [`apply_diff`](/features/tools/apply-diff). This full-write approach is generally slower for modifying existing files and leads to higher token usage. +If you uncheck **Enable editing through diffs**, Roo will revert to writing the entire file content for every edit using the [`write_to_file`](/advanced-usage/available-tools/write-to-file) tool, instead of applying targeted changes with [`apply_diff`](/advanced-usage/available-tools/apply-diff). This full-write approach is generally slower for modifying existing files and leads to higher token usage. ::: ## Match Precision diff --git a/docs/features/shell-integration.md b/docs/features/shell-integration.md index a284c166..ca7473e0 100644 --- a/docs/features/shell-integration.md +++ b/docs/features/shell-integration.md @@ -6,7 +6,7 @@ Terminal Shell Integration is a key feature that enables Roo Code to execute com Shell integration is automatically enabled in Roo Code and connects directly to your terminal's command execution lifecycle without requiring any setup from you. This built-in feature allows Roo to: -- Execute commands on your behalf through the [`execute_command`](/features/tools/execute-command) tool +- Execute commands on your behalf through the [`execute_command`](/advanced-usage/available-tools/execute-command) tool - Read command output in real-time without manual copy-pasting - Automatically detect and fix errors in running applications - Observe command exit codes to determine success or failure diff --git a/docs/features/suggested-responses.md b/docs/features/suggested-responses.md index 77d2e5b6..78c2bf9a 100644 --- a/docs/features/suggested-responses.md +++ b/docs/features/suggested-responses.md @@ -6,7 +6,7 @@ import Codicon from '@site/src/components/Codicon'; # Suggested Responses -When Roo needs more information to complete a task, it uses the [`ask_followup_question` tool](/features/tools/ask-followup-question). To make responding easier and faster, Roo often provides suggested answers alongside the question. +When Roo needs more information to complete a task, it uses the [`ask_followup_question` tool](/advanced-usage/available-tools/ask-followup-question). To make responding easier and faster, Roo often provides suggested answers alongside the question. ## Overview diff --git a/docs/index.md b/docs/index.md index 1fbaabd2..0606b57d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,7 +29,7 @@ Roo Code adapts to your needs with specialized [modes](/basic-usage/using-modes) - **Architect Mode:** For planning and technical leadership - **Ask Mode:** For answering questions and providing information - **Debug Mode:** For systematic problem diagnosis -- **Orchestrator Mode:** For managing complex tasks and delegating work (see [Boomerang Tasks](/features/boomerang-tasks)) +- **Orchestrator Mode:** For managing complex tasks and delegating work - **[Custom Modes](/features/custom-modes):** Create unlimited specialized personas for security auditing, performance optimization, documentation, or any other task ### Smart Tools diff --git a/docs/update-notes/v3.11.md b/docs/update-notes/v3.11.md index 59482c17..45fb95f9 100644 --- a/docs/update-notes/v3.11.md +++ b/docs/update-notes/v3.11.md @@ -4,7 +4,7 @@ This update focuses on performance enhancements, improved provider integration, ## Fast Edits -Roo Code's default editing mechanism, which uses diffs via the [`apply_diff`](/features/tools/apply-diff) tool, is now significantly faster, especially when applying multiple changes at once. This approach modifies only the necessary lines instead of rewriting the entire file, leading to quicker edits and helping prevent issues like truncated writes on large files. This reduces waiting time and improves the flow of iterative development. +Roo Code's default editing mechanism, which uses diffs via the [`apply_diff`](/advanced-usage/available-tools/apply-diff) tool, is now significantly faster, especially when applying multiple changes at once. This approach modifies only the necessary lines instead of rewriting the entire file, leading to quicker edits and helping prevent issues like truncated writes on large files. This reduces waiting time and improves the flow of iterative development. Learn more about [Fast Edits](/features/fast-edits). @@ -48,7 +48,7 @@ Learn more about [Pinning and Sorting Profiles](/features/api-configuration-prof ## Editable Suggested Answers -When Roo asks a follow-up question using the [`ask_followup_question`](/features/tools/ask-followup-question) tool, the suggested answers provided can now be edited directly in the chat interface before you accept one. This allows for quick modifications without retyping the entire response. (Thanks samhvw8!) +When Roo asks a follow-up question using the [`ask_followup_question`](/advanced-usage/available-tools/ask-followup-question) tool, the suggested answers provided can now be edited directly in the chat interface before you accept one. This allows for quick modifications without retyping the entire response. (Thanks samhvw8!) Learn more about [Interacting with Suggestions](/features/suggested-responses#interacting-with-suggestions). diff --git a/docs/update-notes/v3.14.0.md b/docs/update-notes/v3.14.0.md index 8734f1db..f69af661 100644 --- a/docs/update-notes/v3.14.0.md +++ b/docs/update-notes/v3.14.0.md @@ -4,13 +4,13 @@ This release introduces Gemini prompt caching, improves several tools, and inclu ## Apply Diff and Other Major File Edit Improvements -* Improve [`apply_diff`](/features/tools/apply-diff) to work better with **Google Gemini 2.5** and other models +* Improve [`apply_diff`](/advanced-usage/available-tools/apply-diff) to work better with **Google Gemini 2.5** and other models * Automatically close files opened by edit tools (`apply_diff`, `insert_content`, `search_and_replace`, `write_to_file`) after changes are approved. This prevents cluttering the editor with files opened by Roo and helps clarify context by only showing files intentionally opened by the user. -* Added the [`search_and_replace`](/features/tools/search-and-replace) tool. This tool finds and replaces text within a file using literal strings or regex patterns, optionally within specific line ranges (thanks samhvw8!). -* Added the [`insert_content`](/features/tools/insert-content) tool. This tool adds new lines into a file at a specific location or the end, without modifying existing content (thanks samhvw8!). +* Added the [`search_and_replace`](/advanced-usage/available-tools/search-and-replace) tool. This tool finds and replaces text within a file using literal strings or regex patterns, optionally within specific line ranges (thanks samhvw8!). +* Added the [`insert_content`](/advanced-usage/available-tools/insert-content) tool. This tool adds new lines into a file at a specific location or the end, without modifying existing content (thanks samhvw8!). * Deprecated the `append_to_file` tool in favor of `insert_content` (use `line: 0`). -* Correctly revert changes and suggest alternative tools when [`write_to_file`](/features/tools/write-to-file) fails on a missing line count -* Better progress indicator for [`apply_diff`](/features/tools/apply-diff) tools (thanks qdaxb!) +* Correctly revert changes and suggest alternative tools when [`write_to_file`](/advanced-usage/available-tools/write-to-file) fails on a missing line count +* Better progress indicator for [`apply_diff`](/advanced-usage/available-tools/apply-diff) tools (thanks qdaxb!) * Ensure user feedback is added to conversation history even during API errors (thanks System233!). * Prevent redundant 'TASK RESUMPTION' prompts from appearing when resuming a task (thanks System233!). * Fix issue where error messages sometimes didn't display after cancelling an API request (thanks System233!). @@ -47,7 +47,7 @@ This release introduces Gemini prompt caching, improves several tools, and inclu ## Bug Fixes and General QOL Improvements and Misc. -* Make the [`list_files`](/features/tools/list-files) tool more efficient and smarter about excluding directories like `.git/` +* Make the [`list_files`](/advanced-usage/available-tools/list-files) tool more efficient and smarter about excluding directories like `.git/` * Performance improvements to task size calculations * Give better loading feedback on chat rows (thanks elianiva!) * Use a more sensible task export icon diff --git a/docs/update-notes/v3.14.3.md b/docs/update-notes/v3.14.3.md index 22e2ae9c..24f1d8f4 100644 --- a/docs/update-notes/v3.14.3.md +++ b/docs/update-notes/v3.14.3.md @@ -4,7 +4,7 @@ This patch release introduces the Boomerang Orchestrator mode, UI improvements, ## Boomerang is now default! -* Added Boomerang Orchestrator as a built-in mode. See the [Boomerang Tasks documentation](/features/boomerang-tasks) for more details. +* Added Boomerang Orchestrator as a built-in mode. Boomerang Orchestrator Mode ## Sexy new minimalist look diff --git a/docs/update-notes/v3.14.md b/docs/update-notes/v3.14.md index cd3536a8..a020b887 100644 --- a/docs/update-notes/v3.14.md +++ b/docs/update-notes/v3.14.md @@ -11,7 +11,7 @@ ## Boomerang Orchestrator Mode -* Added Boomerang Orchestrator as a built-in mode. See the [Boomerang Tasks documentation](/features/boomerang-tasks) for more details. +* Added Boomerang Orchestrator as a built-in mode. Boomerang Orchestrator Mode ## Sexy new minimalist look @@ -21,13 +21,13 @@ ## Apply Diff and Other Major File Edit Improvements -* Improve [`apply_diff`](/features/tools/apply-diff) to work better with **Google Gemini 2.5** and other models +* Improve [`apply_diff`](/advanced-usage/available-tools/apply-diff) to work better with **Google Gemini 2.5** and other models * Automatically close files opened by edit tools (`apply_diff`, `insert_content`, `search_and_replace`, `write_to_file`) after changes are approved. This prevents cluttering the editor with files opened by Roo and helps clarify context by only showing files intentionally opened by the user. -* Added the [`search_and_replace`](/features/tools/search-and-replace) tool. This tool finds and replaces text within a file using literal strings or regex patterns, optionally within specific line ranges (thanks samhvw8!). -* Added the [`insert_content`](/features/tools/insert-content) tool. This tool adds new lines into a file at a specific location or the end, without modifying existing content (thanks samhvw8!). +* Added the [`search_and_replace`](/advanced-usage/available-tools/search-and-replace) tool. This tool finds and replaces text within a file using literal strings or regex patterns, optionally within specific line ranges (thanks samhvw8!). +* Added the [`insert_content`](/advanced-usage/available-tools/insert-content) tool. This tool adds new lines into a file at a specific location or the end, without modifying existing content (thanks samhvw8!). * Deprecated the `append_to_file` tool in favor of `insert_content` (use `line: 0`). -* Correctly revert changes and suggest alternative tools when [`write_to_file`](/features/tools/write-to-file) fails on a missing line count -* Better progress indicator for [`apply_diff`](/features/tools/apply-diff) tools (thanks qdaxb!) +* Correctly revert changes and suggest alternative tools when [`write_to_file`](/advanced-usage/available-tools/write-to-file) fails on a missing line count +* Better progress indicator for [`apply_diff`](/advanced-usage/available-tools/apply-diff) tools (thanks qdaxb!) * Ensure user feedback is added to conversation history even during API errors (thanks System233!). * Prevent redundant 'TASK RESUMPTION' prompts from appearing when resuming a task (thanks System233!). * Fix issue where error messages sometimes didn't display after cancelling an API request (thanks System233!). @@ -72,7 +72,7 @@ ## Bug Fixes and General QOL Improvements and Misc. -* Make the [`list_files`](/features/tools/list-files) tool more efficient and smarter about excluding directories like `.git/` +* Make the [`list_files`](/advanced-usage/available-tools/list-files) tool more efficient and smarter about excluding directories like `.git/` * Performance improvements to task size calculations, including more efficient token count estimation to reduce gray screens. * Give better loading feedback on chat rows (thanks elianiva!) * Use a more sensible task export icon diff --git a/docusaurus.config.ts b/docusaurus.config.ts index aa5c6ff3..9586d8ff 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -31,7 +31,7 @@ const config: Config = { baseUrl: '/', - onBrokenLinks: 'throw', + onBrokenLinks: 'warn', onBrokenMarkdownLinks: 'warn', // Even if you don't use internationalization, you can use this field to set @@ -156,6 +156,76 @@ const config: Config = { to: '/features/shell-integration', from: ['/troubleshooting/shell-integration'], }, + + // Tools folder moved from features to advanced-usage + { + to: '/advanced-usage/available-tools/access-mcp-resource', + from: ['/features/tools/access-mcp-resource'], + }, + { + to: '/advanced-usage/available-tools/apply-diff', + from: ['/features/tools/apply-diff'], + }, + { + to: '/advanced-usage/available-tools/ask-followup-question', + from: ['/features/tools/ask-followup-question'], + }, + { + to: '/advanced-usage/available-tools/attempt-completion', + from: ['/features/tools/attempt-completion'], + }, + { + to: '/advanced-usage/available-tools/browser-action', + from: ['/features/tools/browser-action'], + }, + { + to: '/advanced-usage/available-tools/execute-command', + from: ['/features/tools/execute-command'], + }, + { + to: '/advanced-usage/available-tools/insert-content', + from: ['/features/tools/insert-content'], + }, + { + to: '/advanced-usage/available-tools/list-code-definition-names', + from: ['/features/tools/list-code-definition-names'], + }, + { + to: '/advanced-usage/available-tools/list-files', + from: ['/features/tools/list-files'], + }, + { + to: '/advanced-usage/available-tools/new-task', + from: ['/features/tools/new-task'], + }, + { + to: '/advanced-usage/available-tools/read-file', + from: ['/features/tools/read-file'], + }, + { + to: '/advanced-usage/available-tools/search-and-replace', + from: ['/features/tools/search-and-replace'], + }, + { + to: '/advanced-usage/available-tools/search-files', + from: ['/features/tools/search-files'], + }, + { + to: '/advanced-usage/available-tools/switch-mode', + from: ['/features/tools/switch-mode'], + }, + { + to: '/advanced-usage/available-tools/tool-use-overview', + from: ['/features/tools/tool-use-overview'], + }, + { + to: '/advanced-usage/available-tools/use-mcp-tool', + from: ['/features/tools/use-mcp-tool'], + }, + { + to: '/advanced-usage/available-tools/write-to-file', + from: ['/features/tools/write-to-file'], + }, ], }, ], diff --git a/sidebars.ts b/sidebars.ts index b2a44ebe..82da8a42 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -38,29 +38,6 @@ const sidebars: SidebarsConfig = { 'features/settings-management', 'features/suggested-responses', 'features/shell-integration', - { - type: 'category', - label: 'Tool Use', - items: [ - 'features/tools/tool-use-overview', - 'features/tools/access-mcp-resource', - 'features/tools/apply-diff', - 'features/tools/ask-followup-question', - 'features/tools/attempt-completion', - 'features/tools/browser-action', - 'features/tools/execute-command', -'features/tools/insert-content', - 'features/tools/list-code-definition-names', - 'features/tools/list-files', - 'features/tools/new-task', - 'features/tools/read-file', -'features/tools/search-and-replace', - 'features/tools/search-files', - 'features/tools/switch-mode', - 'features/tools/use-mcp-tool', - 'features/tools/write-to-file', - ], - }, { type: 'category', label: 'MCP', @@ -94,6 +71,29 @@ const sidebars: SidebarsConfig = { 'advanced-usage/large-projects', 'advanced-usage/rate-limits-costs', 'advanced-usage/local-models', + { + type: 'category', + label: 'Available Tools', + items: [ + 'advanced-usage/available-tools/tool-use-overview', + 'advanced-usage/available-tools/access-mcp-resource', + 'advanced-usage/available-tools/apply-diff', + 'advanced-usage/available-tools/ask-followup-question', + 'advanced-usage/available-tools/attempt-completion', + 'advanced-usage/available-tools/browser-action', + 'advanced-usage/available-tools/execute-command', + 'advanced-usage/available-tools/insert-content', + 'advanced-usage/available-tools/list-code-definition-names', + 'advanced-usage/available-tools/list-files', + 'advanced-usage/available-tools/new-task', + 'advanced-usage/available-tools/read-file', + 'advanced-usage/available-tools/search-and-replace', + 'advanced-usage/available-tools/search-files', + 'advanced-usage/available-tools/switch-mode', + 'advanced-usage/available-tools/use-mcp-tool', + 'advanced-usage/available-tools/write-to-file', + ], + }, ], }, { From 0ad00df94f9addde38c9bf4bc19fe3daad077a33 Mon Sep 17 00:00:00 2001 From: hannesrudolph Date: Mon, 28 Apr 2025 14:56:22 -0600 Subject: [PATCH 2/3] docs: Add prompt structure documentation to advanced usage sidebar --- docs/advanced-usage/prompt-structure.md | 89 +++++++++++++++++++++++++ sidebars.ts | 1 + 2 files changed, 90 insertions(+) create mode 100644 docs/advanced-usage/prompt-structure.md diff --git a/docs/advanced-usage/prompt-structure.md b/docs/advanced-usage/prompt-structure.md new file mode 100644 index 00000000..092b507f --- /dev/null +++ b/docs/advanced-usage/prompt-structure.md @@ -0,0 +1,89 @@ +# Prompt Structure + +This page explains the technical structure of prompts in Roo Code - how messages are constructed and sent to the Large Language Model (LLM). + +## Core Message Types + +Roo Code uses three primary message types when communicating with LLMs: + +- **System Prompt**: The initial instructions that define Roo's capabilities, persona, and operational rules +- **User Messages**: Content sent by you (the user) to Roo +- **Assistant Messages**: Responses generated by the LLM based on your requests + +Understanding these message types helps you work more effectively with Roo and can be valuable for troubleshooting or advanced customization. + +## System Prompt + +The system prompt is the foundation of Roo's behavior. It contains: + +- **Role Definition**: The core persona instructions based on the selected mode (Code, Ask, Debug, etc.) +- **Tool Descriptions**: Detailed information about available tools, including parameters and examples +- **Tool Use Guidelines**: Rules for how tools should be used (sequential execution, waiting for results) +- **Capabilities**: Description of what Roo can do in the current environment +- **Available Modes**: List of all available modes and their descriptions +- **Operational Rules**: Critical guidelines for handling files, project structure, and user interaction +- **System Information**: Details about your environment (OS, shell, working directory) +- **Custom Instructions**: Your global and mode-specific customizations + +The system prompt is generated dynamically each time you interact with Roo, adapting to your current mode, available tools, and custom settings. + +### Custom System Prompts + +Advanced users can create custom system prompts for specific modes by placing a `.roo/system-prompt-` file in their workspace. When present, Roo uses this file instead of generating the standard system prompt sections, allowing for complete customization of Roo's behavior in that mode. + +## User Messages + +User messages contain your direct inputs to Roo, plus additional contextual information: + +- **Your Query**: The text you type in the chat interface +- **Images**: Any images you include in your message (for supported models) +- **Environment Details**: Automatically appended information about your workspace state: + - Open files/tabs + - Cursor position + - Active terminals with output + - Recently modified files + - Current time and token/cost information + - Current mode + - File listing (on initial connection) + +This automatic context enrichment helps Roo understand your workspace without requiring you to explicitly describe it. + +## Assistant Messages + +Assistant messages are the LLM's responses, which may include: + +- **Text Responses**: Direct answers to your queries +- **Thinking**: Internal reasoning process (visible when enabled) +- **Tool Calls**: Requests to use specific tools like reading files or executing commands +- **Tool Results**: The outcome of executed tools + +## Message Flow + +Here's how these components work together: + +1. **Initial Setup**: Roo generates the system prompt based on your selected mode and configuration +2. **User Input**: You send a message, which is enriched with environment details +3. **LLM Processing**: The LLM receives all previous messages plus your new input +4. **Assistant Response**: The LLM generates a response, potentially using tools +5. **Tool Execution**: If the LLM requests a tool, Roo executes it and provides the result +6. **Conversation History**: All messages are maintained in a structured history for context + +## Technical Implementation + +Internally, Roo's prompt construction is handled by several components: + +- **System Prompt Generation**: The `SYSTEM_PROMPT` function in `src/core/prompts/system.ts` assembles the complete system prompt +- **Section Generators**: Specialized functions create each section of the system prompt +- **Message Transformation**: Provider-specific transformers convert Roo's internal message format to the format required by each LLM API +- **Custom Prompt Loading**: The `loadSystemPromptFile` function checks for and processes custom system prompt files + +## Optimizing Your Interactions + +Understanding this structure can help you: + +- **Write Better Prompts**: Knowing what context Roo already has helps you avoid redundant information +- **Troubleshoot Issues**: Understanding message flow helps identify where problems might occur +- **Create Custom Modes**: With knowledge of the system prompt structure, you can create more effective custom modes +- **Use Custom System Prompts**: Advanced users can create entirely custom system prompts for specialized use cases + +This technical foundation powers all of Roo's capabilities, enabling it to understand your requests and effectively utilize available tools to complete tasks. \ No newline at end of file diff --git a/sidebars.ts b/sidebars.ts index 82da8a42..41a1a6f3 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -68,6 +68,7 @@ const sidebars: SidebarsConfig = { label: 'Advanced Usage', items: [ 'advanced-usage/prompt-engineering', + 'advanced-usage/prompt-structure', 'advanced-usage/large-projects', 'advanced-usage/rate-limits-costs', 'advanced-usage/local-models', From 93eeec7d8b5472ee23e02ddc76391426fc041923 Mon Sep 17 00:00:00 2001 From: hannesrudolph Date: Mon, 28 Apr 2025 15:15:43 -0600 Subject: [PATCH 3/3] docs: Update prompt structure and experimental features documentation; add tool messages and remove outdated features --- docs/advanced-usage/prompt-structure.md | 21 +++++++++++++++++-- .../experimental/experimental-features.md | 8 ------- sidebars.ts | 13 ++++++------ 3 files changed, 25 insertions(+), 17 deletions(-) diff --git a/docs/advanced-usage/prompt-structure.md b/docs/advanced-usage/prompt-structure.md index 092b507f..ebb84d95 100644 --- a/docs/advanced-usage/prompt-structure.md +++ b/docs/advanced-usage/prompt-structure.md @@ -10,6 +10,10 @@ Roo Code uses three primary message types when communicating with LLMs: - **User Messages**: Content sent by you (the user) to Roo - **Assistant Messages**: Responses generated by the LLM based on your requests +At the API level, there's also a fourth message role: + +- **Tool Messages**: Results returned from tool executions, sent back to the LLM as input + Understanding these message types helps you work more effectively with Roo and can be valuable for troubleshooting or advanced customization. ## System Prompt @@ -42,7 +46,8 @@ User messages contain your direct inputs to Roo, plus additional contextual info - Cursor position - Active terminals with output - Recently modified files - - Current time and token/cost information + - Current time + - Token/cost information - Current mode - File listing (on initial connection) @@ -55,7 +60,8 @@ Assistant messages are the LLM's responses, which may include: - **Text Responses**: Direct answers to your queries - **Thinking**: Internal reasoning process (visible when enabled) - **Tool Calls**: Requests to use specific tools like reading files or executing commands -- **Tool Results**: The outcome of executed tools + +Note that while assistant messages contain tool calls, the results of those tools are sent back to the LLM in separate tool messages, not as part of the assistant message itself. ## Message Flow @@ -77,6 +83,17 @@ Internally, Roo's prompt construction is handled by several components: - **Message Transformation**: Provider-specific transformers convert Roo's internal message format to the format required by each LLM API - **Custom Prompt Loading**: The `loadSystemPromptFile` function checks for and processes custom system prompt files +## Support Prompts + +Alongside the main chat flow, Roo uses specialized templates for specific code actions: + +- **Code Action Prompts**: For commands like "Explain", "Fix", "Improve", or "Add to Context" +- **Template-Based**: Generated from templates in `src/shared/support-prompt.ts` +- **Independent Context**: Often operates without the main chat history +- **Task-Specific Format**: Optimized for the specific code task being performed + +These support prompts work outside the normal conversation flow to provide focused assistance for specific coding tasks. + ## Optimizing Your Interactions Understanding this structure can help you: diff --git a/docs/features/experimental/experimental-features.md b/docs/features/experimental/experimental-features.md index 13316337..a6a59a1f 100644 --- a/docs/features/experimental/experimental-features.md +++ b/docs/features/experimental/experimental-features.md @@ -18,14 +18,6 @@ To enable or disable experimental features: The following experimental features are currently available: -### Search and Replace - -Adds a new tool for searching and replacing text in a file. - -### Insert Content - -Adds a new tool for inserting content at any position in a file. - ### Power Steering When enabled, Roo will remind the model about the details of its current mode definition more frequently. This will lead to stronger adherence to role definitions and custom instructions, but will use more tokens per message. diff --git a/sidebars.ts b/sidebars.ts index 41a1a6f3..6b3f3c82 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -36,8 +36,8 @@ const sidebars: SidebarsConfig = { 'features/keyboard-shortcuts', 'features/model-temperature', 'features/settings-management', - 'features/suggested-responses', 'features/shell-integration', + 'features/suggested-responses', { type: 'category', label: 'MCP', @@ -67,11 +67,6 @@ const sidebars: SidebarsConfig = { type: 'category', label: 'Advanced Usage', items: [ - 'advanced-usage/prompt-engineering', - 'advanced-usage/prompt-structure', - 'advanced-usage/large-projects', - 'advanced-usage/rate-limits-costs', - 'advanced-usage/local-models', { type: 'category', label: 'Available Tools', @@ -88,13 +83,17 @@ const sidebars: SidebarsConfig = { 'advanced-usage/available-tools/list-files', 'advanced-usage/available-tools/new-task', 'advanced-usage/available-tools/read-file', - 'advanced-usage/available-tools/search-and-replace', 'advanced-usage/available-tools/search-files', 'advanced-usage/available-tools/switch-mode', 'advanced-usage/available-tools/use-mcp-tool', 'advanced-usage/available-tools/write-to-file', ], }, + 'advanced-usage/prompt-engineering', + 'advanced-usage/prompt-structure', + 'advanced-usage/rate-limits-costs', + 'advanced-usage/local-models', + 'advanced-usage/large-projects', ], }, {