Last updated: March 16, 2026

Migrating from Windsurf to Cursor involves more than just installing a new editor. Your project configurations, custom rules, snippets, and workflow settings need to be transferred carefully to maintain productivity. This guide walks you through the complete process of moving your project config from Windsurf to Cursor.

Table of Contents

Prerequisites

Before you begin, make sure you have the following ready:

Step 1: Understand Windsurf and Cursor Config Structures

Both Windsurf and Cursor are built on VS Code, but they store custom configurations differently. Windsurf uses its own “rules” system and Cascade workflows, while Cursor employs “Cursor Rules” and project-specific settings. Understanding these differences helps you plan your migration strategy.

Windsurf stores project-specific configurations in a .windsurf directory at your project root. This directory contains JSON files defining AI behavior, custom commands, and workflow automations. Cursor, on the other hand, uses a .cursor directory with a different configuration structure. Both support YAML and JSON formats, but the key names and organizational logic vary.

Before starting the migration, ensure both editors are installed on your system. You will need access to your project directories and some familiarity with editing configuration files.

Step 2: Exporting Windsurf Project Config

Begin by locating your Windsurf configuration files. Open your project in Windsurf and navigate to the settings panel. Look for the “Project Settings” or “Rules” section where you have defined custom behaviors.

Finding Your Windsurf Rules

Windsurf stores rules in the .windsurf folder within each project. If you have been using Windsurf for significant projects, check your project directories:

# List all Windsurf config directories in your projects
find ~/projects -type d -name ".windsurf" 2>/dev/null

Each .windsurf directory typically contains files like config.json or rules.md. The rules file defines how Windsurf’s AI behaves in your project, including custom instructions, file patterns, and interaction preferences.

Exporting Cascade Workflows

If you use Windsurf’s Cascade feature for automated workflows, export these before switching. Cascade workflows are stored as JSON files within the .windsurf directory:

{
  "workflows": [
    {
      "name": "Code Review",
      "trigger": "onPush",
      "steps": [
        {"action": "run", "command": "npm test"},
        {"action": "analyze", "scope": "changedFiles"}
      ]
    }
  ]
}

Copy these workflow definitions to a safe location. You will recreate them in Cursor using its own automation features.

Step 3: Set Up Cursor with Your Config

Now that you have exported your Windsurf settings, the next step is importing them into Cursor. Cursor uses a similar but distinct configuration system that requires some manual translation.

Creating Cursor Rules

Cursor supports two locations for project rules. The legacy approach uses a .cursorrules file in the project root. The current preferred approach uses the .cursor/rules/ directory, which allows you to split rules into multiple focused files:

.cursor/
  rules/
    coding-style.mdc
    testing-conventions.mdc
    api-guidelines.mdc

Each .mdc file in this directory is applied automatically. This modular approach maps well from Windsurf’s rules system, where you may have had separate files for different concerns. Create a base rules file in your project root:

# Project Rules for [Your Project Name]

### Step 4: Context
You are working on a [project description]. This is a [language/framework] application using [key technologies].

### Step 5: Code Style
- Use [your preferred style guidelines]
- Follow [specific conventions]
- Prefer [patterns you commonly use]

### Step 6: Guidelines
- Always run tests before committing
- Use descriptive variable names
- Keep functions under 50 lines

Importing Custom Snippets

If you have custom snippets in Windsurf, export them and import into Cursor. Both editors support VS Code snippets, which are stored in snippets folders. Locate your Windsurf snippets:

# Find snippet files
find ~/.windsurf -name "*.json" -path "*snippets*" 2>/dev/null

Copy these snippet files to Cursor’s equivalent location:

# Copy to Cursor's snippets directory
cp -r ~/.windsurf/snippets ~/.cursor/

Migrating Keyboard Shortcuts and Keybindings

Both editors support VS Code keybindings, but custom keybindings may need adjustment. Export your Windsurf keybindings and adapt them for Cursor.

Exporting Windsurf Keybindings

Access the keyboard shortcuts panel in Windsurf (Cmd+K on Mac or Ctrl+K on Windows), then export your custom keybindings. The file is typically located at:

# On macOS
~/Library/Application\ Support/Windsurf/User/keybindings.json

# On Windows
%APPDATA%/Windsurf/User/keybindings.json

Applying Keybindings to Cursor

Copy or adapt these keybindings to Cursor’s configuration location:

# On macOS
cp ~/Library/Application\ Support/Windsurf/User/keybindings.json \
   ~/Library/Application\ Support/Cursor/User/keybindings.json

Review each keybinding. Some may conflict with Cursor’s default shortcuts and require modification.

Step 7: Transferring Terminal Profiles and Tasks

If you have custom terminal configurations or task definitions in Windsurf, migrate these to Cursor for an experience.

Task Configurations

Both editors support VS Code task definitions. Your tasks.json file should work directly in Cursor if you copy it:

cp .windsurf/tasks.json .cursor/
# or
cp .vscode/tasks.json .cursor/

Terminal Profiles

Custom terminal profiles and shell integrations may need reconfiguration. Check your shell configuration files (.bashrc, .zshrc, or .fish) for Windsurf-specific aliases and functions, then add equivalent configurations for Cursor if needed.

Step 8: Preserving Git and Version Control Settings

Your Git configurations, including hooks and settings, transfer automatically since they are project-based. However, review the following:

Git Hooks

If you use Husky, lefthook, or similar tools for Git hooks, these work in Cursor without modification. Verify that your pre-commit and pre-push hooks function correctly after the switch.

Remote URLs

Update your Git remote URLs if you have added Windsurf-specific remotes:

git remote -v
git remote set-url origin git@github.com:your-repo-url.git

Step 9: Verify Your Migration

After transferring all configurations, spend time verifying that everything works correctly in Cursor.

Test Your Setup

  1. Open your project in Cursor

  2. Verify that custom rules load correctly (check the “Rules” panel)

  3. Test your snippets by triggering them

  4. Confirm keyboard shortcuts work as expected

  5. Run your test suite to ensure nothing broke

Adjust and Iterate

You will likely need to fine-tune some settings. Cursor’s AI behavior differs from Windsurf’s Cascade in important ways. Cascade in Windsurf operates more autonomously across multi-file changes with minimal prompting. Cursor’s Composer mode (invoked with Cmd+I) is the closest equivalent, but it requires more explicit instruction. Plan to rewrite your Windsurf rules with more detailed context to get comparable results from Cursor’s AI.

Migrating VS Code Extensions

Since both editors are VS Code forks, most extensions are compatible. However, some extensions available in Windsurf’s marketplace may not be published on the Open VSX Registry or Cursor’s extension marketplace. Audit your installed extensions before switching:

# In Windsurf, list all installed extensions
code --list-extensions > windsurf-extensions.txt

# Review and install compatible ones in Cursor
cat windsurf-extensions.txt

Common extensions that migrate cleanly include ESLint, Prettier, GitLens, Docker, and language-specific syntax highlighters. Extensions that are AI-specific to Windsurf (like Windsurf’s built-in Cascade integration) have no direct equivalent—Cursor’s AI features replace them natively.

If an extension you rely on is unavailable in Cursor’s marketplace, check whether it is published on the Open VSX Registry (open-vsx.org). Cursor can install extensions from .vsix files directly:

cursor --install-extension path/to/extension.vsix

Windsurf vs. Cursor: Configuration Feature Comparison

Understanding what maps to what helps you plan the migration:

Windsurf Feature Cursor Equivalent Migration Effort
.windsurf/rules.md .cursorrules or .cursor/rules/*.mdc Low — copy and reformat
Cascade workflows Cursor Composer (Cmd+I) Medium — manual recreation
Custom commands VS Code Tasks (tasks.json) Low — direct copy
Windsurf snippets VS Code snippets Low — direct copy
AI model selection Cursor model picker Low — UI setting
Usage analytics Cursor admin dashboard Low — UI navigation
Project indexing Cursor codebase indexing Automatic on open

The biggest investment is in recreating Cascade workflows as Composer sessions or task definitions. Cascade’s ability to chain multi-step AI actions is a distinctive Windsurf feature; Cursor’s equivalent requires more manual orchestration but gives you finer control over each step.

Troubleshooting

Configuration changes not taking effect

Restart the relevant service or application after making changes. Some settings require a full system reboot. Verify the configuration file path is correct and the syntax is valid.

Permission denied errors

Run the command with sudo for system-level operations, or check that your user account has the necessary permissions. On macOS, you may need to grant terminal access in System Settings > Privacy & Security.

Connection or network-related failures

Check your internet connection and firewall settings. If using a VPN, try disconnecting temporarily to isolate the issue. Verify that the target server or service is accessible from your network.

Frequently Asked Questions

How long does it take to transfer project?

For a straightforward setup, expect 30 minutes to 2 hours depending on your familiarity with the tools involved. Complex configurations with custom requirements may take longer. Having your credentials and environment ready before starting saves significant time.

What are the most common mistakes to avoid?

The most frequent issues are skipping prerequisite steps, using outdated package versions, and not reading error messages carefully. Follow the steps in order, verify each one works before moving on, and check the official documentation if something behaves unexpectedly.

Do I need prior experience to follow this guide?

Basic familiarity with the relevant tools and command line is helpful but not strictly required. Each step is explained with context. If you get stuck, the official documentation for each tool covers fundamentals that may fill in knowledge gaps.

Can I adapt this for a different tech stack?

Yes, the underlying concepts transfer to other stacks, though the specific implementation details will differ. Look for equivalent libraries and patterns in your target stack. The architecture and workflow design remain similar even when the syntax changes.

Where can I get help if I run into issues?

Start with the official documentation for each tool mentioned. Stack Overflow and GitHub Issues are good next steps for specific error messages. Community forums and Discord servers for the relevant tools often have active members who can help with setup problems.