Analyze, plan, and execute Windsurf SDK upgrades with breaking change detection.
Use when upgrading Windsurf SDK versions, detecting deprecations,
or migrating to new API versions.
Trigger with phrases like "upgrade windsurf", "windsurf migration",
"windsurf breaking changes", "update windsurf SDK", "analyze windsurf version".
!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: .codeiumignore # AI indexing exclusions
.cursor/rules/: .windsurf/rules/ # Workspace rules
cursor_settings: windsurf_settings # IDE preferences
Composer: Cascade # Agentic AI assistant
Tab: Supercomplete # Inline completions
Cmd+K: Cmd+I # Inline editing
Cmd+L: Cmd+L # AI chat (same!)
Migration script:
#!/bin/bash
set -euo pipefail
echo "Migrating Cursor config to Windsurf..."
# Convert .cursorrules to .windsurfrules
[ -f .cursorrules ] && cp .cursorrules .windsurfrules && echo "Copied .cursorrules → .windsurfrules"
# Convert .cursorignore to .codeiumignore
[ -f .cursorignore ] && cp .cursorignore .codeiumignore && echo "Copied .cursorignore → .codeiumignore"
# Migrate workspace rules
if [ -d .cursor/rules ]; then
mkdir -p .windsurf/rules
cp .cursor/rules/*.md .windsurf/rules/ 2>/dev/null
echo "Copied workspace rules to .windsurf/rules/"
echo "NOTE: Check frontmatter -- Windsurf uses 'trigger:' field, Cursor uses different format"
fi
echo "Migration complete. Review .windsurfrules for Cursor-specific references."
Step 4: Add Windsurf-Specific Configuration
After migration, add Windsurf-exclusive features:
<!-- New Windsurf features not in VS Code or Cursor -->
1. Cascade Workflows (.windsurf/workflows/*.md)
- Reusable multi-step automation via slash commands
- No equivalent in VS Code or Cursor
2. Cascade Memories
- Persistent facts across sessions
- Partial equivalent: Cursor notepad
3. Turbo Mode
- Auto-execute terminal commands
- Cursor has "auto-run" but different config
4. Browser Previews
- In-IDE preview with element selection
- Send UI elements to Cascade for editing
5. Workspace Rules with Trigger Modes
- glob, always_on, manual, model_decision
- More granular than Cursor's rule system
Step 5: Post-Upgrade Validation
set -euo pipefail
echo "=== Windsurf Post-Upgrade Check ==="
echo "Version: $(windsurf --version)"
echo "Extensions: $(windsurf --list-extensions | wc -l) installed"
echo "Rules: $([ -f .windsurfrules ] && wc -c < .windsurfrules || echo 'none') bytes"
echo "Ignore: $([ -f .codeiumignore ] && wc -l < .codeiumignore || echo 'none') patterns"
# Test AI features
echo ""
echo "Manual checks:"
echo "1. Open a code file -- Supercomplete should show ghost text"
echo "2. Press Cmd/Ctrl+L -- Cascade should open and respond"
echo "3. Press Cmd/Ctrl+I -- Command mode should activate"
Error Handling
Issue
Cause
Solution
Extensions not loading
Incompatible with Windsurf
Check Windsurf marketplace for alternative
Settings not applied
Wrong config directory
Verify OS-specific settings path
.cursorrules not working
Wrong filename
Rename to .windsurfrules
Keyboard shortcuts different
Windsurf overrides some defaults
Check Keyboard Shortcuts editor
Copilot still active
Not disabled
Extensions > search "copilot" > Disable
Examples
Backup Before Upgrade
# Backup current Windsurf config
tar -czf windsurf-config-backup-$(date +%Y%m%d).tar.gz \
~/.config/Windsurf/User/ \
~/.codeium/ \
.windsurfrules \
.codeiumignore \
.windsurf/ 2>/dev/null
Check Windsurf Changelog
Visit: https://windsurf.com/changelog
Look for: breaking changes, deprecated settings, new features
