docs(kilo-docs): consolidate migration guides for Claude Code, Cline, and other tools#8280
docs(kilo-docs): consolidate migration guides for Claude Code, Cline, and other tools#8280kilo-code-bot[bot] wants to merge 4 commits intomainfrom
Conversation
Document migration paths from Claude Code, GitHub Copilot, and Aider. Highlights the Claude Code compatibility toggle from PR #8230 that controls loading CLAUDE.md instructions and .claude/skills/ into sessions.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
|
|
||
| # Migrating from Other Tools | ||
|
|
||
| This guide covers migrating to Kilo Code from AI coding tools not covered in our dedicated [Cursor/Windsurf](/docs/getting-started/migrating) or [Cline](/docs/getting-started/switching-from-cline) guides. If you're coming from one of those tools, start there instead. |
There was a problem hiding this comment.
WARNING: Broken link to a non-existent Cline migration guide
I can't find any page or redirect for /docs/getting-started/switching-from-cline in this repo. Shipping this as-is will send readers to a 404 from the first paragraph of the page.
|
|
||
| ### Claude Code Compatibility Toggle | ||
|
|
||
| Kilo includes a **Claude Code Compatibility** setting that controls whether your `CLAUDE.md` instructions and Claude Code skills are loaded into Kilo sessions. This is disabled by default to keep sessions clean, but you can enable it to reuse your existing Claude Code configuration. |
There was a problem hiding this comment.
WARNING: Default-behavior description contradicts the CLI section below
This paragraph says Claude Code compatibility is disabled by default, but the CLI section later says Claude Code files are loaded by default unless KILO_DISABLE_CLAUDE_CODE=true is set. Please scope the "disabled by default" note to the VS Code toggle or reword this section so the defaults are consistent.
|
|
||
| **3. Convert custom rules:** | ||
|
|
||
| If you have project-specific rules, place them in `.kilocode/rules/`: |
There was a problem hiding this comment.
WARNING: This migration step points users at the legacy rules directory
packages/kilo-docs/pages/customize/custom-rules.md documents .kilocode/rules/ as backward-compatible legacy behavior and recommends instructions in kilo.jsonc / .kilo/rules/ for the current setup. Calling .kilocode/rules/ the "native format" here will steer new migrations toward the outdated path.
Code Review SummaryStatus: No Issues Found | Recommendation: Merge Files Reviewed (2 files)
Reviewed by gpt-5.4-2026-03-05 · 215,262 tokens |
…line pages - Add dedicated Claude Code migration page documenting the compatibility toggle, CLAUDE.md/skills loading, env vars, and full migration path - Move Cline switching guide from docs/ to pages/ so it's actually served; update Orchestrator references to reflect its deprecated status - Rewrite hub page as an index linking all dedicated migration guides plus brief sections for GitHub Copilot and Aider - Update navigation to show migration as a subsection with sublinks to Cursor/Windsurf, Claude Code, and Cline guides
kilo-code-bot
bot
changed the title
| | `~/.claude/CLAUDE.md` | Global | Your home directory Claude config | | ||
|
|
||
| {% callout type="warning" %} | ||
| Kilo uses a **first-match-wins** strategy per directory. If a directory contains both `AGENTS.md` and `CLAUDE.md`, only `AGENTS.md` is loaded from that directory. This means if you have both files at your project root, `CLAUDE.md` will be ignored in favor of `AGENTS.md`. |
There was a problem hiding this comment.
WARNING: AGENTS.md does not win on a per-directory basis
packages/opencode/src/session/instruction.ts stops looking for CLAUDE.md as soon as it finds any AGENTS.md while walking upward, so a parent AGENTS.md suppresses all CLAUDE.md files below it as well. This paragraph documents a per-directory merge rule that the implementation does not currently have.
| For more fine-grained control, you can split your `CLAUDE.md` into separate rule files: | ||
|
|
||
| ```bash | ||
| mkdir -p .kilocode/rules |
There was a problem hiding this comment.
WARNING: This migration step sends users to the legacy rules layout
packages/kilo-docs/pages/customize/custom-rules.md now recommends the instructions key in kilo.jsonc with files under .kilo/rules/, and treats .kilocode/rules/ as backward-compatible legacy behavior. Pointing Claude Code migrations at .kilocode/rules/ will steer new setups back to the deprecated path.
| If you have a `.github/copilot-instructions.md` file, copy its contents to Kilo's rules: | ||
|
|
||
| ```bash | ||
| mkdir -p .kilocode/rules |
There was a problem hiding this comment.
WARNING: This guide still migrates users to the legacy rules path
The current rules docs recommend instructions in kilo.jsonc / .kilo/rules/ for new setups and keep .kilocode/rules/ only for backward compatibility. The Copilot and Aider examples here will send new migrations back to the deprecated layout.
| - "What external services does this integrate with?" | ||
| - Ask agent never writes files, so exploration is always safe | ||
|
|
||
| **Why this matters:** In Cline, you might accidentally make changes while exploring. In Kilo, Ask and Plan agents can't write files, so you're safe to explore without worry. |
There was a problem hiding this comment.
WARNING: Plan agent is not fully read-only
packages/opencode/src/agent/agent.ts still allows the plan agent to edit plan files under .kilo/plans/*.md (and .opencode/plans/*.md for compatibility). Saying Ask and Plan agents can't write files overstates the safety guarantee and can surprise users who pick Plan expecting zero writes.
|
|
||
| ```bash | ||
| # Create Kilo rules directory | ||
| mkdir -p .kilocode/rules |
There was a problem hiding this comment.
WARNING: This migration guide points new users at the legacy rules directories
Current docs recommend instructions in kilo.jsonc with files under .kilo/rules/ for new projects, while .kilocode/rules* is documented as backward-compatible legacy behavior. This section currently tells Cline users to create the legacy layout instead of the current one.
…date to .kilo/rules/, fix Plan agent write scope - Fix AGENTS.md/CLAUDE.md precedence description: finding any AGENTS.md in the directory hierarchy stops all CLAUDE.md loading (not per-directory) - Replace all .kilocode/rules/ references with .kilo/rules/ + kilo.jsonc (the current recommended format) across all three migration guides - Fix Plan agent claim: Plan can write to .kilo/plans/*.md, not fully read-only like Ask agent - Add kilo.jsonc instructions examples for Copilot, Aider, and Cline migration steps
| } | ||
| ``` | ||
|
|
||
| Kilo's rule system adds **agent-specific rules** that Claude Code doesn't support. Use the `kilo.jsonc` `instructions` field scoped per agent, or use agent-specific rule directories: |
There was a problem hiding this comment.
WARNING: Per-agent rule scoping described here is not implemented
kilo.jsonc's agent schema only exposes fields like prompt, model, and permissions; it does not support an instructions field. The only loader for .kilo/rules-{mode} is RulesMigrator, and it flattens those files into the top-level instructions array, so they apply globally instead of only to Code/Debug/Ask. This section currently documents an agent-specific rules setup that users cannot actually get from the configuration shown here.
| } | ||
| ``` | ||
|
|
||
| Mode-specific Cline rules (`.clinerules-code`, `.clinerules-ask`, etc.) map to Kilo's agent-specific directories: |
There was a problem hiding this comment.
WARNING: These directories do not stay scoped to a single agent
The current rules loader only recognizes .kilo/rules-{mode} through RulesMigrator, which appends every matching file into the global instructions array. So migrating .clinerules-code / .clinerules-ask this way will make those instructions visible to all agents, not just Code or Ask.
Rules from .kilo/rules-{mode}/ directories are loaded globally across
all agents — the mode metadata is not used for filtering at runtime.
Remove per-agent scoping claims and simplify the migration guidance.
2 participants
Summary
Consolidates the migration documentation into a proper section with dedicated pages for each tool:
migrating-from-other-tools.md) — Index linking all dedicated guides, plus brief sections for GitHub Copilot and Aidermigrating-from-claude-code.md) — New dedicated page documenting the compatibility toggle from PR feat(vscode): add Claude Code compatibility toggle #8230,CLAUDE.md/.claude/skills/loading behavior, environment variables (KILO_DISABLE_CLAUDE_CODE*), full migration to Kilo-native config, feature comparison, and concept mapping (slash commands, permission model, project config)switching-from-cline.md) — Moved from orphaneddocs/directory topages/so it's actually served; updated all Orchestrator references to reflect its deprecated status, replaced "modes" terminology with "agents"What was wrong before
docs/getting-started/(notpages/), was not in navigation, and was never served as a live pagemigrating-from-other-tools.mdhad a broken link to the non-existent Cline pageBuilt for Joshua Lambert by Kilo for Slack