Claude Code to Kilo Code migration guide (2026)

# 1. Install the surfaces you use
npm install -g @kilocode/cli
code --install-extension kilocode.Kilo-Code
# JetBrains: Settings -> Plugins -> Marketplace -> "Kilo Code"

# 2. Authenticate. Do not reuse Claude Code credentials.
kilo auth login
kilo config check

# 3. Pull a Claude Code session across, if you want the history
kilo
# /new
# /resume-claude

# 4. Translate config. Paste the migration prompt below into Kilo and let it do the work.

# 5. Verify
kilo debug config
kilo agent list
kilo debug skill
kilo mcp list

You are migrating this project from Claude Code to Kilo Code. Work in three phases.
Do not skip phase 2. Do not write any file before I approve the plan.

## Ground rules

- Read-only until I approve. Phase 1 and 2 are inventory and questions only.
- Never delete, move, or edit anything under `.claude/`, `~/.claude/`, `~/.claude.json`,
  or `CLAUDE.md`. Copy and translate, never cut.
- Never copy credentials. If you find API keys, OAuth tokens, or secrets in
  `~/.claude.json`, `.claude/settings*.json`, `.mcp.json`, or anywhere else, do not
  carry them into Kilo config and do not print them. Just note that the server or
  provider needs re-authentication.
- Never put a secret in a Kilo config file. Use `{env:VAR_NAME}` references, and tell
  me which environment variables I need to set.
- If a Claude Code feature has no Kilo equivalent, say so plainly and list it in an
  unmigrated section. Don't approximate it silently.
- Use the real Kilo schema. If you're unsure of a key, check the `$schema` at
  https://app.kilo.ai/config.json rather than guessing.

## Phase 1 - Inventory (read only)

Read whichever of these exist. Report which were found and which were absent.

Project scope, relative to the repo root:
  CLAUDE.md
  CLAUDE.local.md
  .claude/CLAUDE.md
  .claude/settings.json
  .claude/settings.local.json
  .claude/rules/**/*.md
  .claude/agents/**/*.md
  .claude/skills/*/SKILL.md          (and any bundled files in those skill dirs)
  .claude/commands/**/*.md
  .claude/output-styles/*.md
  .claude/hooks/**
  .claude/workflows/*.js
  .mcp.json
  .worktreeinclude
  Any CLAUDE.md files in subdirectories

User scope, in my home directory:
  ~/.claude/CLAUDE.md
  ~/.claude/settings.json
  ~/.claude/rules/**/*.md
  ~/.claude/agents/**/*.md
  ~/.claude/skills/*/SKILL.md
  ~/.claude/commands/**/*.md
  ~/.claude/output-styles/*.md
  ~/.claude.json                     (read the mcpServers key and the settings-shaped
                                      keys only - ignore transcripts, caches, and the
                                      OAuth session)

Also read anything that already exists on the Kilo side so you don't clobber it:
  kilo.jsonc, kilo.json, .kilo/kilo.jsonc, .kilo/kilo.json
  .kilo/agents/, .kilo/commands/, .kilo/skills/, .kilo/rules/
  ~/.config/kilo/kilo.jsonc and the same subdirectories there

Then print an inventory table: source file, what it contains in one line, and the
Kilo destination you propose. Flag every item you can't map.

## Phase 2 - Ask me these, then stop

Ask all of the questions below that apply, numbered, in one message. Give me your
recommended default for each so I can reply "defaults except 4 and 7". Then wait.

1. SCOPE. Migrate this repo only, or this repo plus my user-level `~/.claude/`
   config into `~/.config/kilo/`?

2. INSTRUCTIONS. Kilo loads `AGENTS.md` from the project root automatically. It does
   not load `CLAUDE.md` unless I point at it. Which do you want:
   (a) copy CLAUDE.md to AGENTS.md and leave CLAUDE.md in place for Claude Code,
   (b) create AGENTS.md as the source of truth and leave a one-line CLAUDE.md that
       imports it with `@AGENTS.md` so both tools stay in sync,
   (c) leave CLAUDE.md alone and add `"instructions": ["CLAUDE.md"]` to kilo.jsonc.
   Tell me which one keeps both tools working during a parallel-run period.

3. PATH-SCOPED RULES. For each `.claude/rules/*.md` file that has `paths:` frontmatter,
   Kilo has no glob-triggered rule loading. Show me the list of those files with their
   globs, and for each ask whether to:
   (a) load it unconditionally via the `instructions` array in kilo.jsonc,
   (b) convert it to a per-directory `AGENTS.md` in the directory its globs mostly
       cover (Kilo loads those on demand when the agent reads files there),
   (c) convert it to a skill with a description that says when it applies,
   (d) fold it into the root AGENTS.md,
   (e) drop it.
   Rules with no `paths:` frontmatter go into `instructions` - confirm that's fine.

4. SKILLS. Kilo can read `.claude/skills/` as a compatibility directory. Do you want to
   (a) leave the skills where they are and rely on that, or
   (b) copy them into `.kilo/skills/` so they don't depend on the compat path?
   If (a), check whether the compat directory is actually active in my current setup
   before we rely on it - run `kilo debug skill` and show me whether the Claude Code
   skills appear in the list.
   Either way, flag any SKILL.md whose `name` frontmatter doesn't match its directory
   name, and any skill using `disable-model-invocation`, `user-invocable`,
   `allowed-tools`, or `hooks` frontmatter, since Kilo's skill spec doesn't use those.

5. SUBAGENTS - MODELS. List each `.claude/agents/*.md` with its `model:` value. For each,
   should the Kilo agent inherit the session model, or pin a specific one? If pinning,
   run `kilo models anthropic` (and any other provider I use) and show me the exact
   `provider/model-id` strings before you write them, because Claude Code aliases like
   `sonnet` and `opus` are not valid Kilo model IDs.

6. SUBAGENTS - PERMISSIONS. Claude Code agents use `tools:` allowlists and
   `disallowedTools:` denylists. Kilo agents use a `permission` map over
   bash / edit / read / glob / grep / webfetch / task / websearch / todowrite / lsp / skill.
   Show me your proposed translation per agent as a table before writing. For a
   read-only Claude Code agent (`tools: Read, Grep, Glob`), propose `edit: deny` and
   `bash: deny` and let me confirm. Flag any agent using `memory:`, `isolation:`,
   `skills:`, `hooks:`, `maxTurns`, or `permissionMode` and tell me what's lost.

7. PERMISSIONS BASELINE. Two options for the top-level `permission` block:
   (a) strict start - `"*": "ask"` with a small explicit allow list, loosened after
       I've watched it for a few days,
   (b) port my Claude Code allow/deny lists as literally as they translate.
   Whichever I pick, remember Kilo evaluates permission patterns with the LAST matching
   rule winning, so `"*"` goes first and specifics go after. Show me the resulting
   block before writing it. Convert `Read(./.env)`-style deny rules into both a
   `permission.read` deny entry and a `.kilocodeignore` entry, and tell me the
   difference between the two.

8. MCP SERVERS. List every server in `.mcp.json` and in the `mcpServers` key of
   `~/.claude.json`, with transport type. For each, ask: port it or drop it, and
   project-scope or global-scope. Important: `{env:VAR}` references only resolve in
   trusted config - my global `~/.config/kilo/kilo.jsonc` - not in a project-level
   kilo.jsonc. So any server that needs a secret from the environment should go global.
   Say so for each affected server rather than writing a project entry that will
   silently fail to interpolate.

9. HOOKS. For every hook in `.claude/settings.json`, `.claude/settings.local.json`, and
   `~/.claude/settings.json`, print a table: event, matcher, what the command does,
   and my options. Kilo has no shell-command hook system. For each hook ask whether to:
   (a) express it as a Kilo permission rule, if it's a PreToolUse deny gate,
   (b) rewrite it as a Kilo plugin - a TypeScript module in `.kilo/plugin/` using
       `tool.execute.before` / `tool.execute.after` / `chat.message` / `permission.ask`
       / the `event` hook,
   (c) move it into my own git hooks or CI, if it's a formatter or linter,
   (d) drop it.
   Don't write any plugin until I've picked (b) for a specific hook. When I do, write
   one file per hook in `.kilo/plugin/`, and tell me it needs `bun install` support via
   a `.kilo/package.json` if it imports anything.

10. AUTO MEMORY. If `~/.claude/projects/<this project>/memory/MEMORY.md` exists, Kilo has
    no equivalent auto-memory store. Do you want me to read it and propose a short set
    of durable facts to add to AGENTS.md, or leave it alone? If proposing, show me the
    diff - don't append raw memory notes into a file the whole team reads.

11. COMMANDS. `.claude/commands/*.md` map to `.kilo/commands/*.md`, and any
    `.claude/skills/*/SKILL.md` that Claude Code exposes as `/name` maps there too.
    Flag every command that uses `$ARGUMENTS`, `$0`/`$1` positional args, shell
    injection, or `argument-hint`, and tell me which of those Kilo supports in
    commands before we rely on them.

12. OUTPUT STYLES. If `.claude/output-styles/` or `~/.claude/output-styles/` has files,
    propose turning each into either a Kilo primary agent with a custom `prompt`, or an
    entry in `instructions`. Ask which per file.

13. GIT. Should the new `.kilo/` directory and `kilo.jsonc` be committed, and do you
    want `.gitignore` entries for anything personal? Propose the entries; don't write
    them yet.

## Phase 3 - Write, after approval only

Apply exactly what I approved. Nothing else. Then:

- Show me a diff or a file-by-file list of everything you created or changed.
- Run `kilo config check` and paste the output verbatim.
- Run `kilo debug config` and confirm the instructions, mcp, permission, and agent
  keys resolved the way we intended.
- Run `kilo agent list` and confirm every migrated agent appears with the mode and
  permissions we agreed.
- Run `kilo debug skill` and confirm every skill I expect is discoverable.
- If we ported MCP servers, run `kilo mcp list` and tell me which need
  `kilo mcp auth <name>` or an environment variable before they'll connect.

Finish with two lists:

  MIGRATED - one line each, source -> destination.
  NOT MIGRATED - everything with no Kilo equivalent, what it did in Claude Code, and
  what I'd have to build to get it back. Be specific; I'd rather know now.

{
  "permission": {
    "external_directory": { "~/.claude/**": "allow" }
  }
}

npm install -g @kilocode/cli
kilo --version

code --install-extension kilocode.Kilo-Code

kilo auth login
kilo config check

/new
/resume-claude

@AGENTS.md

{
  "instructions": ["CLAUDE.md", ".claude/rules/*.md"]
}

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob
model: sonnet
---

You are a senior code reviewer...

---
description: Reviews code for quality and best practices
mode: subagent
permission:
  edit: deny
  bash: deny
---

You are a senior code reviewer...

kilo debug skill

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": { "NOTION_TOKEN": "${NOTION_TOKEN}" }
    }
  }
}

{
  "mcp": {
    "notion": {
      "type": "local",
      "command": ["npx", "-y", "@notionhq/notion-mcp-server"],
      "environment": { "NOTION_TOKEN": "{env:NOTION_TOKEN}" },
      "enabled": true
    }
  }
}

{
  "permissions": {
    "allow": ["Bash(npm test *)", "Bash(git diff *)"],
    "deny": ["Bash(rm -rf *)", "Read(./.env)"]
  }
}

{
  "$schema": "https://app.kilo.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": {
      "*": "ask",
      "npm test*": "allow",
      "git diff*": "allow",
      "rm *": "deny"
    },
    "edit": {
      "*": "ask",
      ".env*": "deny"
    }
  }
}

// .kilo/plugin/env-guard.ts
import type { Plugin } from '@kilocode/plugin';

const EnvGuard: Plugin = async () => ({
  'tool.execute.before': async (input, output) => {
    if (input.tool === 'read' && String(output.args.filePath).includes('.env')) {
      throw new Error('reading .env files is blocked');
    }
  },
});

export default { id: 'env-guard', server: EnvGuard };