|
| 1 | +--- |
| 2 | +description: Define TypeScript/JavaScript tools that extend Roo's capabilities beyond built-in tools, enabling project-specific workflows and team standardization. |
| 3 | +keywords: |
| 4 | + - experimental features |
| 5 | + - custom tools |
| 6 | + - TypeScript tools |
| 7 | + - JavaScript tools |
| 8 | + - tool extension |
| 9 | + - defineCustomTool |
| 10 | + - workflow automation |
| 11 | +image: /img/social-share.jpg |
| 12 | +--- |
| 13 | +# Custom Tools |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +:::warning Experimental Feature |
| 18 | +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. |
| 19 | +::: |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## What it does |
| 24 | + |
| 25 | +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. |
| 26 | + |
| 27 | +--- |
| 28 | + |
| 29 | +## How to create a tool |
| 30 | + |
| 31 | +Tools live in `.roo/tools/` (project-specific) or `~/.roo/tools/` (global) as `.ts` or `.js` files. Tools from later directories can override earlier ones. |
| 32 | + |
| 33 | +#### Basic structure |
| 34 | + |
| 35 | +```typescript |
| 36 | +import { parametersSchema as z, defineCustomTool } from "@roo-code/types" |
| 37 | + |
| 38 | +export default defineCustomTool({ |
| 39 | + name: "tool_name", |
| 40 | + description: "What the tool does (shown to AI)", |
| 41 | + parameters: z.object({ |
| 42 | + param1: z.string().describe("Parameter description"), |
| 43 | + param2: z.number().describe("Another parameter"), |
| 44 | + }), |
| 45 | + async execute(args, context) { |
| 46 | + // args are type-safe and validated |
| 47 | + // context provides: mode, task |
| 48 | + return "Result string shown to AI" |
| 49 | + } |
| 50 | +}) |
| 51 | +``` |
| 52 | + |
| 53 | +#### What you define |
| 54 | + |
| 55 | +- **`name`**: Tool name Roo sees in its available tools list |
| 56 | +- **`description`**: Shown to the AI so it knows when to call the tool |
| 57 | +- **`parameters`**: Zod schema converted to JSON Schema for validation |
| 58 | +- **`execute`**: Async function returning a string result to Roo |
| 59 | + |
| 60 | +Tools are dynamically loaded and transpiled with esbuild. Changes to tool files trigger automatic reload. |
| 61 | + |
| 62 | +--- |
| 63 | + |
| 64 | +## Enabling the feature |
| 65 | + |
| 66 | +1. Open Roo Code settings (gear icon in top right) |
| 67 | +2. Go to the "Experimental" tab |
| 68 | +3. Toggle "Enable custom tools" |
| 69 | + |
| 70 | +<img src="/img/custom-tools/custom-tools.png" alt="Enable custom tools toggle in experimental settings" width="400" /> |
| 71 | + |
| 72 | +**Critical:** When enabled, custom tools are **auto-approved**—Roo runs them without asking. Disable if you don't trust the tool code. |
| 73 | + |
| 74 | +--- |
| 75 | + |
| 76 | +## Tool directories |
| 77 | + |
| 78 | +- **`.roo/tools/`** in your workspace: project-specific tools shared with your team |
| 79 | +- **`~/.roo/tools/`** in your home folder: personal tools across all projects |
| 80 | + |
| 81 | +Tools from both directories are loaded. Tools with the same name in `.roo/tools/` override those in `~/.roo/tools/`. |
| 82 | + |
| 83 | +--- |
| 84 | + |
| 85 | +## Limits |
| 86 | + |
| 87 | +- **No approval prompts**: Tools are auto-approved when the feature is enabled—security trade-off for convenience |
| 88 | +- **String-only results**: Tools must return strings (Roo's protocol constraint) |
| 89 | +- **No interactive input**: Tools can't prompt the user mid-execution |
| 90 | +- **No npm packages**: Tools are transpiled in isolation; use Node.js built-ins only |
| 91 | +- **Cache invalidation**: Tool updates may require reloading the window |
| 92 | + |
| 93 | +**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. |
0 commit comments