Roo Code

IDE extension

Roo Code

Open-source AI coding agent extension for VS Code with multiple modes, MCP support, and rich rule/skill customization.

MCP

Supported

MCP servers configured under mcpServers in a project .roo/mcp.json or the global mcp_settings.json. Supports STDIO, Streamable HTTP, and legacy SSE transports.

Verified 2026-07-12Docs

Transportsstdiohttpsse

Authheadersenv

Config files

Path	Scope	Format	Key
`.roo/mcp.json` Committed project-level servers; created via 'Edit Project MCP' in the MCP settings view.	Project	json	mcpServers
`mcp_settings.json` Global servers; stored in VS Code extension global storage and opened via 'Edit Global MCP' in the MCP settings view.	Global	json	mcpServers

Fields

Field	Type	Description
`command`*	string	Executable to run for a STDIO server (e.g. node, python, npx, or an absolute path). Required for stdio servers.
`args`	string[]	Arguments passed to the command. Supports ${env:VARIABLE_NAME} interpolation.
`cwd`	string	Working directory to launch the server process from. Defaults to the first workspace folder.
`env`	record<string, string>	Environment variables set for the server process.
`type`	"stdio" \| "streamable-http" \| "sse"	Transport type. Defaults to stdio for command-based configs; required for URL-based configs.
`url`	string	Endpoint URL for a remote Streamable HTTP or SSE server.
`headers`	record<string, string>	Custom HTTP headers for remote servers (e.g. authentication tokens).
`alwaysAllow`	string[]	Tool names from this server to auto-approve.
`disabledTools`	string[]	Tool names to disable from this server.
`disabled`	boolean	Set true to disable this server configuration.
`timeout`	number	Per-server response timeout override in seconds (1-3600, default 60).
`watchPaths`	string[]	File paths to watch; the server restarts automatically when they change (stdio servers).

Capabilities

ToolsSupported

ResourcesSupported

Examples

Local STDIO server

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["server.js"],
      "env": { "API_KEY": "your_api_key" },
      "alwaysAllow": ["tool1"],
      "disabled": false
    }
  }
}

Remote Streamable HTTP server

{
  "mcpServers": {
    "remote-server": {
      "type": "streamable-http",
      "url": "https://your-server.com/api/mcp-endpoint",
      "headers": { "X-API-Key": "your-secure-api-key" }
    }
  }
}

•Project-level servers take precedence over global servers with the same name.
•System environment variables can be referenced in args and env via ${env:VARIABLE_NAME}.
•SSE is legacy; Streamable HTTP (type = "streamable-http") is recommended for remote servers. URL-based configs must set type explicitly.
•Per-tool auto-approval via alwaysAllow plus the global 'Use MCP servers' auto-approve setting.

Skills

Supported

SKILL.md instruction packages following the Agent Skills format, loaded on demand when a request matches the skill description. Supports mode-specific and cross-agent (.agents) locations.

Verified 2026-07-12Docs

Invokeautomatic (request matches skill description)skill tool (explicit load, e.g. "use the pdf-processing skill")

Config files

Path	Scope	Format	Key
`.roo/skills/<name>/SKILL.md` Roo-specific project skills (highest priority).	Project	markdown	—
`.agents/skills/<name>/SKILL.md` Cross-agent project skills shared with other agent tools.	Project	markdown	—
`~/.roo/skills/<name>/SKILL.md` Roo-specific global skills.	Global	markdown	—
`~/.agents/skills/<name>/SKILL.md` Cross-agent global skills.	Global	markdown	—

Fields

Field	Type	Description
`name`*	string	Skill identifier; must exactly match the directory (or symlink) name. 1-64 chars, lowercase alphanumeric and hyphens, no leading/trailing/consecutive hyphens.
`description`*	string	What the skill does and when to use it (1-1024 chars). Roo matches requests against this text.

Examples

SKILL.md

---
name: pdf-processing
description: Extract text and tables from PDF files using Python libraries
---

# PDF Processing Instructions

When the user requests PDF processing:
1. Check if PyPDF2 or pdfplumber is installed
2. For text extraction, use pdfplumber for better table detection
3. Always handle encoding errors gracefully

•Progressive disclosure: only frontmatter metadata is indexed at startup; the full SKILL.md loads when a request matches, and bundled files are read on demand.
•Override priority: project .roo > project .agents > global .roo > global .agents; mode-specific beats generic within each location.
•Mode-specific variants live in skills-{modeSlug}/ directories (e.g. .roo/skills-code/).
•Skills can bundle helper scripts, templates, and reference files alongside SKILL.md.
•Symlinked skill directories are supported; the skill name comes from the symlink name.

Rules

Supported

Persistent custom instructions from .roo/rules/ directories (global and workspace), mode-specific rules-{modeSlug}/ variants, .roorules fallback files, and AGENTS.md.

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`.roo/rules/` Preferred workspace-wide rules directory; any text/markdown files, read recursively.	Project	markdown	—
`.roo/rules-{modeSlug}/` Mode-specific rules (e.g. .roo/rules-code/), applied only in that mode.	Project	markdown	—
`.roorules` Single-file fallback when .roo/rules/ is missing or empty. Plain text also accepted.	Project	markdown	—
`AGENTS.md` Agent Rules standard file in the workspace root; AGENT.md used as fallback.	Project	markdown	—
`~/.roo/rules/` Global rules applied to all projects.	Global	markdown	—
`~/.roo/rules-{modeSlug}/` Global mode-specific rules.	Global	markdown	—

Examples

Workspace rule file (.roo/rules/coding-standards.md)

# Global Coding Standards

1. Always use TypeScript for new projects
2. Write unit tests for all new functions
3. Use descriptive variable names
4. Add JSDoc comments for public APIs

•Loading order: global rules (~/.roo/) first, then workspace rules (.roo/); workspace rules win on conflict. Mode-specific rules load before generic rules.
•Rules directories are read recursively and appended to the system prompt in alphabetical order by filename.
•Fallback single files (.roorules, .roorules-{modeSlug}) are used only when the corresponding rules directory is missing or empty; legacy .clinerules is also read.
•AGENTS.md loading is controlled by the roo-cline.useAgentRules VS Code setting (default true); AGENT.md is a fallback when AGENTS.md is absent.
•Additional plain-text instructions can be set per-mode and globally in the Prompts tab UI.

Hooks

Not supported

Roo Code does not expose user-configurable lifecycle hooks.

Verified 2026-07-12

•The official documentation has no hooks feature; no hook configuration file exists in docs or the extension repo.
•Task lifecycle events (taskStarted, taskCompleted, etc.) exist only as an internal extension API for programmatic consumers, not as a user-facing hook surface.

Commands

Supported

Custom slash commands as markdown files in .roo/commands/ (project) or ~/.roo/commands/ (global); the filename becomes the command name.

Verified 2026-07-12Docs

Invoke/command-name

Config files

Path	Scope	Format	Key
`.roo/commands/<name>.md`	Project	markdown	—
`~/.roo/commands/<name>.md`	Global	markdown	—

Fields

Field	Type	Description
`description`	string	Shown in the command menu to explain the command's purpose.
`argument-hint`	string	Hint displayed next to the command showing expected arguments (e.g. <endpoint-name> <http-method>).
`mode`	string	Mode slug to switch to before running the command (e.g. code, architect).

Examples

Command with frontmatter (.roo/commands/api-endpoint.md)

---
description: Generate a new REST API endpoint with best practices
argument-hint: <endpoint-name> <http-method>
---

Create a new REST API endpoint with the following specifications:
- Proper error handling
- Input validation
- Unit tests

Follow our project's API conventions and patterns.

•Project commands override global commands with the same name; built-in commands (e.g. /init and mode-switching commands like /code) cannot be overridden.
•Commands can also be created and managed from Settings > Slash Commands.
•Command subdirectories and symlinked command directories are supported.

Settings

Supported

Settings live in the Roo Code settings UI backed by extension storage, exportable/importable as JSON. Agent-relevant knobs (command allowlists, AGENTS.md loading, timeouts) are VS Code settings under the roo-cline.* namespace.

Verified 2026-07-12Docs

Config files

Path	Scope	Format	Key
`.vscode/settings.json` VS Code workspace settings; all Roo settings are prefixed roo-cline.* (also settable in user settings).	Project	json	roo-cline
`~/Documents/roo-code-settings.json` Default filename for exported settings; any path can be used and wired to auto-import.	Global	json	—

Fields

Field	Type	Description
`roo-cline.allowedCommands`	string[]	Commands auto-executed without approval. Default: ["git log", "git diff", "git show"].
`roo-cline.deniedCommands`	string[]	Commands always blocked from execution.
`roo-cline.commandExecutionTimeout`	number	Timeout in seconds for command execution (0-600; 0 = no timeout).
`roo-cline.useAgentRules`	boolean	Enable loading of AGENTS.md files for agent-specific instructions (default true).
`roo-cline.autoImportSettingsPath`	string	Path to a settings JSON automatically imported on VS Code startup.
`roo-cline.customStoragePath`	string	Custom directory for Roo Code storage (task history, settings).
`roo-cline.apiRequestTimeout`	number	Timeout in seconds for AI provider API requests (0-3600, default 600).
`roo-cline.newTaskRequireTodos`	boolean	Require a todo list when creating new tasks via subtasks (default false).

Examples

Auto-approve safe commands (VS Code settings.json)

{
  "roo-cline.allowedCommands": ["git log", "git diff", "npm test"],
  "roo-cline.useAgentRules": true,
  "roo-cline.autoImportSettingsPath": "~/roo-code-settings.json"
}

•Export/Import produces a roo-code-settings.json file containing provider profiles (including plaintext API keys) and global settings.
•roo-cline.autoImportSettingsPath auto-imports a settings JSON on every VS Code start, useful for syncing machines or standardizing teams.
•MCP servers, rules, skills, and commands have their own dedicated files (see the other surfaces).