Roo Code Setup Guide

Roo Code AI Assistant: Complete Setup Guide

Roo Code is a free, open-source AI coding assistant for Visual Studio Code that excels in flexibility and customization. Built as a fork of the Cline project with significant enhancements, Roo Code supports multiple AI modes, extensive tool integration through MCP, and works with virtually any AI model provider. This guide walks you through setup, configuration, and effective usage.

Installation

1. Open Visual Studio Code.
2. Navigate to the Extensions panel (Cmd+Shift+X or Ctrl+Shift+X).
3. Search for "Roo Code" (previously known as Roo-Cline).
4. Click Install.
5. After installation, the Roo Code icon appears in the VS Code sidebar. Click it to open the configuration panel.

Configuring Your API Provider

Roo Code supports a wide range of API providers. Here are the most common configurations:

Option 1: OpenAI Compatible (Most Flexible)

The OpenAI Compatible option works with relay services, alternative providers, and self-hosted models:

Provider: OpenAI Compatible
Base URL: https://claude4u.com/v1
API Key:  cr_your-relay-api-key
Model ID: claude-sonnet-4-20250514

Option 2: Anthropic (Direct)

Provider: Anthropic
API Key:  sk-ant-your-anthropic-key
Model:    claude-sonnet-4-20250514

Option 3: Google Gemini

Provider: Google Gemini
API Key:  your-gemini-api-key
Model:    gemini-2.5-flash

Option 4: Local Models via Ollama

Provider: Ollama
Base URL: http://localhost:11434
Model:    deepseek-coder-v2:latest

Understanding Roo Code Modes

One of Roo Code's standout features is its mode system. Each mode defines a specialized AI persona with different capabilities and permissions:

• Code mode: The default mode for writing and editing code. Has full file system and terminal access.
• Architect mode: Focuses on high-level design and planning. Analyzes project structure and suggests architectural improvements without making direct code changes.
• Ask mode: A read-only mode for asking questions about your codebase. Cannot modify files or run commands.
• Debug mode: Specialized for troubleshooting issues. Focuses on analyzing error messages, logs, and tracing bugs through the code.

You can switch modes using the mode selector in the Roo Code panel. Each mode can be configured with different models — for example, using a cheaper model for Ask mode and a more capable one for Code mode.

Custom Modes

Roo Code allows you to create custom modes with specific instructions, tool permissions, and model assignments:

// Example custom mode configuration in .roo/modes.json
{
  "customModes": [
    {
      "slug": "reviewer",
      "name": "Code Reviewer",
      "roleDefinition": "You are a senior code reviewer. Analyze code for bugs, security issues, performance problems, and adherence to best practices.",
      "groups": ["read"],
      "customInstructions": "Focus on security vulnerabilities and performance anti-patterns."
    }
  ]
}

Project Configuration

Create a .roo/ directory in your project root for project-specific settings:

• .roo/rules/ — Custom instructions that apply across all modes
• .roo/rules-code/ — Instructions specific to Code mode
• .roo/rules-architect/ — Instructions specific to Architect mode
• .roo/modes.json — Custom mode definitions

// .roo/rules/project-conventions.md
# Project Conventions
- Use TypeScript strict mode
- Follow the repository pattern for data access
- All API endpoints must have input validation using Zod
- Error responses follow RFC 7807 Problem Details format
- Write unit tests for all new business logic

MCP Tool Integration

Roo Code has robust support for MCP (Model Context Protocol) tools, extending its capabilities beyond file editing and terminal commands:

• Database tools: Query databases directly from the AI agent
• API testing tools: Test endpoints and inspect responses
• Documentation tools: Access external documentation within the AI context
• Browser tools: Inspect and test web applications

Effective Usage Patterns

1. Start with Architect mode for complex tasks. Plan the approach, then switch to Code mode for implementation.
2. Use Ask mode for exploration. When you need to understand unfamiliar code, Ask mode is fast and read-only.
3. Write detailed task descriptions. Specify the files involved, the expected behavior, edge cases, and testing requirements.
4. Review every change. Roo Code shows diffs before applying changes — always review them.
5. Use custom modes for repetitive workflows like code review, documentation writing, or test generation.

Cost Management

Roo Code displays real-time token usage and cost estimates. To optimize costs:

• Use lighter models (Gemini Flash, Claude Haiku) for simple tasks and Ask mode
• Reserve premium models (Claude Sonnet/Opus, Gemini Pro) for complex coding tasks
• Configure different models per mode to automatically use the right model for each task type
• Use a relay service for detailed cost tracking and budget alerts