Roo Code to Kilo Code Migration Guide (2026)

Matt Rubens announced on April 21, 2026 that Roo Code is shutting down. The RooCodeInc/Roo-Code repo archives on May 15. In his words: "Roo Code hit 3 million installs. We're shutting it down to go all-in on Roomote."

Three million developers need a new agent. If you're one of them, this post is for you.

We started Kilo as a Roo fork in 2025. The two codebases share real git history. That means most of what you used in Roo is in Kilo: custom modes, project rules, MCP support, diff-based edits, real command execution. A few things changed, and the rest of this post covers what.

This is the migration path to the new Kilo Code VS Code extension, which we rebuilt on OpenCode server and shipped GA on April 2. A legacy v5.x Kilo extension still ships the Roo-derived codebase. We cover how to pin it at the end if you need Orchestrator mode or the old Memory Bank.

The short version

# 1. Install
code --install-extension kilocode.Kilo-Code

# 2. Port project files (run in each repo with Roo config)
mv .roorules AGENTS.md
[ -d .roo/rules ] && mkdir -p .kilo/rules && cp -r .roo/rules/* .kilo/rules/
[ -f .roomodes ] && cp .roomodes .kilocodemodes
[ -f .roo/mcp.json ] && mkdir -p .kilocode && cp .roo/mcp.json .kilocode/mcp.json

# 3. Launch VS Code. Our migration wizard converts legacy files.
# 4. Re-authenticate providers. (API keys don't carry over from Roo's SecretStorage.)

What breaks: API key storage, Orchestrator mode, codebase indexing.

What we added: parallel subagents, an Agent Manager with git worktrees, Auto Models, Stick Models, Autocomplete, and shared sessions between CLI and VS Code.

The shutdown, briefly


Announcement	Matt Rubens on X, April 21, 2026
Stated reason	Pivot to Roomote, Roo's cloud agent
Repo archive date	May 15, 2026
License	Apache-2.0. BYOK continues working after archive.
Migration recommendation from Roo	None published
Community discussion	Hacker News
Our response	"Thank you, Roo!"

The Roo team deliberately chose to focus on their cloud product and that's a fair move. As a result, you need a working agent in your editor by May 15.

Why we rebuilt, and what that means for you

We shipped the rebuilt extension as a public beta on March 10 and went GA on April 2. Since GA, we've merged 188 PRs of our own and pulled 21 upstream OpenCode releases.

We rebuilt because the old extension (the Roo-derived codebase) had VS Code internals included in every surface. That capped what we could ship. The CLI and Cloud Agents had to reimplement too much. We moved everything onto OpenCode server, a shared engine that runs the same agent loop whether you invoke it from CLI, VS Code, or Cloud Agents. Your kilo.jsonc is shared across them. Sessions carry between them.

That rebuild changed four things you'll feel as a migrator:

Permissions replaced tool groups. Roo's read/edit/browser/command/mcp groups are gone. We use explicit allow/ask/deny rules with glob patterns. Similar control, different mental model.

Checkpoints moved out of your repo. Snapshots live at ~/.local/share/kilo/snapshot/<project-id>/<worktree-hash>/ in a detached worktree. The nested-.git bug that hit some Roo users is gone. Checkpoints are taking every user message instead of every agent action (turn vs step), to better support large repositories.

Execution is parallel. Tool calls (file reads, greps, shell commands) run concurrently. Full-tool agents can spawn subagents that work on separate pieces at the same time. Our Agent Manager runs each chat in its own git worktree, so parallel agents don't step on each other's files.

Three features we added that Roo didn't ship. Sticky Models pin a model per agent. Autocomplete does inline autocomplete. Sessions move between CLI and VS Code because both hit the same engine. Auto Models make model selection easy, automatically using the best model at a given price point.

File and config mapping

Roo path or concept	New Kilo equivalent	How to migrate
`.roorules`	`AGENTS.md` at project root	Rename. AGENTS.md is an open standard Cursor and Windsurf also read.
`.roorules-{slug}`	Markdown body of `.kilo/agents/{slug}.md` (below the YAML frontmatter)	Paste the rules content into the body of the matching agent file, below the --- block
`.roo/rules/*.md`	`.kilo/rules/*.md` (referenced from `kilo.jsonc`)	Copy. We also read `.kilocode/rules/` as a fallback.
`.roo/rules-{slug}/*.md`	Markdown body of `.kilo/agents/{slug}.md`	Concatenate the files and append to the agent's markdown body
`.rooignore`	`.kilocodeignore`	Rename
`.roomodes` (YAML)	`.kilo/agents/*.md` (Markdown + YAML frontmatter)	Copy to `.kilocodemodes`; our wizard converts on launch
`custom_modes.yaml` (global)	Markdown agent files in our globalStorage	Wizard converts automatically
`.roo/mcp.json`	`mcp` key in `kilo.jsonc`, or `.kilocode/mcp.json`	Copy to `.kilocode/mcp.json`; wizard migrates
`mcp_settings.json` (global)	Merged into `~/.config/kilo/kilo.jsonc`	Copy the file or re-add servers in Settings
Memory Bank (`.kilocode/rules/memory-bank/`)	`AGENTS.md`	Concatenate manually, or ask the agent to do it
Tool groups (`read`, `edit`, `browser`, `command`, `mcp`)	`permission` key with `allow`/`ask`/`deny` + globs	Rewrite (example below)
In-repo `.git` checkpoints	Snapshots at `~/.local/share/kilo/snapshot/`	Automatic; fresh snapshots start on first run
VS Code Marketplace ID	`RooVeterinaryInc.roo-cline` → `kilocode.Kilo-Code`	Install fresh
On-disk extension folder	`rooveterinaryinc.roo-cline/` → `kilocode.kilo-code/`	Automatic
Command namespace	`roo-cline.` → `kilo-code.`	Find-and-replace in `keybindings.json`
API keys (VS Code SecretStorage)	`~/.config/kilo/auth.json`	Re-authenticate manually. Keys don't port.

VSCode global storage paths, for reference:

OS	Path
macOS	`~/Library/Application Support/Code/User/globalStorage/`
Linux	`~/.config/Code/User/globalStorage/`
Windows	`%APPDATA%\Code\User\globalStorage\`

Feature mapping

Roo Code	New Kilo Code
Code, Ask, Debug modes	`code`, `ask`, `debug` agents (built-in)
Architect mode	`plan` agent
Orchestrator / Boomerang Tasks	Native subagent delegation from any full-tool agent
Custom modes (YAML)	Custom agents (Markdown with YAML frontmatter)
Tool groups per mode	`permission` rules per agent (globs + allow/ask/deny)
Memory Bank	`AGENTS.md` (open standard)
Per-task model override	Sticky Models (pinned per agent)
Single chat session	Agent Manager with multi-tab, parallel, worktree-isolated chats. Single chat sessions also available.
No inline completion	Ghost inline autocomplete
Codebase indexing via embeddings	Not yet ported. PR #6966 in review.
MCP (stdio, Streamable HTTP, SSE)	Same. We try Streamable HTTP first, fall back to SSE.
Per-mode custom instructions	Per-agent system prompt in Markdown
Model picker	Fuzzy model search over 500+ models via Kilo Gateway
Roo Code Router (at-cost curated)	Kilo Gateway (zero markup, free BYOK, Kilo Pass on top if you want hosted credits)

Providers work the same in both: OpenRouter, Anthropic direct, OpenAI, Gemini, DeepSeek, Mistral, AWS Bedrock, Ollama, LM Studio, LiteLLM, Groq, xAI and more.

Migration, step by step

Budget 15 to 30 minutes depending on how much custom config you have.

1. Install

code --install-extension kilocode.Kilo-Code

The extension ID on the VS Code Marketplace is kilocode.Kilo-Code. On disk it's kilocode.kilo-code.

For Cursor, VSCodium, or Windsurf, substitute the binary (cursor --install-extension, codium --install-extension with Open VSX configured).

JetBrains users: install from the plugin marketplace. Requires Node.js LTS and JetBrains Toolbox for OAuth. (Note Jetbrains is still using our v5 codebase, and is actively being ported to v7)

2. Back up your Roo config

# macOS
cp -R "$HOME/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline" \
      "$HOME/roo-backup-$(date +%Y%m%d)"

# Linux
cp -R "$HOME/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline" \
      "$HOME/roo-backup-$(date +%Y%m%d)"

PowerShell:

Copy-Item "$env:APPDATA\Code\User\globalStorage\rooveterinaryinc.roo-cline" `
          "$HOME\roo-backup-$(Get-Date -Format yyyyMMdd)" -Recurse

3. Port workspace files

Run in each repo that has Roo config:

# Project rules → AGENTS.md (project-wide, read every session)
[ -f .roorules ] && mv .roorules AGENTS.md

# Per-folder rules
if [ -d .roo/rules ]; then
  mkdir -p .kilo/rules
  cp -r .roo/rules/* .kilo/rules/
fi

# Project custom modes (wizard converts .kilocodemodes to .kilo/agents/*.md)
# Per-mode rules under .roo/rules-{slug}/ get appended to the agent markdown
# body in step 5a, after the wizard creates .kilo/agents/{slug}.md.
[ -f .roomodes ] && cp .roomodes .kilocodemodes

# MCP project config
if [ -f .roo/mcp.json ]; then
  mkdir -p .kilocode
  cp .roo/mcp.json .kilocode/mcp.json
fi

# Ignore file
[ -f .rooignore ] && cp .rooignore .kilocodeignore

PowerShell equivalents:

if (Test-Path .roorules) { Rename-Item .roorules AGENTS.md }
if (Test-Path .roo\rules) {
  New-Item -ItemType Directory -Force .kilo\rules | Out-Null
  Copy-Item .roo\rules\* .kilo\rules\ -Recurse -Force
}
# Per-mode rules under .roo\rules-{slug}\ are appended in step 5a.
if (Test-Path .roomodes) { Copy-Item .roomodes .kilocodemodes }
if (Test-Path .roo\mcp.json) {
  New-Item -ItemType Directory -Force .kilocode | Out-Null
  Copy-Item .roo\mcp.json .kilocode\mcp.json
}
if (Test-Path .rooignore) { Copy-Item .rooignore .kilocodeignore }

4. Copy global configs (optional)

If you maintained global custom modes or MCP servers in Roo, copy them before launching Kilo for the first time:

# macOS
SRC="$HOME/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings"
DST="$HOME/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings"
mkdir -p "$DST"
[ -f "$SRC/custom_modes.yaml" ] && cp "$SRC/custom_modes.yaml" "$DST/custom_modes.yaml"
[ -f "$SRC/mcp_settings.json" ] && cp "$SRC/mcp_settings.json" "$DST/mcp_settings.json"

Our CustomModesManager reads these files on first startup and auto-converts them into Markdown agent files.

5. Launch VS Code

Our migration wizard detects legacy Kilo files and converts them:

.kilocodemodes becomes .kilo/agents/*.md
Global custom_modes.yaml becomes Markdown agents in our globalStorage
.kilocode/mcp.json gets merged into kilo.jsonc under the mcp key
.kilocode/rules/ is preserved and read as a fallback

The wizard doesn't read Roo-prefixed files directly. That's why step 3 renames them first.

5a. Append per-mode rules to agent markdown bodies

Roo loads .roo/rules-{slug}/*.md automatically whenever mode {slug} runs. Kilo has no equivalent auto-loaded path — per-mode instructions live in the markdown body of .kilo/agents/{slug}.md. Run this after step 5, so the wizard has already created the agent files from .kilocodemodes:

for d in .roo/rules-*; do
  [ -d "$d" ] || continue
  slug="${d#.roo/rules-}"
  agent_file=".kilo/agents/$slug.md"
  if [ ! -f "$agent_file" ]; then
    echo "skipping $slug: $agent_file not found (check wizard output or create it manually)"
    continue
  fi
  {
    printf '\n\n'
    for f in "$d"/*.md; do
      [ -f "$f" ] || continue
      cat "$f"
      printf '\n'
    done
  } >> "$agent_file"
  echo "appended $d/*.md → $agent_file"
done

PowerShell:

Get-ChildItem -Directory .roo | Where-Object { $_.Name -like 'rules-*' } | ForEach-Object {
  $slug = $_.Name -replace '^rules-', ''
  $agentFile = ".kilo\agents\$slug.md"
  if (-not (Test-Path $agentFile)) {
    Write-Host "skipping ${slug}: $agentFile not found"
    return
  }
  Add-Content -Path $agentFile -Value ''
  Get-ChildItem "$($_.FullName)\*.md" | ForEach-Object {
    Add-Content -Path $agentFile -Value (Get-Content $_.FullName -Raw)
  }
  Write-Host "appended $($_.FullName) → $agentFile"
}

Do not place these files under .kilo/rules-{slug}/ — that path is not loaded by default, so the per-mode instructions would silently disappear.

6. Re-authenticate providers

This is the one real friction point in the migration. We store credentials at ~/.config/kilo/auth.json. We don't read Roo's VS Code SecretStorage entries. Re-auth once per provider.

From the sidebar: click the gear, go to Providers, add your key. Or from the CLI:

kilo auth login --provider anthropic
kilo auth login --provider openrouter

If you want managed credits instead of BYOK, our Kilo Gateway fronts 500+ models at zero markup. Kilo Pass sits on top at $19/mo Starter, $49/mo Pro, $199/mo Expert. As of publication, we're running a $20 first-top-up bonus and a Double Welcome Bonus through April 24, 2026.

7. Update keybindings

If you set custom keybindings for Roo, find-and-replace roo-cline. with kilo-code. in your keybindings.json. Command suffixes are identical: newTask, plusButtonClicked, addToContext, and so on.

8. Write a minimal `kilo.jsonc`

Project-level kilo.jsonc lives at the repo root or at .kilo/kilo.jsonc (the latter wins). Global is ~/.config/kilo/kilo.jsonc.

{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "anthropic/claude-sonnet-4.6",
  "permission": {
    "*": "ask",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm test*": "allow",
      "rm *": "deny"
    },
    "edit": {
      "*": "ask",
      ".env*": "deny"
    }
  },
  "instructions": [".kilo/rules/*.md"],
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  }
}

Validate it:

kilo config check

Common settings that are configured include:

9. Port a custom mode to a custom agent

A Roo read-only Review Mode in .roomodes might have looked like this:

customModes:
  - slug: reviewer
    name: Reviewer
    roleDefinition: You are a code review specialist. Read diffs, suggest changes.
    groups: [read, browser]

In the new Kilo, it becomes a Markdown file at .kilo/agents/reviewer.md:

---
description: Code review specialist, read-only
mode: primary
color: '#3B82F6'
permission:
  edit: deny
  bash:
    'git diff*': 'allow'
    'git log*': 'allow'
    '*': 'deny'
---

You are a code review specialist. Read diffs, comment on quality, suggest changes. Do not edit files.

It shows up in the agent cycle (Cmd+. / Ctrl+.) next to our built-ins.

10. Verify

Open a repo. Open a chat. Pick the code agent. Ask it to list custom agents and rules it has loaded. We'll report what we read from kilo.jsonc, AGENTS.md, and .kilo/agents/.

If the MCP panel shows servers as connected, that side of the migration is done.

Once Kilo works, disable Roo in the Extensions panel. Don't uninstall yet. VS Code's customStoragePath setting is reportedly broken in Roo (issue #3788), so some users have non-standard storage paths. Keep the extension disabled for a week as a fallback before uninstalling.

What we deprecated, and why

A few Roo patterns don't have a one-to-one match in the new extension. Here's the honest context on each.

Orchestrator mode. We deprecated it because full-tool agents (Code, Plan, Debug) can delegate to subagents natively. You describe the goal, the parent agent splits the work, subagents run in parallel. We found the explicit coordinator pattern added overhead without adding capability. One constraint we're still working on: subagents can't spawn subagents. Flat two-level hierarchy as of v7.2.10.

Memory Bank. We moved to AGENTS.md, which is an open standard Cursor and Windsurf also read. Existing Memory Bank files still work. We didn't break them. But if you're starting fresh, AGENTS.md is the way. Sub-directory AGENTS.md files are supported and take precedence for files under that directory. AGENTS.md is write-protected, so the agent can't modify it without your approval.

Built-in Review agent. Pick Code Reviewer from the agents list in the chat.

Built-in Architect agent. Use plan for architecture work.

Codebase indexing. Honest answer: we haven't ported it yet. Roo's Qdrant plus embeddings pipeline isn't in the new extension. Community PR #6966 is in review. Until it lands, use @file and @terminal context mentions, plus Local Recall, which searches past sessions across worktrees. If you depend on semantic codebase search, stay on legacy v5.x for now (see below).

API keys don't transfer. Already covered in step 6, but worth repeating: we re-auth once because Roo keeps keys in OS keychain via VS Code SecretStorage, and we keep them in ~/.config/kilo/auth.json.

Paid Roo Code Cloud Pro subscribers: Roo archiving the Roo Code repo, refunding any unused balances, and making the last extension release on May 15th. Rubens pointed users at Roomote. We can't speak to that.

If you need the old behavior, pin legacy Kilo v5.x

The legacy v5.x Kilo extension still ships the Roo-derived codebase with Orchestrator mode, Memory Bank, and Qdrant-based codebase indexing intact.

In the Extensions panel, click the gear icon on Kilo Code, then Install Specific Version.
Pick the latest 5.x release.
Disable auto-update on the extension.

You trade the new architecture (parallel subagents, Agent Manager worktrees, OpenCode core, shared sessions) for the old mental model. That's a reasonable call if your workflow depends on Memory Bank or Orchestrator and you don't want to rewrite.

Where to get help

kilo.ai/docs covers kilo.jsonc, agents, permissions, MCP, and AGENTS.md
Our Discord, #vscode channel, for live help and release notes
github.com/Kilo-Org/kilocode for issues and PRs. We pay $100 in credits for a merged bug-fix PR.
r/kilocode for longer-form discussion
blog.kilo.ai for release notes
hi@kilocode.ai for anything else

A note on Roo

We owe the Roo team real credit. The decisions they made early on (custom modes, the Architect/Code/Debug split, real command execution in the editor) shaped the category we all work in now. We built on their codebase. We're building on what they started.

If you're migrating, we're here. Welcome in.

Sources

Roo Code is shutting down. Here's how to move to Kilo (guide).