Windsurf Guide

What it is

Windsurf is an AI-native code editor from Codeium — a fork of VS Code wrapped around Cascade, an autonomous in-editor agent that plans, edits, runs, and iterates without leaving the IDE. It's Cursor's primary competitor, with similar VS Code DNA but different bets on what matters: stronger agent autonomy, more generous free tier, live preview for web, and self-hosting for enterprise.

If you want an editor that feels like VS Code but has an AI engineer pair-programming with you, Windsurf is one of two serious choices in 2026 (the other being Cursor). Pair it with Claude Code in the terminal and you've got the strongest two-tool setup for modern coding work.

When to reach for Windsurf

• You want agent-driven multi-file changes inside your editor — not a separate CLI
• You're building web apps and want live preview alongside the editor
• You're on a tight budget — the free tier covers real daily use
• You need self-hosted AI coding (HIPAA, SOC 2, air-gapped) — Cursor doesn't offer this
• You like the VS Code keymap and don't want to relearn an editor
• You're a small team or solo dev — Cascade's project memory cuts re-priming friction

Don't reach for Windsurf if:

• You live in Vim, Emacs, JetBrains, or Sublime — Continue (in VS Code) or Aider (terminal) fit better
• You want a pure terminal workflow — Claude Code or Aider are right
• You want maximum-polish and biggest-community — Cursor wins on both

Setup

Install

Download from windsurf.com. Available for macOS, Linux (deb/rpm/AppImage), and Windows.

First-launch flow

1. Sign in with Google or GitHub.
2. Pick your default Cascade model — Claude Sonnet 4.6 is the safe default for most work.
3. Import your VS Code settings if you're switching (Windsurf detects them automatically).
4. Install your usual extensions from the marketplace.

Project rules

Drop a .windsurf/rules.md file at the root of your repo. Cascade reads it automatically as ambient context. Cover:

# Project rules

## Stack
- Next.js 15 (app router)
- TypeScript strict mode
- Tailwind CSS 3
- Vitest for tests

## Conventions
- Components in /components, pages in /app
- File names: kebab-case for routes, PascalCase for React components
- Always pair UI changes with a story update (Storybook)
- No `any` — use `unknown` and narrow

## Commands
- Tests: npm test
- Build: npm run build
- Lint: npm run lint --fix

This 30-line file dramatically improves Cascade's first-attempt accuracy.

Cascade tool permissions

Cascade can run terminal commands. Lock that down per workspace:

• Settings → Cascade → Tool execution
  • Auto-approve: read-only commands (ls, cat, grep)
  • Prompt: write commands (npm install, git, file edits)
  • Block: destructive commands (rm -rf, git push --force, db drops)

For team workspaces, push these settings into a checked-in .windsurf/settings.json so everyone gets the same guardrails.

MCP servers

Add MCP servers in .windsurf/mcp.json (same schema as Claude Code's mcp.json). Common picks:

• GitHub MCP — for PR / issue / release management
• Postgres MCP — for safe DB queries in dev
• Linear MCP — to file/triage tickets from the editor
• Sentry MCP — to pull and triage live errors

Once installed, Cascade can call these tools mid-task without leaving the IDE.

The Cascade loop

Open Cascade with Cmd-L (Mac) or Ctrl-L (Windows/Linux). Type a task. Cascade:

1. Plans — outputs a numbered plan (you can interrupt or revise here).
2. Edits — applies changes file by file, each surfacing as an in-editor diff.
3. Runs — executes test/build commands as configured, sees the output.
4. Iterates — fixes failures and retries until success criteria are met.

You can:

• Accept all — bulk-accept the proposed changes
• Accept per-file — review and accept one file at a time
• Reject + retry — give Cascade more guidance and rerun
• Pause — stop the loop, edit manually, then continue

This loop is the killer feature. Cursor has a similar loop ("Composer"); Cascade's edge in 2026 is fewer "lost the plot" failures on multi-file tasks.

Supercomplete + Tab to Jump

Inline AI that doesn't require invoking Cascade:

• Supercomplete — multi-line autocomplete tuned by Codeium's SWE models. Trigger as you type; accept with Tab.
• Tab to Jump — after an edit, Cascade predicts where you'll edit next and the Tab key jumps your cursor there. Works across files. Saves a surprising amount of navigation friction once you trust it.

Both run on Codeium's models by default — fast and free, no API spend.

Inline command (Cmd-I)

For quick targeted edits without firing up the full Cascade agent: select code, hit Cmd-I, describe the change. Cascade rewrites the selection in place. Best for:

• Convert this class component to hooks
• Add JSDoc comments to these functions
• Refactor this for-loop into a map/filter pipeline
• Translate this Python snippet to TypeScript

Faster than Cascade for one-off tweaks; doesn't load the whole project context.

Live preview

For web projects (Next.js, Vite, Astro, etc.), Windsurf shows a rendered preview pane alongside the editor. Hot-reload as you edit. Cursor doesn't ship this natively — for visual web work, it's a real productivity unlock.

The preview understands routes, components, and dev server output. Cascade can also navigate the preview mid-task — "go to /pricing and verify the CTA renders" works.

Cascade Memory

Cascade persists project context across sessions:

• Files it's already read recently (skip re-reading them)
• Conventions it's learned (from rules.md and past corrections)
• Decisions you've made ("we agreed to use this pattern for forms")

You can inspect, edit, or wipe the memory from the Cascade panel. For privacy-sensitive projects, you can also disable memory per workspace.

Model picker

Per-workspace, per-mode model selection:

• Autocomplete / Tab to Jump — Codeium SWE models (free, fast)
• Cascade agent — Claude Sonnet (default), Claude Opus, GPT-5, Gemini 2.5 Pro, Codeium frontier
• Inline command — same picker

You're not locked in. If Claude has a bad day or you want to A/B GPT vs Sonnet on a specific task, switch in one click.

Pricing reality

• Free — Supercomplete + Tab to Jump unlimited, Cascade with a daily quota. Genuinely usable for solo work.
• Pro ($15/mo) — higher Cascade limits, more frontier-model usage, larger context windows.
• Teams — admin controls, billing rollups, shared settings.
• Enterprise — self-hosted deployment, SSO, audit logging, custom model endpoints.

For solo: Free is real. For daily heavy use: Pro is the right line. For team/enterprise: book a demo (pricing isn't public for those tiers).

Comparison: Windsurf vs Cursor vs Claude Code

Most engineers in 2026 use two of these. Common pairings:

• Cursor + Claude Code (most popular)
• Windsurf + Claude Code (best for budget-conscious or self-host)
• Just Cursor (simplest, most polished, costs more long-term)

Honest limitations

• No live token meter. Cost forecasting is harder than Claude Code's /cost. Watch your monthly bill until you've calibrated.
• Smaller plugin community. Most things work; the long tail of niche VS Code extensions sometimes doesn't.
• A few Microsoft extensions need alternates. Pylance → Pyright, Remote Containers → devcontainer CLI, a couple of language servers. Not painful, just a one-time fix.
• Cascade can over-edit on vague prompts. Invest in .windsurf/rules.md and use plan-first prompts for anything non-trivial.
• UI polish lags Cursor in a few places. Real, but minor. Both ship fast.
• No personal/team self-host. Self-hosting is Enterprise-only. Sole proprietors who want local-only AI should look at Continue with a local model.

Workflow patterns that work

1. .windsurf/rules.md first, code second. Spend 15 minutes writing project rules before your first Cascade run on a new repo. Pays off immediately.

2. Plan-first for anything non-trivial. Use "Plan only — wait for my approval" in your Cascade prompt. Same discipline as Claude Code's plan mode; same payoff.

3. Cascade for multi-file, Cmd-I for single-spot edits. Don't fire up Cascade for a one-line tweak; use inline command.

4. Live preview + Cascade for web work. "Verify this renders correctly at /pricing" is a Cascade command that uses the preview.

5. Switch models on tough tasks. Default Sonnet; flip to Opus on hard refactors or perf debugging.

6. Memory hygiene per project. If you redirect Cascade ("no, we don't do it that way here"), make sure that lands in rules.md so it survives memory clears.

Security & privacy

• Code is sent to Codeium and your chosen model provider during AI calls. Read the privacy policy if your repo is sensitive.
• Free and Pro tiers send to Codeium-hosted models by default.
• Enterprise self-host keeps everything in your VPC — no data leaves.
• You can disable training-data usage in account settings (default-off for paid tiers).
• Sandbox Cascade's terminal access per workspace; never let it run unscoped on a host with prod credentials.

When to walk away

• You don't want a VS Code fork — use Continue inside official VS Code, or Cursor's CLI tools.
• You want a non-VS Code editor — Aider (terminal), Claude Code (terminal), Zed AI (Zed-only).
• You want zero internet exposure — only Enterprise self-host gives you that; otherwise look at local-model setups (Continue + Ollama).
• You're a JetBrains shop — neither Windsurf nor Cursor really fits; check Cursor IDE Plus or JetBrains AI Assistant.

Next steps

• Install Windsurf and import your VS Code settings.
• Write a .windsurf/rules.md for your current project.
• Run your first Cascade task with "plan first" — see how it scopes the work.
• Pair Windsurf with Claude Code for terminal automations.
• For enterprise needs, book a demo for the self-host story.