Migrating from Windsurf

You have been using Windsurf for months. Cascade handles your multi-file edits, Flows keep your conversation context organized, and the inline suggestions feel natural. But you keep reading about features that Windsurf does not have: MCP servers that connect your AI to Jira and databases, skills that teach the agent your team conventions, and autonomous cloud agents that run in parallel. You want to try Cursor, Claude Code, or Codex — but you do not want to lose the workflows you have already built.

This guide maps every Windsurf feature to its equivalent in the three major AI coding tools, shows you how to migrate your configuration, and warns you about the gaps where no direct equivalent exists.

What You’ll Walk Away With

• A complete feature mapping from Windsurf to Cursor, Claude Code, and Codex
• Step-by-step instructions for migrating Windsurf rules and configuration
• Workflow translation for Cascade and Flows to each target tool
• Honest assessment of what you gain and what you lose with each migration path
• Configuration files you can copy directly into your new setup

Feature Mapping

Before migrating, understand where each Windsurf feature lives in the target tool.

Windsurf Feature	Cursor Equivalent	Claude Code Equivalent	Codex Equivalent
Cascade (multi-file agent)	Agent Mode (Cmd+I)	Default behavior (all sessions)	Task execution (cloud agent)
Flows (contextual threads)	Composer conversations	Conversation sessions	Task threads
Inline suggestions	Tab autocomplete	N/A (CLI-based)	N/A (cloud-based)
Windsurf Rules	.cursor/rules/	CLAUDE.md	AGENTS.md
Memories	Notepad + rules	Memory system (CLAUDE.md)	AGENTS.md
@-mentions (files)	@file, @folder, @codebase	Automatic file discovery	Automatic via sandbox
Preview pane	Built-in browser preview	External browser	N/A
Supercomplete	Tab predictions	N/A	N/A
Model selection	Model picker (GPT-4o, Claude, etc.)	Claude models only	OpenAI models (codex-mini)

Migrating Your Configuration

Translating Windsurf Rules

Windsurf rules live in .windsurf/rules/ as markdown files. Each target tool uses a different format and location.

Cursor

Cursor rules live in .cursor/rules/ as markdown files. The format is nearly identical to Windsurf rules.

# Copy your Windsurf rules directly
mkdir -p .cursor/rules
cp .windsurf/rules/*.md .cursor/rules/

Cursor reads all .md files in .cursor/rules/ and includes them in the agent’s context. The content format is compatible — you may only need to update tool-specific references.

What to change after copying:

• Replace references to “Cascade” with “Agent Mode” or “Composer”
• Replace references to “Flows” with “conversations” or “sessions”
• Remove any Windsurf-specific instructions (like “use Supercomplete for…”)
• Add Cursor-specific instructions if needed (e.g., “use @codebase for broad searches”)

Example migration:

# Before (Windsurf rule)
When using Cascade for multi-file changes, always create a Flow
for the feature so context is preserved across sessions.

# After (Cursor rule)
When using Agent Mode for multi-file changes, keep related changes
in the same Composer conversation so context is preserved.

Claude Code

Claude Code reads project instructions from CLAUDE.md at the repository root. Consolidate your Windsurf rules into a single file.

# Create CLAUDE.md from your Windsurf rules
cat .windsurf/rules/*.md > CLAUDE.md

Then edit CLAUDE.md to restructure the content:

# Project Instructions

## Architecture
- Components go in src/components/ with PascalCase names
- API routes go in src/pages/api/ with kebab-case names

## Code Conventions
- Use TypeScript strict mode
- Prefer named exports over default exports
- Use interfaces for object shapes, types for unions

## Testing
- Every component needs a test file
- Use Vitest with React Testing Library
- Test behavior, not implementation

## Workflow
- When making multi-file changes, explain the plan before starting
- Run tests after every significant change
- Commit with conventional commit messages

What to change:

• Remove all GUI-specific instructions (Cascade, Flows, Supercomplete)
• Add CLI-specific instructions (e.g., “use /think for complex planning”)
• Consolidate into a single coherent document (not separate rule files)
• Add workflow instructions that reference Claude Code features

Codex

Codex reads instructions from AGENTS.md at the repository root. Like Claude Code, consolidate into a single file.

# Create AGENTS.md from your Windsurf rules
cat .windsurf/rules/*.md > AGENTS.md

Edit AGENTS.md to match Codex conventions:

# Agent Instructions

## Code Conventions
- TypeScript strict mode, named exports only
- Components in src/components/, API routes in src/pages/api/

## Testing Requirements
- Run `npm test` after changes to verify nothing breaks
- Every new function needs a corresponding test

## Boundaries
- Do not modify files in src/auth/ without explicit approval
- Do not delete test files
- Do not change database migration files that have already been applied

What to change:

• Remove all GUI references
• Add explicit sandbox boundaries (Codex runs autonomously)
• Specify which commands to run for verification
• Be more prescriptive — Codex operates with less interactive guidance

Tip

Copy-paste prompt for automatic rule migration:

“Read all files in .windsurf/rules/ and convert them to [Cursor .cursor/rules/ format | a single CLAUDE.md file | a single AGENTS.md file]. Remove any Windsurf-specific references (Cascade, Flows, Supercomplete). Preserve all coding conventions, architecture decisions, and workflow instructions. Add tool-specific instructions where appropriate.”

Translating Windsurf Workflows

Cascade to Agent Mode / Claude Code Sessions / Codex Tasks

Windsurf’s Cascade is its multi-file agentic editing feature. Here is how the same workflows translate.

Cursor

Cascade equivalent: Agent Mode in Composer

In Windsurf, you open Cascade and describe a multi-file task. In Cursor:

1. Open Composer with Cmd+I (macOS) or Ctrl+I (Windows/Linux)
2. Ensure Agent Mode is selected (not Ask or Edit mode)
3. Describe your task the same way you would in Cascade

"Refactor the authentication module to use JWT tokens instead of sessions.
Update all middleware, API routes, and test files. Run the test suite
after making changes."

Agent Mode works like Cascade: it reads files, plans changes, edits multiple files, and can run terminal commands.

Key differences from Cascade:

• Cursor shows a diff preview before applying changes (you accept or reject each file)
• You can reference specific files with @filename for more targeted context
• Cursor’s @codebase searches your entire indexed codebase, similar to Cascade’s full-project awareness

Claude Code

Cascade equivalent: Standard conversation

Claude Code is agentic by default. Every conversation is a “Cascade” — it reads files, edits code, and runs commands without needing a special mode.

claude "Refactor the authentication module to use JWT tokens instead
of sessions. Update all middleware, API routes, and test files.
Run the test suite after making changes."

Key differences from Cascade:

• No GUI — everything happens in the terminal
• Claude Code automatically discovers relevant files (no need to @-mention them)
• You can use /think for complex planning before execution
• Changes are applied directly (no diff preview step by default)
• You can review changes afterward with git diff

Codex

Cascade equivalent: Task execution

Codex runs tasks asynchronously in a cloud sandbox. Instead of an interactive conversation, you describe the task and Codex executes it.

codex "Refactor the authentication module to use JWT tokens instead
of sessions. Update all middleware, API routes, and test files.
Run npm test to verify changes."

Key differences from Cascade:

• Codex runs in the cloud, not locally
• Tasks are asynchronous — you can run multiple in parallel
• Results come back as a set of changes you review and merge
• No interactive back-and-forth during execution
• Better suited for well-defined tasks than exploratory work

Flows to Context Management

Windsurf Flows let you organize conversations by feature or topic. The equivalent in each tool:

Cursor

Flows equivalent: Multiple Composer sessions

Cursor does not have a named “Flows” feature, but you can:

• Open separate Composer conversations for different features
• Use Notepad to store context that persists across conversations
• Reference previous conversation context with the history panel

For long-running features, create a Notepad entry with the feature context and reference it in each conversation.

Claude Code

Flows equivalent: Separate sessions + CLAUDE.md

Each Claude Code session is independent. To maintain context across sessions:

• Document feature context in CLAUDE.md or a feature-specific file
• Start new sessions by pointing Claude to the relevant context file
• Use the memory system to persist decisions across sessions

claude "Read docs/features/jwt-auth-migration.md for context on the
ongoing auth migration. Continue from where we left off -- the
middleware is updated but the API routes still need changes."

Codex

Flows equivalent: Task descriptions

Codex tasks are self-contained. Provide all context in the task description:

codex "Continue the JWT auth migration (see docs/features/jwt-auth-migration.md).
The middleware is updated. Now update all API routes in src/pages/api/
to use the new JWT verification function instead of session checks."

What You Gain

Each target tool offers capabilities that Windsurf does not have.

MCP Ecosystem

Windsurf has limited MCP support. Cursor, Claude Code, and Codex all connect to the full MCP ecosystem:

• Database MCP — query your database directly from the AI conversation
• GitHub MCP — create PRs, review code, manage issues
• Atlassian MCP — read Jira tickets and Confluence docs
• Playwright MCP — run browser automation and E2E tests
• Context7 MCP — fetch live documentation for any library

// Example: MCP configuration (works in Cursor and Claude Code)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://..." }
    }
  }
}

Skills Ecosystem

Skills let you install curated instruction sets that teach the AI best practices for specific frameworks:

npx skills add vercel-labs/agent-skills
npx skills add anthropics/claude-code
npx skills add stripe/agent-toolkit

Parallel Autonomous Agents (Codex)

Codex can run multiple tasks in parallel in isolated cloud sandboxes. You can fire off five refactoring tasks and review the results together — something Windsurf’s single-threaded Cascade cannot do.

Tip

Copy-paste prompt for validating your migration:

“I just migrated from Windsurf. Read my [.cursor/rules/ | CLAUDE.md | AGENTS.md] configuration and verify it covers: coding conventions, architecture patterns, testing requirements, and workflow instructions. Identify any gaps where Windsurf-specific instructions were removed but no replacement was added. Suggest additions for features specific to this tool.”

What You Lose

Be honest about the trade-offs.

Inline suggestions (if migrating to Claude Code or Codex). Windsurf’s Supercomplete and inline suggestions do not exist in CLI or cloud-based tools. If you value inline autocomplete, Cursor is the closest match.

Integrated preview pane. Windsurf has a built-in browser preview. Cursor has some preview capability, but Claude Code and Codex require external browser testing.

Model flexibility. Windsurf lets you switch between GPT-4o, Claude, and other models mid-conversation. Claude Code is Claude-only. Codex uses OpenAI models only. Cursor offers the most model flexibility among the three.

Familiar interface. If you have spent months building muscle memory in Windsurf, any switch requires adjustment time. Budget 1-2 weeks for the transition.

Migration Checklist

1. Export your Windsurf rules. Copy all files from .windsurf/rules/ to a temporary location.

2. Choose your target tool. Cursor for closest feature parity with Windsurf. Claude Code for maximum agentic capability. Codex for parallel cloud execution.

3. Translate your rules. Follow the configuration migration section above for your chosen tool.

4. Set up MCP servers. Configure the MCP servers you need (GitHub, database, documentation).

5. Install relevant skills. Search the skills marketplace for your tech stack.

6. Test with a representative task. Pick a task you did recently in Windsurf and redo it in the new tool. Compare the experience.

7. Run both tools for one week. Use Windsurf for comfort tasks and the new tool for exploration. Gradually shift more work to the new tool.

8. Commit your configuration. Once satisfied, commit .cursor/rules/, CLAUDE.md, or AGENTS.md to your repository so your team can follow.

Tip

Copy-paste prompt for side-by-side comparison:

“I am migrating from Windsurf to [Cursor | Claude Code | Codex]. Help me test the migration by performing this task that I previously did in Windsurf: [describe the task]. After completing it, compare the experience and point out any steps that were harder or easier than they would have been in Windsurf.”

When This Breaks

Rules migrate but the AI ignores some conventions. Windsurf may have applied rules differently than the target tool. If a convention is not being followed, make the instruction more explicit with a concrete code example.

MCP configuration does not transfer. MCP server configuration is tool-specific. You cannot copy Windsurf’s MCP config directly. Set up each MCP server from scratch following the target tool’s documentation.

Windsurf-specific prompts produce worse results. If you developed prompt patterns tuned for Windsurf’s model handling, they may not work as well in other tools. Simplify your prompts and let the target tool’s agent handle the planning.

Missing model access. If you relied on a specific model in Windsurf (e.g., GPT-4o), verify that your target tool provides access to it. Claude Code only supports Claude models. Codex only supports OpenAI models.

Team members still on Windsurf. During a gradual migration, some team members may still use Windsurf while others use the new tool. Commit rules for all tools simultaneously (.windsurf/rules/, .cursor/rules/, CLAUDE.md) until the migration is complete.

What’s Next

Migrating from GitHub Copilot If you are also moving off Copilot, combine migration strategies.

Migrating Between Codex, Cursor, and Claude Code Cross-tool migration strategies for multi-tool teams.

Project Conversion Playbook Make your project AI-ready with proper configuration and context files.