Skip to main content

Migrating from Cursor or Windsurf

Quickly migrate your custom rules from Cursor or Windsurf to Kilo Code. The process typically takes just a few minutes per project.

Last Updated: November 2025

Why Kilo Code's Rules System?​

Kilo Code simplifies AI configuration while adding powerful new capabilities:

  • Simple format: Plain Markdown files—no YAML frontmatter or GUI configuration required
  • Mode-specific rules: Different rules for different workflows (Code, Debug, Ask, custom modes)
  • Better version control: All configuration lives in your repository as readable Markdown
  • More control: Custom modes let you define specialized workflows with their own rules and permissions

Quick Migration Guide​

Choose your current tool:

Migrating from Cursor​

What's Different in Kilo Code​

CursorKilo CodeKey Difference
.cursor/rules/*.mdc with YAML frontmatter.kilocode/rules/*.md plain MarkdownNo YAML metadata required
alwaysApply: true/false metadataFile location determines scopeScope controlled by directory structure
globs: ["*.ts"] for file patternsMode-specific directories or custom modesFile patterns handled via custom modes
description for AI activationClear file names and organizationRelies on explicit file organization
Global rules in UI settings~/.kilocode/rules/*.md filesGlobal rules stored as files in home folder

Migration Steps​

1. Identify your rules:

ls -la .cursor/rules/        # Project rules
ls -la .cursorrules          # Legacy file (if present)

2. Create Kilo Code directory:

mkdir -p .kilocode/rules

3. Convert .mdc files to .md:

For each file in .cursor/rules/, remove the YAML frontmatter and keep just the Markdown content.

Cursor format:

---
description: TypeScript coding standards
globs: ["*.ts", "*.tsx"]
alwaysApply: false
---

# TypeScript Standards
- Always use TypeScript for new files
- Prefer functional components in React

Kilo Code format:

# TypeScript Standards

- Always use TypeScript for new files
- Prefer functional components in React

4. Migrate in one command:

# Copy all files
for file in .cursor/rules/*.mdc; do
  basename="${file##*/}"
  cp "$file" ".kilocode/rules/${basename%.mdc}.md"
done

# Then manually edit each file to remove YAML frontmatter (the --- section at the top)

5. Migrate global rules:

  • Open Cursor Settings → General → Rules for AI
  • Copy the text content
  • Save to ~/.kilocode/rules/cursor-global.md

6. Handle legacy .cursorrules:

cp .cursorrules .kilocode/rules/legacy-rules.md

Converting Cursor's globs Patterns​

Cursor's globs field specifies which files a rule applies to. Kilo Code handles this through mode-specific directories instead.

Cursor approach:

---
globs: ["*.ts", "*.tsx"]
---
Rules for TypeScript files...

Kilo Code approach (Option 1 - Mode-specific directory):

mkdir -p .kilocode/rules-code
# Save TypeScript-specific rules here

Kilo Code approach (Option 2 - Custom mode):

# .kilocodemodes (at project root)
- slug: typescript
  name: TypeScript
  roleDefinition: You work on TypeScript files
  groups:
      - read
      - [edit, { fileRegex: '\\.tsx?$' }]
      - ask

Then place rules in .kilocode/rules-typescript/

Flattening Nested Cursor Rules​

Cursor supports nested .cursor/rules/ directories. Kilo Code uses flat structure with descriptive names:

# Cursor: .cursor/rules/backend/server/api-rules.mdc
# Kilo Code: .kilocode/rules/backend-server-api-rules.md

Migrating from Windsurf​

What's Different in Kilo Code​

WindsurfKilo CodeKey Difference
.windsurf/rules/*.md.kilocode/rules/*.mdSame Markdown format
GUI configuration for activation modesFile location determines scopeScope controlled by directory structure
"Always On" mode (GUI)Place in .kilocode/rules/Rules stored as files, not GUI settings
"Glob" mode (GUI)Mode-specific directoriesFile patterns handled via mode directories
12,000 character limit per ruleNo hard limitNo character limit on rule files
Global rules in ~/.codeium/windsurf/memories/global_rules.md~/.kilocode/rules/*.mdGlobal rules in home folder, multiple files

Migration Steps​

1. Identify your rules:

ls -la .windsurf/rules/      # Project rules
ls -la .windsurfrules        # Legacy file (if present)

2. Create Kilo Code directory:

mkdir -p .kilocode/rules

3. Copy files directly (already Markdown):

cp .windsurf/rules/*.md .kilocode/rules/

4. Migrate global rules:

cp ~/.codeium/windsurf/memories/global_rules.md ~/.kilocode/rules/global-rules.md

5. Handle legacy .windsurfrules:

cp .windsurfrules .kilocode/rules/legacy-rules.md

6. Split large rules if needed:

If you had rules approaching the 12,000 character limit, split them:

# Instead of one large file:
# .windsurf/rules/all-conventions.md (11,500 chars)

# Split into focused files:
# .kilocode/rules/api-conventions.md
# .kilocode/rules/testing-standards.md
# .kilocode/rules/code-style.md

Converting Windsurf's Activation Modes​

Windsurf configures activation through the GUI. In Kilo Code, file organization replaces GUI configuration:

Windsurf GUI ModeKilo Code Equivalent
Always OnPlace in .kilocode/rules/ (default)
Glob (file patterns)Mode-specific directory or custom mode
Model DecisionClear file names by concern (e.g., testing-guidelines.md)
ManualOrganize with descriptive names

Example - Converting a Glob rule:

If you had a rule in Windsurf with Glob mode set to *.test.ts, create a custom test mode:

# .kilocodemodes (at project root)
- slug: test
  name: Testing
  roleDefinition: You write and maintain tests
  groups:
      - read
      - [edit, { fileRegex: '\\.(test|spec)\\.(ts|js)$' }]
      - ask

Then place the rule in .kilocode/rules-test/

AGENTS.md Support​

All three tools support the AGENTS.md standard. If you have one, it works in Kilo Code automatically:

# Verify it exists
ls -la AGENTS.md

# That's it - Kilo Code loads it automatically (enabled by default)

Important: Use uppercase AGENTS.md (not agents.md). Kilo Code also accepts AGENT.md (singular) as a fallback.

Note: Both AGENTS.md and AGENT.md are write-protected files in Kilo Code and require user approval to modify.

Understanding Mode-Specific Rules​

This is Kilo Code's unique feature that replaces both Cursor's globs and Windsurf's activation modes.

Directory Structure​

.kilocode/rules/              # Apply to ALL modes
.kilocode/rules-code/         # Only in Code mode
.kilocode/rules-debug/        # Only in Debug mode
.kilocode/rules-ask/          # Only in Ask mode
.kilocode/rules-{custom}/     # Only in your custom mode

Real-World Example​

From Cursor:

---
description: Testing best practices
globs: ["**/*.test.ts", "**/*.spec.ts"]
---
# Testing Rules
- Write tests for all features
- Maintain >80% coverage

To Kilo Code:

# 1. Create test mode directory
mkdir -p .kilocode/rules-test

# 2. Save rule as plain Markdown
cat > .kilocode/rules-test/testing-standards.md << 'EOF'
# Testing Rules
- Write tests for all features
- Maintain >80% coverage
EOF

# 3. Define the mode (optional - creates a custom mode)
# Add to .kilocode/config.yaml:
# modes:
#   - slug: test
#     name: Test Mode
#     groups: [read, edit, ask]

Post-Migration Checklist​

After migration:

  • Verify rules loaded: Click law icon (⚖️) in Kilo Code panel
  • Test rule application: Ask Kilo Code to perform tasks following your rules
  • Organize rules: Split large files, use clear names
  • Set up mode-specific rules: Create directories for specialized workflows
  • Update team docs: Document new .kilocode/rules/ location
  • Commit to version control: git add .kilocode/
  • Remove old directories: Delete .cursor/ or .windsurf/ folders once verified

Troubleshooting​

Rules Not Appearing​

Check file location:

ls -la .kilocode/rules/      # Project rules
ls -la ~/.kilocode/rules/    # Global rules

Verify file format:

  • Can be any text file extension (.md, .txt, etc.) - binary files are automatically filtered out
  • Remove all YAML frontmatter from Cursor files
  • Ensure files are not cache/temp files (.cache, .tmp, .log, .bak, etc.)

Reload VS Code:

  • Cmd+R (Mac) or Ctrl+R (Windows/Linux)
  • Or: Command Palette → "Developer: Reload Window"

Cursor Metadata Lost​

Cursor's globs, alwaysApply, and description don't transfer automatically. Solutions:

  • For file patterns: Use mode-specific directories or custom modes
  • For always-on rules: Place in .kilocode/rules/
  • For context-specific rules: Use clear file names and organization

Windsurf Activation Modes Lost​

Windsurf's GUI activation modes (Always On/Glob/Model Decision/Manual) aren't stored in files. Solutions:

  • Before migrating: Document each rule's activation mode
  • After migrating: Organize files accordingly in Kilo Code

Nested Rules Flattened​

Cursor's nested directories don't map to Kilo Code. Flatten with descriptive names:

# Bad: .cursor/rules/backend/api/rules.mdc
# Good: .kilocode/rules/backend-api-rules.md

AGENTS.md Not Loading​

  • Verify filename: Must be AGENTS.md or AGENT.md (uppercase)
  • Check location: Must be at project root
  • Check setting: Verify "Use Agent Rules" is enabled in Kilo Code settings (enabled by default)
  • Reload: Restart VS Code if needed

Advanced: Creating Custom Modes​

For complex workflows, define custom modes with their own rules and permissions:

# .kilocodemodes (at project root)
- slug: review
  name: Code Review
  roleDefinition: You review code and suggest improvements
  groups:
      - read
      - ask
      # Note: No edit permission - review mode is read-only

- slug: docs
  name: Documentation
  roleDefinition: You write and maintain documentation
  groups:
      - read
      - [edit, { fileRegex: '\\.md$', description: "Markdown files only" }]
      - ask

Then create corresponding rule directories:

mkdir -p .kilocode/rules-review
mkdir -p .kilocode/rules-docs

Note: .kilocodemodes can be in YAML (preferred) or JSON format. For global modes, edit the custom_modes.yaml file via Settings > Edit Global Modes.

Next Steps​

Additional Resources​

Community Examples​

Cursor users:

Windsurf users:

Cross-tool:

Is this documentation incorrect or incomplete? Report an issue on GitHub