How to Use Windsurf AI Editor? Complete Beginner Guide 2026

TL;DR

Windsurf is Codeium's AI-native code editor — a VS Code fork rebuilt from the ground up for AI-assisted development. If you want to code faster with AI without copy-pasting between a chatbot and your editor, Windsurf gives you Cascade (an agentic AI that reads your entire project and makes changes directly) and Supercomplete (context-aware inline completions). This tutorial walks you through installation, configuration, and the workflows that actually save you time.

What You'll Learn

• Install Windsurf on macOS, Windows, or Linux in under 5 minutes
• Configure AI models — Claude Sonnet 4.5, GPT-5, and free alternatives
• Use Supercomplete for intelligent inline code suggestions
• Master Cascade for multi-file agentic coding
• Set up .windsurfrules for project-specific AI behavior
• Debug common issues and optimize your workflow

Prerequisites

• A computer running macOS (12+), Windows 10/11, or Linux (Ubuntu 20.04+)
• At least 4 GB of free RAM (8 GB recommended)
• An internet connection for AI model access
• Optional: existing VS Code settings/extensions (Windsurf can import them)

Step 1: Install Windsurf

macOS

# Option A: Download from windsurf.com

# Visit https://windsurf.com and download the .dmg installer

# Drag Windsurf to Applications folder

# Option B: Homebrew (if available)
brew install --cask windsurf

Windows

Download the .exe installer from windsurf.com and run it. The installer handles everything — no manual PATH configuration needed.

Linux

# Debian/Ubuntu
wget https://windsurf.com/windsurf.deb
sudo dpkg -i windsurf.deb

# Or use the AppImage
wget https://windsurf.com/windsurf.AppImage
chmod +x windsurf.AppImage
./windsurf.AppImage

First Launch — Import VS Code Settings

On first launch, Windsurf asks if you want to import settings, extensions, keybindings, and themes from VS Code. Select "Import from VS Code" — this gives you a familiar starting environment with all your shortcuts intact. The import is one-way and non-destructive (your VS Code setup is untouched).

Step 2: Configure AI Models

Open Windsurf, then go to Settings (Cmd+, on macOS / Ctrl+, on Windows/Linux) and search for "AI" or "Model."

Recommended Model Setup (June 2026)

How to switch models: Click the model name dropdown in the Cascade sidebar panel (bottom-left of the Cascade chat area).

Enabling Supercomplete

Supercomplete is Windsurf's inline code completion engine. It suggests entire lines or blocks based on your project context — more intelligent than standard autocomplete.

1. Open Settings → Search "supercomplete"
2. Toggle Enable Supercomplete to ON
3. Set Supercomplete Suggestion Delay to 200ms (default is fine for most users)
4. Under Supercomplete: Max Tokens, set to 256 (controls how long the suggestion can be)

Supercomplete works automatically — just start typing and pauses trigger suggestions. Press Tab to accept, Esc to dismiss.

Step 3: Use Cascade — The Agentic AI

Cascade is Windsurf's main AI agent. Unlike a chatbot where you copy-paste code, Cascade reads your entire codebase, understands project structure, and makes changes directly in your files.

Opening Cascade

Press Cmd+L (macOS) or Ctrl+L (Windows/Linux) to open the Cascade sidebar panel.

Cascade Chat vs Cascade Agent

Windsurf has two modes inside Cascade:

• Chat mode (default): Ask questions, get explanations. Writes code as suggestions you review.
• Agent mode (Ctrl+Shift+L): Autonomous editing. Cascade reads files, modifies code, creates new files, and runs terminal commands — all from a single prompt. Each change appears as a diff you can accept or reject.

Example: Build a REST API Endpoint with Cascade Agent

1. Press Ctrl+Shift+L to open Cascade Agent
2. Paste this prompt:

Add a GET /api/users endpoint to this Node.js Express app.
Include pagination (page and limit query params),
error handling for invalid params,
and return JSON with { users: [], total, page, limit }.

1. Cascade will:

   • Find your Express router file
   • Read existing route patterns
   • Write the new endpoint code
   • Show you the diff
   • Wait for you to accept or reject

2. Click Accept All (Cmd+Enter) or review each change individually

Cascade Context — How It Sees Your Code

Cascade automatically indexes your entire project on open. It sees:

• All files in the workspace (excluding .gitignore patterns)
• Open tabs as priority context
• Git history for recent changes
• Running terminal output

Pro tip: Use @filename to explicitly add files to Cascade's context if it misses something relevant.

Step 4: Write .windsurfrules for Project-Specific AI Behavior

.windsurfrules is a markdown file at your project root that tells Cascade how to behave. It's like a system prompt for your codebase.

Create .windsurfrules

Create a file named .windsurfrules in your project root:

# Project Rules for Cascade

## Tech Stack
- Next.js 15 with App Router
- TypeScript strict mode
- Tailwind CSS v4 for styling
- Prisma ORM with PostgreSQL

## Coding Standards
- Use arrow functions, not function declarations
- Always add error boundaries to new pages
- Use Zod for API validation
- File names: kebab-case for components, camelCase for utilities

## Testing
- Write tests with Vitest
- Every API route needs at least one integration test

## Never
- Do not use `any` type — use `unknown` first
- Do not add new npm dependencies without asking
- Do not modify tsconfig.json without explicit instruction

Save the file. Cascade reads it automatically on every session. There is no need to reload — it picks up changes when you next invoke Cascade.

Advanced .windsurfrules with @-references

You can reference other files:

@docs/architecture.md
@docs/api-conventions.md

Always follow the patterns in the above docs when generating code.

Step 5: Practical Workflows That Actually Save Time

Workflow 1: Refactor a Function Across the Codebase

1. Select the function name in any file
2. Press Cmd+Shift+L (Agent mode)
3. Type: Rename this function to X and update all references across the project
4. Cascade finds every usage and updates them all
5. Review diffs → Accept All

Workflow 2: Generate Tests for an Existing Module

1. Open the file you want tested
2. Press Cmd+L → type: Write comprehensive unit tests for this module using Vitest. Cover edge cases, error states, and happy paths.
3. Cascade reads the module, understands all exports, and writes tests
4. Press Cmd+Enter to accept

Workflow 3: Debug with Terminal Integration

1. Run your failing command in Windsurf's built-in terminal
2. Select the error message in the terminal output
3. Press Cmd+L → type: Fix this error (Cascade gets the terminal output as context)
4. Cascade reads the error, the relevant files, and proposes a fix

Workflow 4: Inline Editing with Ctrl+K

1. Select a block of code
2. Press Ctrl+K (Cmd+K on macOS)
3. Type your instruction: Add input validation for empty strings and null values
4. Cascade rewrites the selected block in place

Step 6: Optimize Your Windsurf Settings

Performance Settings

UI Settings (These Make a Big Difference)

Editor: Minimap                 → OFF (saves sidebar space)
Editor: Inlay Hints             → ON (shows inferred types)
Cascade: Show Diff Preview      → ON (review before accepting)
Cascade: Auto-accept Safe Edits → OFF (always review AI changes)

Critical: Keep "Auto-accept Safe Edits" OFF. Even "safe" edits like formatting can have unintended side effects in large codebases. Always review.

Windsurf vs Cursor vs VS Code Copilot (Quick Comparison)

Troubleshooting

Cascade is slow to respond

• Check your internet connection — Cascade relies on cloud models
• Reduce context: close tabs you do not need in Cascade's context
• Switch to a faster model (Cascade Base is instant but less capable)
• Exclude large directories from indexing in Settings → Indexing → Exclude

Supercomplete suggestions are irrelevant

• Make sure your project has a .windsurfrules file with coding conventions
• Open the relevant files as tabs — Cascade prioritizes open files for context
• Check that the file type is recognized (bottom-right status bar shows language mode)

Agent changes files I did not intend

• Always use Agent mode with specific, scoped prompts
• Start prompts with file paths: In src/utils/auth.ts, add JWT refresh logic
• Review every diff before accepting — never auto-accept Agent changes

Windsurf uses too much memory

• Exclude node_modules, .next, dist, build from indexing
• Close unused projects (Windsurf indexes all open workspace folders)
• Restart Windsurf daily — long sessions can accumulate memory from indexing

Import from VS Code did not bring my extensions

Windsurf uses the VS Code extension marketplace, but some extensions may not be compatible. Reinstall them manually from the Extensions panel (Cmd+Shift+X). All standard VS Code extensions work — issues typically only affect extensions that hook into VS Code-specific internal APIs.

Related Tutorials

• Claude Code Beginner Tutorial: Complete 2026 Guide
• GitHub Copilot Agent Mode: How to Use It Effectively
• Cursor AI Editor Tutorial: Setup and Best Practices