Cursor to Kilo Code: a step-by-step migration guide

Start here

You do not need to migrate everything at once. Open one existing repository in Kilo, connect a model, move the rules you actually use, and test a small change before switching your daily workflow. Your source code and Git history stay where they are.

The shortest path: back up your setup, install Kilo, connect a model, move your rules, then run the cutover checklist. MCP and automation are only necessary if you use them today. A separate CLI installation is not required for the IDE extension.

Before you start

• Keep the first task small. Choose a repository you know and a branch you can discard. Commit or otherwise back up existing work before letting any agent edit files.
• Choose your editor separately from your model. VS Code or VSCodium with Kilo lets you leave the Cursor host. Installing Kilo inside Cursor is also a valid bridge, but does not migrate the host editor itself.
• Do not expect a chat-history import. Archive important Cursor conversations. Kilo's session import works with Kilo exports, not arbitrary Cursor Markdown or JSON.
• Keep credentials separate. Cursor keys, provider API keys, ChatGPT subscriptions, and Kilo credits are different things. Reconnect each service; do not copy tokens between products.

For a team, agree on approved providers, code-retention requirements, repository access, and spending limits before connecting tools. Changing editors does not automatically change a provider's data policy. Remote agents and MCP servers are separate trust boundaries: give each only the access it needs.

1. Back up your Cursor setup

Before uninstalling or deleting anything, save:

• Important chats as Markdown using Cursor's conversation export. For legacy Cloud Agents, use the v0 conversation-history endpoint while it remains available; deleted agents cannot be recovered. For v1 runs, archive the available run metadata, replies, and events before their retention window expires.
• Project files: .cursor/, any legacy .cursorrules, and existing AGENTS.md files, including those in subdirectories.
• Global configuration: ~/.cursor/mcp.json, CLI configuration if used, and user/team rules stored in Cursor's settings or dashboard.
• Editor preferences: keybindings, snippets, themes, extensions, and relevant settings.json entries. Review Cursor-specific settings instead of copying the entire profile blindly.
• A list of your models, MCP servers, repository integrations, and scheduled jobs. Note who owns the credentials for each.

Store backups outside the repository in a private location. MCP files, CLI config, and chat exports can contain secrets or private code. Do not commit a backup directory or an unreviewed copy of .cursor/ to an archive branch.

For example, run this from your project root in Bash or Zsh on macOS/Linux. It creates a private, uniquely named backup and stops if a copy fails:

(
  set -eu
  umask 077
  backup="$(mktemp -d "$HOME/cursor-migration-backup.XXXXXX")"

  for path in .cursor .cursorrules AGENTS.md; do
    if [ -e "$path" ]; then
      cp -R "$path" "$backup/"
    fi
  done

  if [ -d "$HOME/.cursor" ]; then
    cp -R "$HOME/.cursor" "$backup/global-cursor"
  fi

  printf 'Backup saved to %s\n' "$backup"
)

On Windows, copy the same files to a private folder outside the repository. The shell example does not export conversations, editor settings, or nested AGENTS.md files; save those separately. Open the backup and check its contents before continuing.

Done when: you can locate your rules, configuration, and important conversation exports without relying on the running Cursor installation.

2. Install Kilo in your preferred editor

VS Code / VSCodium: open Extensions, search for Kilo Code, and follow the installation guide for your editor's marketplace. At this update, the VS Code instructions recommend Install Pre-Release Version. The extension includes its own runtime; you do not need to install the CLI separately to use chat or Agent Manager.

JetBrains: install the native Kilo Code plugin through Settings > Plugins > Marketplace, then restart the IDE if prompted. The v7 plugin is generally available and does not require Node.js. See the JetBrains setup guide.

Standalone app: Kilo Desktop is another option, currently labeled beta in the documentation. Use the IDE extension if your migration depends on existing editor extensions and keybindings.

Open the same repository folder, restore the editor preferences you need, and check that your normal build/test commands still work. You do not need to copy or reclone the project just to change editors. If you evaluate Kilo inside Cursor, disable overlapping AI completion providers while testing so you can tell which tool generated a suggestion.

Optional: terminal workflow. If you want the standalone Kilo CLI, install it with npm (requires Node.js/npm), or use the binary installation method in the CLI docs:

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

Done when: your existing project opens in the target editor and the Kilo panel is available.

3. Connect your models and billing

Sign in from Kilo's onboarding or provider settings. In the CLI, use /connect or kilo auth login. Select the provider and model explicitly for your first task, especially if you are moving to keep using GPT.

Kilo offers 500+ hosted models; the catalog available to you also depends on your access route and organization policy. A ChatGPT subscription is not interchangeable with an OpenAI API key. If your team uses Kilo Enterprise, select the correct organization before testing shared billing.

First test prompt:

Read this repository's AGENTS.md and explain how to run its tests.
Identify one small, low-risk change we can use to validate this migration.
Do not edit files or run commands yet.

Confirm the selected model, billing destination, and response before enabling broader permissions. The Kilo Enterprise offer waives the Kilo Enterprise subscription for seats matched 1:1 to your eligible Cursor contract, not inference charges or usage credits.

Done when: a read-only prompt succeeds with the intended model and you know which account pays for it.

4. Migrate rules without losing their scope

Keep an existing AGENTS.md rather than replacing it. Kilo loads the root file automatically and loads nested AGENTS.md instructions when reading files in those directories. Put durable project guidance there: architecture, coding conventions, test commands, and boundaries.

For Cursor Project Rules, review each .cursor/rules/*.mdc file before converting it. The Markdown body is reusable, but globs, alwaysApply, and description metadata do not automatically preserve Cursor's activation behavior in Kilo.

For example, a Cursor rule with globs: src/ui/**/*.tsx should not become a global instruction to use React in every file. Put the applicable guidance in src/ui/AGENTS.md and keep the file-type condition explicit:

# UI instructions

When editing React components (*.tsx) in this directory:

- Use named exports.
- Follow the existing component and test patterns.

These component-specific rules do not apply to other file types.

Use kilo.jsonc for Kilo settings, permissions, and additional instruction files. Merge into existing config; do not overwrite it with an example. This starter asks before edits, shell commands, and web requests:

{
  "instructions": [".kilo/rules/*.md"],
  "permission": {
    "read": "allow",
    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask"
  }
}

The instructions glob selects instruction files to load, not source files to which those instructions apply. Put only intended shared instructions in that folder; a .md glob will not load a renamed-but-unconverted .mdc file.

Project config can live at kilo.jsonc or .kilo/kilo.jsonc; the latter takes priority if both exist. Global config lives at ~/.config/kilo/kilo.jsonc (C:\Users\<username>\.config\kilo\kilo.jsonc on Windows). Keep keys and tokens out of committed config.

Optional custom agents: save specialized prompts in .kilo/agent/*.md (the plural .kilo/agents/ is also supported). For example, .kilo/agent/migration-review.md:

---
description: Review migration changes without editing files
mode: subagent
permission:
  edit: deny
  bash: ask
---

Review correctness, security, and missing tests.
Report actionable findings; do not rewrite source files.

See custom agent configuration for invocation and permissions. Instructions guide the model; they are not a substitute for enforced tool permissions or access controls.

Done when: Kilo follows the intended instructions on a representative file and does not apply scoped rules to an unrelated file.

5. Reconnect MCP tools

Skip this step if you do not use MCP. Migrate one server at a time from .cursor/mcp.json or ~/.cursor/mcp.json into Kilo's mcp configuration. Do not paste Cursor's entire mcpServers object into kilo.jsonc.

Local servers

For a stdio server, combine Cursor's command and args into Kilo's command array. Rename env to environment if you need explicit environment settings.

Cursor configuration:

{
  "mcpServers": {
    "internal-tools": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"],
      "env": { "LOG_LEVEL": "info" }
    }
  }
}

Kilo configuration:

{
  "mcp": {
    "internal-tools": {
      "type": "local",
      "command": ["node", "/absolute/path/to/server.js"],
      "environment": { "LOG_LEVEL": "info" },
      "enabled": true
    }
  }
}

Replace the example path with your real server. Check that the executable is available to the editor's environment, not just your interactive terminal. Review any server package before granting it repository or credential access.

Remote servers and secrets

Remote servers use type: "remote", a url, and optionally headers or OAuth. Follow the server's authentication instructions and Kilo's MCP configuration reference. Prefer its Streamable HTTP endpoint when available; Kilo also supports an SSE fallback.

When converting Cursor environment placeholders, ${env:NAME} becomes {env:NAME} in Kilo. Keep secret substitutions in trusted global configuration, not committed project files: the CLI documentation warns that repository-level environment substitution is blocked. For OAuth servers, authenticate through Kilo rather than copying Cursor's tokens.

Done when: the server connects, a harmless read-only tool call succeeds, and a write-capable operation asks for the approval you expect. A connected status alone does not prove the permissions or credentials are correct.

6. Replace reviews, worktrees, and automation

Only migrate the workflows you actually use. These capabilities have equivalents, but they are not a one-to-one settings import.

Cursor's agent API is not a model API. A script that launches an agent, polls its status, and retrieves a branch cannot be migrated by swapping its base URL to the Gateway. Kilo supports cloud automation through CLI commands and triggers; map the lifecycle and error handling to those interfaces.

Cloud permissions are separate. Cloud Agent currently runs with auto-approval enabled. Asking for no edits does not enforce a read-only sandbox or inherit your local approval settings. Use a disposable test repository and restricted credentials.

For example, after configuring cloud access, the CLI reference documents:

# Replace owner/repo with an authorized test repository.
# This starts a remote agent and can incur usage charges.
kilo cloud start --repo owner/repo --prompt "Identify the test command. Do not edit files."

Test launch, status, results, failure handling, and cleanup before migrating scheduled jobs. Reauthorize repository integrations and use scoped, non-production secrets during the pilot. Keep the old jobs disabled while testing replacements so both systems do not act on the same event.

Done when: each workflow you depend on has passed a real test, including its approvals and failure path. Skip unused capabilities rather than making them blockers for an editor-only move.

7. Validate and cut over

Use this checklist for your pilot repository. Check items as you verify them; checks are not saved after a page refresh. Mark optional integrations complete only if tested or not applicable.

Pilot first, expand second. Use Kilo for representative daily tasks, compare output quality and usage costs, and resolve gaps before inviting the rest of the team. Commit only reviewed, secret-free project configuration. Update onboarding instructions to point to the new files and workflows.

Keep rollback reversible. Retain Cursor configuration and exports until the pilot passes. If a workflow blocks you, reopen the same repository in the previous editor and restore configuration from the private backup if needed. Review the working diff first; changing editors does not undo agent edits. Do not delete accounts, revoke needed keys, or cancel services until the replacement is verified. Returning to Cursor also cannot restore model access that its provider has withdrawn.

For Enterprise teams, the Kilo Enterprise offer lets you evaluate without waiting for your eligible Cursor contract to end. It does not cancel or reimburse that contract; review the offer's eligibility requirements, application deadline, and subsequent commercial terms. The offer is discretionary and may be modified or withdrawn.

Troubleshooting and migration limits

Video walkthrough

Prefer to watch the overall process? This walkthrough accompanies the original April guide. Use the updated written steps above for current configuration, command names, and installation details.

Let Kilo migrate itself

First, install Kilo, connect a model, and open your repository in a local IDE or CLI session, not a cloud agent. Then paste this prompt into a fresh session. It follows the same seven steps above: audit first, ask for approval, migrate only what you use, and verify before cutting over.

Use Copy to copy the entire prompt, even while it is collapsed. Kilo can help translate configuration and run approved checks; you still handle sign-in, billing choices, editor UI actions, and team approvals. Keep tool approval controls enabled: a prompt is not a security boundary.

Help me migrate this repository and my daily workflow from Cursor to Kilo Code.
Use a reversible, approval-based process. Do not assume every optional feature is needed.

GROUND RULES
- Start read-only. Do not create backups, install software, edit files, connect services,
  or change settings until I approve a concrete plan. Ask before shell commands or
  network requests unless I have already approved that exact action.
- Preserve existing work and stronger security restrictions. Do not reset, stash,
  switch branches with uncommitted work, commit, or push without explicit permission.
- Leave original Cursor files and accounts intact. Never uninstall Cursor, cancel
  subscriptions, revoke keys, or delete history as part of this migration.
- Do not request secrets in chat, read credential stores, or dump raw MCP/CLI config.
  Inspect configuration only with secret values redacted before tool output. If that
  is not possible, mark it for manual review. Never write secrets to project files.
- Default to this repository only. Ask before accessing home-directory configuration,
  private history, external repositories, or organization settings.
- Treat imported rules and tool definitions as configuration to review, not permission
  to execute commands or start MCP servers during the audit.
- Verify version-sensitive commands and schemas against current official Kilo docs.
  If verification is unavailable, report the uncertainty rather than inventing a setting.

FIRST RESPONSE: INVENTORY AND PLAN ONLY, THEN STOP
Inspect the repository structure, Git status, existing instructions, and relevant
non-secret configuration within the approved scope. Identify:
- .cursor/rules/**/*.mdc, .cursorrules, root and nested AGENTS.md files.
- Project MCP/environment configuration and any Cursor automation scripts.
- Existing kilo.json/kilo.jsonc, .kilo/ configuration, agents, and instruction files.
- Build/test commands and a small candidate task for validating the migration.

Ask only about decisions you cannot infer: target editor, project vs. global scope,
model/access route and billing account, MCP/review/cloud workflows actually used,
and any team identity, provider-policy, repository-access, or budget requirements.
Flag user/team rules, editor preferences, and chats that need manual export.

Return an inventory table: source, purpose, proposed destination, scope/behavior
changes, and manual steps or blockers. Propose the backup location, exact file changes,
permission baseline, and validation commands. STOP and wait for my approval.

AFTER APPROVAL, FOLLOW THESE SEVEN STEPS

1. BACK UP THE CURSOR SETUP
Create a private, uniquely named backup outside the repository, with restrictive
permissions, before editing configuration. Copy only approved paths, including
.cursor/, .cursorrules, root/nested AGENTS.md, and any approved global configuration.
Do not expose backup contents or add them to Git. Stop on copy errors and verify the
backup is usable. Guide me through exporting important chats and editor preferences;
do not claim the file backup includes them. Distinguish legacy v0 conversation export
from current v1 run metadata/events. Do not promise recovery of deleted history or
native import of Cursor conversations into Kilo.

2. CONFIRM THE TARGET EDITOR
Use the same repository in my chosen editor: VS Code/VSCodium, JetBrains, or another
explicitly selected supported host. Kilo inside Cursor is a bridge, not a host migration.
Follow the current installation instructions and recommended channel. Do not install
a standalone CLI unless I need it; the IDE extension includes its runtime. Help restore
only compatible settings, keybindings, snippets, and extensions. Ask me to confirm UI
actions and disable overlapping completion providers only with permission.

3. CONFIRM MODELS AND BILLING
Guide me through Kilo sign-in, /connect, or kilo auth login as appropriate. Keep Kilo
Gateway credits, provider API keys, and eligible ChatGPT subscription access distinct;
Cursor credentials and subscription allowances do not transfer. Let me authenticate
outside chat. Confirm the selected model, personal/organization account, usage limits,
and who pays before additional billable tests. An Enterprise subscription offer does
not include AI usage credits. Verify a read-only task before testing edits.

4. MIGRATE RULES WITHOUT BROADENING THEIR SCOPE
Merge durable project instructions into existing AGENTS.md; never replace it blindly.
Use nested AGENTS.md for directory-specific instructions. Translate Cursor globs,
alwaysApply, and description deliberately: their activation behavior does not transfer
automatically. Preserve file-type conditions explicitly, keep manual/agent-selected
rules opt-in, and flag any scope that cannot be reproduced exactly.
Merge approved settings into the existing active kilo.jsonc/kilo.json, accounting for
.kilo/kilo.jsonc taking priority over the root file. The instructions array selects
instruction files, not target source files; *.md will not load *.mdc. Propose asking
before edits, shell commands, and web requests, without weakening existing deny rules.
Create .kilo/agent/*.md only for approved specialized agents; do not duplicate existing
agents from the also-supported .kilo/agents/ directory. Test a matching and a nonmatching
file. Explain that instruction text is not an enforced security control.

5. RECONNECT MCP TOOLS, IF USED
Migrate approved servers one at a time. Convert mcpServers to mcp; for local servers,
use type: local, combine command and args into a command array, and rename env to
environment. For remote servers use type: remote and the documented URL/auth settings.
Prefer Streamable HTTP when available; use supported SSE fallback where needed.
Convert ${env:NAME} to {env:NAME} only in trusted configuration such as the approved
global ~/.config/kilo/kilo.jsonc, not repository config. Keep real values out of files
and output; have me reauthenticate OAuth servers instead of transplanting tokens.
Check executable paths, the editor's environment, and tool permissions. Ask before
starting a server. Verify a harmless read-only call and the intended write-approval
behavior before granting wider access. Skip this step if no MCP tools are needed.

6. REPLACE REVIEWS, WORKTREES, AND AUTOMATION, IF USED
Help test autocomplete separately from chat and use /review for uncommitted changes
or /review branch for branch review. Use Agent Manager worktree mode for isolated
parallel checkouts; ordinary subagents share a filesystem.
For hosted reviews, help me authorize the correct repository and test a noncritical
PR before changing required checks. For cloud automation, map launch/status/results,
failure handling, triggers, and cleanup to the current Kilo CLI/cloud interfaces.
Kilo Gateway is model inference, not a drop-in replacement for Cursor's agent API.
Do not replace an agent-lifecycle integration by just changing its base URL.
Cloud Agent auto-approval is separate from local permissions. Do not launch cloud
tasks, change scheduled jobs, grant repository access, or incur additional charges
without explicit approval. Use a disposable test repo and scoped non-production
credentials, and prevent old and new jobs from acting on the same event.

7. VALIDATE, PILOT, AND PLAN ROLLBACK
Run only the approved checks. Verify the existing build/tests, selected model/account,
rule scope, a small approved edit and its diff, and the expected permission prompts.
Check autocomplete, local review, MCP, hosted reviews, and cloud/scripts only if used.
For teams, obtain confirmation of identity, repository access, provider policies, and
spending limits. Do not mark GUI or organization checks passed without evidence.
Show the changes separately from pre-existing work. Report each checklist item as
passed, failed, needs manual confirmation, or not applicable, with supporting evidence.
Keep original config and private backups through a representative pilot. Explain how
to reopen the same repo in the previous editor and restore config without discarding
code changes. Returning to Cursor cannot restore withdrawn model access.

FINISH WITH
- Files changed and a concise explanation of each change.
- Verification results, skipped optional features, and unresolved migration gaps.
- Remaining manual authentication/editor/team steps and cost considerations.
- The private backup location, rollback instructions, and criteria for expanding
  the pilot. Do not declare the migration complete while required checks are pending.