windsurf-upgrade-migration

name	windsurf-upgrade-migration
description	Upgrade Windsurf IDE, migrate settings from VS Code or Cursor, and handle breaking changes. Use when upgrading Windsurf versions, migrating from another editor, or handling configuration changes after updates. Trigger with phrases like "upgrade windsurf", "windsurf update", "migrate to windsurf", "windsurf from cursor", "windsurf from vscode".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(git:*)
version	1.11.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","windsurf","migration","upgrade","vscode"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Windsurf Upgrade & Migration

Current State

!windsurf --version 2>/dev/null || echo 'Not installed' !code --version 2>/dev/null | head -1 || echo 'VS Code not installed'

Overview

Guide for upgrading Windsurf to new versions and migrating from VS Code or Cursor. Covers settings transfer, extension compatibility, and Windsurf-specific configuration that doesn't exist in other editors.

Prerequisites

• Current editor installation accessible
• Git for version controlling config files
• Backup of existing settings

Instructions

Step 1: Check Current Windsurf Version

# Current version
windsurf --version

# Check for updates
# Windsurf auto-updates by default
# Manual: Help > Check for Updates (or download from windsurf.com)

Step 2: Migrate from VS Code

Windsurf is VS Code-based and supports most VS Code settings and extensions:

# Windsurf imports VS Code settings on first launch
# For manual migration:

# 1. Export VS Code extensions list
code --list-extensions > vscode-extensions.txt

# 2. Install in Windsurf
cat vscode-extensions.txt | xargs -L1 windsurf --install-extension

# 3. Copy settings
# macOS:
cp ~/Library/Application\ Support/Code/User/settings.json \
   ~/Library/Application\ Support/Windsurf/User/settings.json

# Linux:
cp ~/.config/Code/User/settings.json \
   ~/.config/Windsurf/User/settings.json

Key difference: Remove or disable GitHub Copilot -- it conflicts with Windsurf's Supercomplete.

Step 3: Migrate from Cursor

Cursor and Windsurf both extend VS Code but have different AI config files:

# Mapping Cursor concepts to Windsurf:
cursor_to_windsurf:
  .cursorrules:       .windsurfrules     # AI context rules
  .cursorignore: