diff --git a/docs/features/experimental/custom-tools.md b/docs/features/experimental/custom-tools.md new file mode 100644 index 00000000..739e47af --- /dev/null +++ b/docs/features/experimental/custom-tools.md @@ -0,0 +1,93 @@ +--- +description: Define TypeScript/JavaScript tools that extend Roo's capabilities beyond built-in tools, enabling project-specific workflows and team standardization. +keywords: + - experimental features + - custom tools + - TypeScript tools + - JavaScript tools + - tool extension + - defineCustomTool + - workflow automation +image: /img/social-share.jpg +--- +# Custom Tools + +Define TypeScript or JavaScript tools that Roo can call like built-in tools—standardize team workflows instead of re-prompting the same steps every task. + +:::warning Experimental Feature +Custom tools is an experimental feature. Custom tools are **automatically approved** when enabled—Roo won't ask for permission before running them. Only enable this feature if you trust your tool code. +::: + +--- + +## What it does + +Custom tools let you codify project-specific actions into TypeScript/JavaScript files that Roo calls like [`read_file()`](/basic-usage/how-tools-work) or [`execute_command()`](/basic-usage/how-tools-work). Ship tool schemas alongside your repo so teammates don't need to keep re-explaining the same workflow steps. Tools are validated with Zod and automatically transpiled from TypeScript. + +--- + +## How to create a tool + +Tools live in `.roo/tools/` (project-specific) or `~/.roo/tools/` (global) as `.ts` or `.js` files. Tools from later directories can override earlier ones. + +#### Basic structure + +```typescript +import { parametersSchema as z, defineCustomTool } from "@roo-code/types" + +export default defineCustomTool({ + name: "tool_name", + description: "What the tool does (shown to AI)", + parameters: z.object({ + param1: z.string().describe("Parameter description"), + param2: z.number().describe("Another parameter"), + }), + async execute(args, context) { + // args are type-safe and validated + // context provides: mode, task + return "Result string shown to AI" + } +}) +``` + +#### What you define + +- **`name`**: Tool name Roo sees in its available tools list +- **`description`**: Shown to the AI so it knows when to call the tool +- **`parameters`**: Zod schema converted to JSON Schema for validation +- **`execute`**: Async function returning a string result to Roo + +Tools are dynamically loaded and transpiled with esbuild. Changes to tool files trigger automatic reload. + +--- + +## Enabling the feature + +1. Open Roo Code settings (gear icon in top right) +2. Go to the "Experimental" tab +3. Toggle "Enable custom tools" + +Enable custom tools toggle in experimental settings + +**Critical:** When enabled, custom tools are **auto-approved**—Roo runs them without asking. Disable if you don't trust the tool code. + +--- + +## Tool directories + +- **`.roo/tools/`** in your workspace: project-specific tools shared with your team +- **`~/.roo/tools/`** in your home folder: personal tools across all projects + +Tools from both directories are loaded. Tools with the same name in `.roo/tools/` override those in `~/.roo/tools/`. + +--- + +## Limits + +- **No approval prompts**: Tools are auto-approved when the feature is enabled—security trade-off for convenience +- **String-only results**: Tools must return strings (Roo's protocol constraint) +- **No interactive input**: Tools can't prompt the user mid-execution +- **No npm packages**: Tools are transpiled in isolation; use Node.js built-ins only +- **Cache invalidation**: Tool updates may require reloading the window + +**vs. MCP:** [MCP](/features/mcp/overview) is for external services (search, APIs). Custom tools are for in-repo logic you control directly. MCP is more extensible; custom tools are lighter weight for project-specific actions. diff --git a/docs/features/experimental/experimental-features.md b/docs/features/experimental/experimental-features.md index e68f32b5..2aab8612 100644 --- a/docs/features/experimental/experimental-features.md +++ b/docs/features/experimental/experimental-features.md @@ -32,6 +32,7 @@ To enable or disable experimental features: The following experimental features are currently available: +- [Custom Tools](/features/experimental/custom-tools) - Define TypeScript/JavaScript tools that Roo can call like built-in tools - [Concurrent File Edits](/features/experimental/concurrent-file-edits) - Edit multiple files in a single operation - [Power Steering](/features/experimental/power-steering) - Enhanced consistency in AI responses - [Background Editing](/features/experimental/background-editing) - Work uninterrupted while Roo edits files in the background diff --git a/docs/features/index.md b/docs/features/index.md index 6bc708bc..aedbcbdf 100644 --- a/docs/features/index.md +++ b/docs/features/index.md @@ -58,6 +58,7 @@ Discover the powerful features that make Roo Code your ultimate AI-powered codin Push the boundaries with cutting-edge capabilities: +- [**Custom Tools**](/features/experimental/custom-tools) - Define TypeScript/JavaScript tools that Roo can call - [**Concurrent File Edits**](/features/experimental/concurrent-file-edits) - Edit multiple files in a single operation - [**Power Steering**](/features/experimental/power-steering) - Enhanced consistency in AI responses - [**More Experimental Features**](/features/experimental/experimental-features) - Explore features under development diff --git a/sidebars.ts b/sidebars.ts index 80e49fb1..af0a92e3 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -70,6 +70,7 @@ const sidebars: SidebarsConfig = { label: 'Experimental', items: [ 'features/experimental/experimental-features', + 'features/experimental/custom-tools', 'features/experimental/concurrent-file-edits', 'features/experimental/power-steering', 'features/experimental/background-editing', diff --git a/static/img/custom-tools/custom-tools.png b/static/img/custom-tools/custom-tools.png new file mode 100644 index 00000000..d696c64b Binary files /dev/null and b/static/img/custom-tools/custom-tools.png differ