How to Configure Roo Code Custom Modes: Optimize Your AI Developer Agent

Disclosure: This article may contain affiliate links. We only recommend products we believe in.

To configure Roo Code custom modes, you must define them inside the roo_modes.json file in your global or workspace configuration directory. By specifying custom mode definitions—including specific role prompts, system instructions, and tool restrictions—you can tailor your AI developer agent’s behavior to match your exact software engineering workflow.

Executive Summary

  • Customization Control: Roo Code allows developers to create dedicated agent personas (e.g., Code, Architect, Refactorer, Reviewer) rather than relying on a single generic assistant.
  • Tool Restriction Management: You can restrict custom modes to a subset of system tools (like read-only, write-only, or command execution) to balance autonomy and safety.
  • Workflow Efficiency: Properly configured modes cut API costs by up to 30% by preventing the LLM from making redundant tool calls or reasoning loops.
  • Setup Simplicity: Configuring modes requires modifying a single JSON file (roo_modes.json) which can be shared across teams or checked into repository roots.

Why Should You Customize Your AI Coding Persona?

Standard AI coding assistants operate under a single, generic set of instructions. While this works for simple completions, complex software engineering tasks require different mindsets. An architect needs to focus on structure, modularity, and API design without immediately writing code. A debugger needs write access and terminal execution tools to find and fix test failures.

By creating custom modes, you segment the developer lifecycle. The model receives a targeted system prompt tailored to a specific task, reducing cognitive load on the LLM. This leads to higher success rates for complex, multi-file code editing and prevents “context drift” where the AI forgets its primary objective during long troubleshooting sessions.

What is the Difference Between Roo Code Modes and Default AI Tools?

Default AI tools like Cursor or GitHub Copilot use a unified chat prompt that tries to handle all tasks. In contrast, Roo Code’s mode system is built on strict behavioral segregation. When you switch modes in Roo Code, you are swapping the underlying system prompt and the tool permissions.

For instance, the default Architect mode in Roo Code is designed for high-level planning. It has access to file-reading tools but is restricted from writing files directly. The default Code mode has write access but might lack terminal execution permissions in strict setups. Custom modes allow you to define the exact boundaries of these permissions, granting command execution only to debugging and testing modes while keeping refactoring modes sandboxed.

Where is the Configuration File Located?

Roo Code looks for custom mode definitions in two locations depending on whether you want global or project-specific configurations:

  1. Global Configuration: Stores modes that are active across all projects.
    • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/roo_modes.json
    • Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\roo_modes.json
    • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/roo_modes.json
  2. Workspace/Project Configuration: Stores modes specific to a project.
    • Project Root: Located in .vscode/roo_modes.json

Workspace-level configuration takes precedence over global settings, allowing teams to check custom mode definitions directly into git to keep environments synchronized.

How Do You Write a Valid custom mode Schema?

The roo_modes.json file uses a specific JSON schema to define the list of modes. Each mode object must contain fields for slug, name, role definition, groups, and instructions.

Here is a complete, valid schema example for roo_modes.json:

{
  "customModes": [
    {
      "slug": "senior-refactor",
      "name": "Senior Refactorer",
      "roleDefinition": "You are a senior software engineer specializing in code cleanups, performance optimizations, and technical debt reduction. Your goal is to simplify code without changing its functionality.",
      "groups": ["read", "write"],
      "customInstructions": "Always verify that your refactoring passes existing tests. Prioritize readability and performance. Never write new features unless explicitly asked."
    },
    {
      "slug": "qa-tester",
      "name": "QA Test Runner",
      "roleDefinition": "You are a QA automation engineer specializing in writing unit tests, integration tests, and executing test suites to verify application health.",
      "groups": ["read", "write", "execute"],
      "customInstructions": "When writing tests, cover edge cases and failure modes. You are authorized to run test commands in the terminal using the execute tools. Always report test results."
    }
  ]
}

What are the Available Tool Groups and Permissions?

When defining a custom mode, the groups array controls which tools the agent can use. Restricting tool groups is crucial for maintaining safety and preventing the AI from running destructive terminal commands.

The following tool groups are supported:

  • read: Permits the agent to read files, search directories, and list file structures.
  • write: Permits the agent to edit existing files or write new files.
  • execute: Permits the agent to execute terminal commands.
  • mcp: Permits the agent to use Model Context Protocol servers.

If a mode does not include a group (for example, leaving out execute), the agent will not be shown those tools, and the LLM will not attempt to call them. This is an excellent way to sandbox the LLM during high-risk editing tasks.

How to Set Up an Architect Mode that Cannot Write Code?

One of the best practices in AI-assisted development is keeping architectural planning separate from coding. This prevents the LLM from generating large chunks of unverified code before the design is finalized.

To set up a pure Architect mode, create a mode that is restricted to the read and mcp tool groups:

{
  "slug": "solution-architect",
  "name": "Solution Architect",
  "roleDefinition": "You are a principal software architect. Your job is to analyze codebases, design architectures, and write documentation. You plan but do not edit code.",
  "groups": ["read"],
  "customInstructions": "Review the codebase structure. When asked to implement a feature, write a detailed Markdown design doc outlining changes, file structures, and data flows. Instruct the user to switch to Code mode to write the actual code."
}

This configuration guarantees that the architect agent will only analyze and document, preventing it from writing buggy drafts directly into your code.

How to Configure a Tester Mode with Terminal Access?

Writing and running tests requires an agent that can write test files and run terminal commands to verify the outputs. Here is the configuration for a dedicated test agent:

{
  "slug": "test-agent",
  "name": "Test & Verify Agent",
  "roleDefinition": "You are an expert test engineer. Your task is to write test suites and run tests to verify codebase health. You have full terminal access to run test commands.",
  "groups": ["read", "write", "execute"],
  "customInstructions": "Always check what test runner the project uses (e.g., Jest, Pytest, Vitest) before writing tests. After writing or modifying tests, run the appropriate test command in the terminal and report the output. Do not touch production code unless fixing a bug discovered in the tests."
}

By assigning terminal tools to this mode, you keep command-line risks confined to a specific persona that you only activate when running tests.

How Can Teams Share Custom Modes Across Git Repositories?

To ensure all developers on a team use the same AI coding standards, you should store the roo_modes.json file in the project’s root directory. The recommended workflow is:

  1. Create a .vscode folder in the root of your project if it does not exist.
  2. Create roo_modes.json inside the .vscode directory.
  3. Define your custom modes (e.g., Code Reviewer, Database Migrator).
  4. Add the .vscode/roo_modes.json file to your git repository: 
    git add .vscode/roo_modes.json
git commit -m "docs: add shared Roo Code custom modes configuration"

When developers open the project in VS Code with Roo Code installed, the editor automatically loads the workspace modes, making them available in the mode dropdown.

What are the Best Practices for Writing Custom Instructions?

Custom instructions are appended to the system prompt of the LLM. To get the best results out of Claude 3.5 Sonnet or GPT-4o, follow these rules:

  • Be Specific: Tell the model what it should not do. For example, “Never use placeholder code blocks.”
  • Define Formatting: Instruct the agent on how to output information (e.g., “Always format refactoring summaries as Markdown tables showing before and after states”).
  • Integrate Project Context: Mention framework choices (e.g., “This project uses Next.js 14 App Router, Tailwind CSS, and TypeScript. Ensure all new components follow these conventions”).
  • Error Handling: Instruct the agent on how to handle failures (e.g., “If a build command fails, analyze the error output and propose a fix instead of asking the user for help”).

Frequently Asked Questions

Where do I find the logs if my custom modes fail to load?

If your JSON has syntax errors, Roo Code will fall back to default modes. You can inspect the logs in VS Code by navigating to the “Output” panel and selecting “Roo Code” from the dropdown. Syntax errors like trailing commas or unescaped quotes will be printed there.

Can I run a custom mode with any LLM provider?

Yes, the mode system is independent of the model provider. However, agentic modes that use multiple tool groups (like read, write, and execute simultaneously) perform best on reasoning-heavy models such as Claude 3.5 Sonnet and GPT-4o. Smaller or local open-source models (see our Local LLM Setup Guide or DeepSeek-R1 Local Setup) may struggle with tool-use syntax in custom modes.

Can custom modes access MCP servers?

Yes, as long as the mcp group is added to the groups array in your roo_modes.json. This allows custom modes to communicate with external databases, APIs, or local dev tools that you have exposed via MCP.

How do I override default modes (Code, Architect, Ask)?

You cannot delete the default modes, but you can define custom modes with different names and set them as your default workspace options. If you want to customize the instructions of default modes, you can use the workspace settings.json file to pass custom instructions directly to the default slugs.

Can I share custom modes between VS Code and Cursor?

Roo Code is a VS Code extension, so it runs inside standard VS Code and forks like Cursor. As long as you install the Roo Code extension in Cursor, it will look for the configuration file in the same global and workspace storage directories.

Actionable Conclusion

Setting up custom modes optimizes your development velocity and keeps your workspace safe. Follow this implementation checklist to get started today:

  1. Audit current tasks: Identify the repetitive tasks you delegate to AI (e.g., writing tests, refactoring, documentation).
  2. Create config: Write a .vscode/roo_modes.json file in your main project repository.
  3. Start conservative: Restrict tool groups for experimental personas (e.g., omit the execute group for refactoring agents).
  4. Commit to Git: Share the configuration file with your team via version control to ensure standard coding workflows across your codebase.