How to Switch from Windsurf to Claude Code (Step-by-Step Migration Guide)

Why People Are Switching: The Pricing Math

In March 2026, Windsurf moved from a flat subscription model to a credit-based system. The announcement post on r/windsurf picked up 497 upvotes — almost all of them angry. Here's what changed and why the numbers stung so badly.

Under the old Pro plan (~$15–$25/month), you got unlimited or near-unlimited Cascade interactions. One flat fee covered a full month of building. Under the new credit system, every Cascade action costs credits — and credits are priced such that heavy builders burn through them fast.

The community math worked out to roughly this:

To be fair: casual users who make a handful of requests per day may not notice a huge difference. But vibe coders — people who lean on Cascade to build entire features, iterate on bugs, and run multi-step tasks — are the heaviest users. They're also the ones who got hit hardest. The pricing model essentially taxed the power users who loved the product most.

For more context on exactly how the new credit system works, see: Windsurf's Pricing Changes Explained.

What You'll Miss From Windsurf (Honest)

Before we get into the migration, let's be straight about what Claude Code doesn't have. Switching tools is a real tradeoff, not an upgrade in every dimension.

None of these are dealbreakers for most vibe coders — but they're real. Go in with clear eyes.

What You'll Gain With Claude Code

Here's the flip side — what Claude Code does better, or differently enough to matter.

Step-by-Step Migration Guide

Step 1: Install Claude Code

Claude Code requires Node.js 18 or later. Check your version first:

node --version

If you get a version below 18, or "command not found", install Node from nodejs.org (download the LTS version). Then install Claude Code globally:

npm install -g @anthropic-ai/claude-code

Verify the install worked:

claude --version

You should see a version number. If you see an error, try closing and reopening your terminal, then run the version check again.

Step 2: Get Your Anthropic API Key

Claude Code uses the Anthropic API directly. You need an API key to use it.

1. Go to console.anthropic.com and create an account (or sign in if you have one).
2. Navigate to API Keys in the left sidebar.
3. Click Create Key, give it a name like "Claude Code", and copy the key — it starts with sk-ant-.
4. While you're in the console, go to Billing and add a payment method. Set a monthly spending limit to protect yourself from accidental overuse.

Now set the key in your terminal environment. The cleanest way is to add it to your shell profile so it persists across sessions:

# If you use zsh (default on modern macOS):
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY-HERE"' >> ~/.zshrc
source ~/.zshrc

# If you use bash:
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY-HERE"' >> ~/.bashrc
source ~/.bashrc

Replace sk-ant-YOUR-KEY-HERE with your actual key. Do not share this key or commit it to git.

Step 3: Start Your First Session

Navigate to your project folder in the terminal and launch Claude Code:

cd ~/your-project-folder
claude

This opens an interactive session. Claude Code immediately reads your project files and is ready for your first prompt. Try something simple to confirm everything works:

> Summarize what this project does based on the files you can see.

Claude Code will scan your project and give you a summary. If this works, your setup is correct. If you see an API key error, double-check that your environment variable is set correctly by running echo $ANTHROPIC_API_KEY — it should print your key.

For a full walkthrough of Claude Code's features and interface, see: Claude Code: The Complete Beginner's Guide.

Step 4: Create Your CLAUDE.md File

This is the most important step for getting good results from day one. A CLAUDE.md file sits in your project root and tells Claude Code everything it needs to know about your project before it starts working.

Create a file called CLAUDE.md in your project root. Here is a template to start from:

# Project: [Your Project Name]

## What This Is
[One sentence describing what the app does.]

## Tech Stack
- Frontend: [e.g. React 18, Tailwind CSS]
- Backend: [e.g. Node.js, Express 5]
- Database: [e.g. PostgreSQL via Prisma]
- Deployment: [e.g. Vercel]

## Important Rules
- Never modify files in /node_modules or /dist
- Always use TypeScript strict mode
- Use the existing utility functions in /src/lib before creating new ones
- Prefer early returns over nested if/else

## Coding Style
- Use async/await, not .then() chains
- 2-space indentation
- Named exports only (no default exports)

## Current Focus
[What you're working on right now — update this as the project evolves]

Fill in the blanks for your actual project. The more specific you are, the less you'll need to repeat yourself in every prompt. To learn more about what makes a great CLAUDE.md file, read: What Is a CLAUDE.md File and How Do You Write One?

Translating Windsurf Cascade Workflows to Claude Code

The mental model is nearly identical — describe what you want, the AI does it. But the interface is different. Here's how your Cascade habits map to Claude Code.

Cascade Write Mode → Claude Code (default mode)

In Windsurf, you switched to Write mode when you wanted Cascade to actually change files. In Claude Code, the default mode is agentic — it can and will edit files. You don't need to toggle anything. Just describe what you want built:

Add a password reset flow to this
Express app. POST /auth/reset
sends an email with a token,
POST /auth/reset/:token
validates and updates the
password. Use nodemailer.

Add a password reset flow to this
Express app. POST /auth/reset
sends an email with a token,
POST /auth/reset/:token
validates and updates the
password. Use nodemailer.

The prompt is identical. The experience is nearly identical. The main difference is where you see the changes — Claude Code shows them in the terminal and applies them to your files, while Cascade showed them in the visual diff panel inside the IDE.

Cascade @file mentions → Claude Code file references

In Windsurf, you used @filename to point Cascade at specific files. In Claude Code, you can reference files directly in your prompt using plain language or relative paths:

Claude Code indexes your entire project at startup, so it can find files semantically — you don't need to know exact paths for most requests. For large codebases, being specific still helps.

Cascade Chat Mode → Claude Code question prompts

Windsurf's Chat mode was for questions that didn't change code. In Claude Code, just ask your question as a prompt. If Claude Code thinks it needs to edit files, it will ask you first. If you want to make sure it stays in "explain only" mode, just say so:

> Don't make any changes — just explain how the authentication middleware works in this project.

Windsurf system prompt → CLAUDE.md

If you had a custom system prompt configured in Windsurf to set project context, that maps directly to CLAUDE.md. Copy the content of your system prompt into your CLAUDE.md file. Claude Code reads it at the start of every session — no need to paste it manually each time.

New Cascade conversation → Claude Code /clear

In Windsurf, you started fresh with Cmd+Shift+L. In Claude Code, type /clear to reset the conversation context. Do this between unrelated tasks to keep the context window clean and costs lower.

Cost Comparison: Windsurf New Pricing vs Claude Code API

These numbers are based on community reports from the r/windsurf exodus thread and Anthropic's published API pricing as of March 2026. Individual costs vary depending on how you work, which models you use, and how long your prompts are.

The gap widens with heavier use because Windsurf's credit system charges more per action at scale, while the Anthropic API charges purely per token with no multiplier for volume. If you want a flat monthly cost instead of per-token billing, Anthropic also offers Claude Max subscription plans at $100/month and $200/month for high-volume users.

What AI Gets Wrong About This Migration

If you ask an AI assistant (including Claude) "how do I switch from Windsurf to Claude Code?", you'll get a mostly accurate answer. But here are four things that tend to be glossed over or wrong:

1. "Claude Code is just like Cascade but in a terminal"

This is mostly true but misses important gaps. Claude Code has no inline autocomplete, no visual diff UI, and no multi-model switching. If your workflow relied heavily on Supercomplete's Tab key suggestions or the visual diff panel, the adjustment period will be real. Plan to compensate: keep a lightweight autocomplete extension in your editor, and build the habit of doing git diff to review changes before committing.

2. Claiming API billing is always cheaper

For heavy users, yes. But if you're a very casual builder who makes 5–10 simple requests per day, Windsurf's flat fee might still be more cost-effective than per-token billing — especially if you use Claude's most powerful models for every request. Run your own math: estimate your daily token usage using this guide on tokens and context limits, then multiply by Anthropic's published rates.

3. CLAUDE.md is optional

Technically yes, practically no. Without a CLAUDE.md, Claude Code has to re-learn your project setup every session. You'll repeat yourself constantly ("this is a Next.js app with Tailwind, use TypeScript strict mode…"). Creating even a basic CLAUDE.md file in the first 10 minutes saves hours of repeated context over the coming weeks.

4. You can just copy your Windsurf system prompt to CLAUDE.md

You can, and it's a good starting point. But Windsurf system prompts are often written for Cascade's specific behaviors and may include instructions that don't apply to Claude Code (like "use Write mode for changes"). Audit your system prompt when you paste it — remove anything Windsurf-specific and restructure it around what Claude Code actually needs: project overview, tech stack, hard rules, and style preferences.

FAQ

What to Read Next

You've got the migration steps. Here's where to go deeper:

• Claude Code: The Complete Beginner's Guide — full walkthrough of every Claude Code feature, from first session to advanced workflows.
• What Is a CLAUDE.md File and How Do You Write One? — everything you need to know to write a CLAUDE.md that makes Claude Code dramatically more useful.
• Windsurf's Pricing Changes Explained — the full breakdown of what changed, who it affects, and what your options are.
• Cursor vs Windsurf — if you're still deciding between tools, this comparison includes Claude Code in the mix.
• What Are AI Tokens and Context Limits? — understanding tokens helps you use Claude Code efficiently and avoid unexpected costs.