# Roo Code Integration

AVELIN API works with [Roo Code](https://github.com/RooVetGit/Roo-Code) — a powerful autonomous AI coding agent that lives inside VS Code. Roo Code can create and edit files, run terminal commands, search codebases, use the browser, and work through complex multi-step tasks autonomously. It supports multiple operating modes (Code, Architect, Ask, Debug) and integrates deeply with your development workflow.

> **Why AVELIN + Roo Code?** Roo Code's autonomous agentic loops demand reliable tool calling, massive context windows, and fast inference — AVELIN delivers all three with 1M-token contexts, ~100 tps throughput, and automatic failover across frontier models.

---

## Quick Setup

### Step 1: Get your AVELIN API key

Sign up at [avelin.ai](https://avelin.ai) and generate an API key. It will look like `sk-ave...xxxx`.

### Step 2: Install Roo Code

1. Open VS Code
2. Go to the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for **Roo Code**
4. Click **Install**

### Step 3: Configure Roo Code

1. Open the Roo Code panel (click the Roo icon in the sidebar)
2. Click the settings/gear icon
3. In the **API Provider** dropdown, select **OpenAI Compatible**
4. Enter your settings:

| Field | Value |
|---|---|
| **Base URL** | `https://api.avelin.ai/v1` |
| **API Key** | `sk-ave...xxxx` |
| **Model ID** | `avelin-coding-pro` |
| **Max Tokens** | `65536` |

5. Click **Done** or save your configuration

Alternatively, Roo Code also supports the **Anthropic** API format:

| Field | Value |
|---|---|
| **API Provider** | Anthropic |
| **Base URL** | `https://api.avelin.ai` |
| **API Key** | `sk-ave...xxxx` |
| **Model ID** | `avelin-coding-pro` |
| **Max Tokens** | `65536` |

We recommend the **OpenAI Compatible** provider for Roo Code — it provides the broadest model compatibility and reliable streaming.

### Step 4: Select Your Model

In the Roo Code panel, choose your model from the dropdown. Start with `avelin-coding-pro` for the best balance of speed, context, and reasoning capability.

---

## Recommended Models

### Primary Recommendation: `avelin-coding-pro`

For autonomous coding workflows with Roo Code:

| Feature | avelin-coding-pro | Why it matters for Roo Code |
|---|---|---|
| **Context window** | **1M tokens** | Roo accumulates context across file reads, terminal output, and browser actions |
| **Max output** | **65K tokens** | Large file edits and comprehensive multi-step plans |
| **Throughput** | **~100 tokens/sec** | 2× faster than standard tiers — Roo loops complete faster |
| **Reasoning** | Deep step-by-step thinking | Better autonomous decision-making in complex tasks |
| **Tool calling** | First-class support | Roo relies on reliable structured tool calls for file ops, terminal, and search |

### Alternative Models

| Model | When to use |
|---|---|
| `avelin-agentic-pro` | Long autonomous workflows — optimized for multi-step agentic loops |
| `avelin-coding-ultra` | Complex refactors, architecture changes, system design |
| `avelin-coding-fast` | Lighter tasks, quick fixes — saves cost on simple work |
| `avelin-fast` | Quick lookups and simple tasks — lowest cost, fastest response |

**Tip:** Use `avelin-agentic-pro` when running Roo Code in fully autonomous mode with auto-approve enabled. It's specifically tuned for extended tool-use chains.

---

## Why AVELIN for Roo Code?

### 1. Cost Optimization

Roo Code's autonomous loops can consume significant tokens across many tool calls and context accumulations. AVELIN optimizes costs:

- **Prompt caching**: ~80% cost reduction on repeated system prompts and instructions
- **Competitive pricing**: Lower per-token costs than direct provider APIs
- **Pay-per-token**: No subscription lock-in or seat limits

### 2. Model Diversity

Access multiple frontier coding models through a single API key:

- Switch between reasoning-heavy and fast models depending on task complexity
- Use `avelin-coding-ultra` for planning mode, `avelin-coding-pro` for execution
- AVELIN automatically routes to the best available backend

### 3. Reliability

Roo Code runs long autonomous sessions that can't afford mid-task failures:

- **Automatic failover**: If one backend is slow or unavailable, AVELIN switches to another
- **Retry logic**: Transient errors are handled automatically
- **99.9% uptime**: Enterprise-grade infrastructure

### 4. 1M Context Windows

Roo Code sessions accumulate context quickly — every file read, terminal output, search result, and browser interaction adds tokens. AVELIN's 1M-token context windows mean longer autonomous sessions without context truncation or task restarts.

---

## Example Workflows

### Autonomous Feature Development

```
Roo Code Panel:

You> Add user authentication to the Express app. Include JWT tokens,
     bcrypt password hashing, protected routes, and tests.

Roo: I'll implement authentication for your Express app. Let me start
     by examining the project structure.

[Reads package.json, src/index.ts, src/routes/]

I can see this is an Express app with TypeScript. Here's my plan:
1. Add User model and migration
2. Create auth middleware with JWT verification
3. Add /auth/register and /auth/login endpoints
4. Protect existing routes with auth middleware
5. Write integration tests

Let me implement each step...

[Creates src/models/User.ts]
[Creates src/middleware/auth.ts]
[Creates src/routes/auth.ts]
[Updates src/index.ts to register routes]
[Creates tests/auth.test.ts]
[Runs npm test — all tests pass]

Done! I've implemented:
- User model with bcrypt password hashing
- JWT generation and verification middleware
- /auth/login and /auth/register endpoints
- Protected route middleware
- 8 passing integration tests
```

### Multi-File Refactoring

```
You> @src/services/ Refactor all services to use dependency injection
     instead of direct database imports.

Roo: Let me analyze the current service structure...

[Reads all files in src/services/]
[Identifies 6 services with direct DB imports]

I'll refactor each service to accept dependencies through constructors.
This will improve testability and reduce coupling.

[Updates src/services/userService.ts]
[Updates src/services/orderService.ts]
[Updates src/services/paymentService.ts]
[Updates src/services/notificationService.ts]
[Creates src/container.ts for DI setup]
[Updates tests for new constructor signatures]
[Runs test suite — all passing]
```

### Debug and Fix Workflow

```
You> The API returns 500 errors on the /orders endpoint when
     the request body contains special characters in the address.

Roo: Let me investigate this issue.

[Reads src/routes/orders.ts]
[Reads src/validators/orderValidator.ts]
[Checks error logs via terminal]
[Reproduces the error with a test request]

Found it — the address validation regex doesn't handle Unicode
characters, causing an unhandled exception. Let me fix this:

[Updates validator with proper Unicode regex]
[Adds test cases for international addresses]
[Runs tests — all passing]

The issue was in the address validation regex at line 42.
Fixed and added 5 test cases covering international addresses.
```

---

## Advanced Configuration

### Roo Code Modes

Roo Code supports multiple operating modes, each suited to different tasks:

| Mode | Description | Recommended Model |
|---|---|---|
| **Code** | Full autonomous coding — reads, writes, runs terminal | `avelin-coding-pro` |
| **Architect** | Plans and designs without executing changes | `avelin-coding-ultra` |
| **Ask** | Questions and explanations without file changes | `avelin-fast` |
| **Debug** | Focused debugging and error resolution | `avelin-coding-pro` |

Switch modes from the Roo Code panel to match your current task. Use Architect mode for planning, then switch to Code mode for implementation.

### Custom Instructions

Add project-specific instructions in Roo Code's settings panel:

```
You are working on a Python FastAPI application.
Follow these conventions:
- Use Pydantic v2 models for request/response schemas
- Use async/await for all database operations with SQLAlchemy 2.0
- Write tests using pytest with httpx AsyncClient
- Follow repository pattern for data access
- Include type hints on all function signatures
```

### Context Management

Roo Code can consume large amounts of context during autonomous sessions:

- **Start new tasks** for unrelated work to reset context
- **Use @-mentions** to include specific files instead of letting Roo search broadly
- **Enable auto-condense** in Roo settings to summarize old context automatically
- **Monitor token usage** in the Roo Code status bar to stay within context limits

With AVELIN's 1M-token context window, you can handle significantly larger sessions before needing to reset.

### Auto-Approve Settings

For trusted projects, enable auto-approve to let Roo Code work without interruptions:

1. Open Roo Code settings
2. Enable **Auto-approve file edits**
3. Enable **Auto-approve terminal commands**
4. Optionally set **command deny list** for dangerous commands (e.g., `rm -rf`, `DROP TABLE`)

---

## Troubleshooting

| Issue | Solution |
|---|---|
| **"Model not found"** | Ensure the model name is exactly as listed (e.g., `avelin-coding-pro`) |
| **"API key invalid"** | Verify your AVELIN API key starts with `sk-ave` and is correctly entered |
| **Tool calls failing** | Use `avelin-coding-pro` or `avelin-agentic-pro` — these have first-class function calling |
| **Slow responses** | Try `avelin-fast` for quicker responses on simple tasks |
| **Context too long errors** | Start a new Roo task to reset context, or enable auto-condense |
| **Streaming not working** | Ensure streaming is enabled in Roo Code settings; both API formats support it |
| **Roo loops endlessly** | Add clearer task descriptions, or switch to `avelin-coding-pro` for better reasoning |
| **Connection timeout** | Check your network; AVELIN has automatic failover but verify base URL is correct |

---

## Related

- [API Quickstart](../../api/quickstart.md) — First API call in 5 minutes
- [Cline Guide](cline.md) — Similar VS Code autonomous agent
- [Cursor Guide](cursor.md) — AI-first code editor
- [Hermes Agent Guide](../hermes.md) — Terminal-based agentic coding tool
- [Claude Code Guide](claude-code.md) — Anthropic's CLI tool
- [Model Catalog](../../models/README.md) — Full model comparison
- [Roo Code GitHub](https://github.com/RooVetGit/Roo-Code) — Official Roo Code repository