Windsurf Getting Started: Installation, Setup, and First Project

Overview

Windsurf is an AI-native code editor built by Codeium. It forks VS Code and adds Cascade — an agentic AI assistant that can read your codebase, edit multiple files, run terminal commands, and iterate on errors autonomously. Unlike bolt-on extensions, Cascade is integrated at the editor level with full context awareness.

This guide covers installation, initial configuration, importing your existing setup, and running your first Cascade session. You’ll have a working Windsurf environment in under 10 minutes.

Prerequisites

• OS: macOS 10.15+, Windows 10+, or Linux (Ubuntu 20.04+, Fedora 36+, Arch)
• RAM: 8 GB minimum, 16 GB recommended
• Disk: ~500 MB for the editor plus extensions
• Account: Free Codeium account (sign up during first launch)
• Optional: Existing VS Code installation (for settings import)

No API keys required for the free tier. Pro and Team plans unlock higher usage limits and additional model access.

Step 1: Download and Install

macOS (Homebrew):

brew install --cask windsurf

Linux (Debian/Ubuntu):

# Download the .deb from windsurf.com, then:
sudo dpkg -i windsurf_*.deb
sudo apt-get install -f

Windows: Run the downloaded .exe installer. Default path is C:\Users\<you>\AppData\Local\Programs\Windsurf.

On first launch, Windsurf opens a welcome tab and prompts you to sign in or create a Codeium account.

Step 2: Import VS Code Settings

If you’re migrating from VS Code, Windsurf can import your extensions, keybindings, and settings in one step.

1. Open the Command Palette: ⌘ + Shift + P (macOS) or Ctrl + Shift + P (Windows/Linux)
2. Type Import VS Code Settings
3. Select the profile to import

Windsurf uses the Open VSX registry by default but supports most VS Code extensions. Extensions relying on proprietary Microsoft APIs (Live Share, Remote SSH) may not be available — check the marketplace before switching fully.

Step 3: Open a Project and Launch Cascade

Open a project folder via File > Open Folder or from the terminal:

windsurf ~/projects/my-app

The Cascade panel lives on the right side of the editor. Open it with ⌘ + L (macOS) or Ctrl + L (Windows/Linux).

Cascade offers two primary modes:

• Chat mode — Ask questions about your codebase. Cascade reads relevant files and provides answers with file references.
• Write mode — Give Cascade a task. It plans the changes, edits files, runs commands, and iterates until done.

Toggle between modes using the dropdown at the top of the Cascade panel.

Step 4: Your First Cascade Session

Try a simple task to see Cascade in action. In Write mode, type:

Create a basic Express server with a /health endpoint that returns { status: "ok" }

Cascade will:
1. Check if package.json exists; if not, run npm init -y
2. Install Express
3. Create the server file
4. Optionally run the server and verify the endpoint

You’ll see each step in the Cascade panel with diffs for file changes. Accept or reject individual edits before they’re saved.

Step 5: Configure Cascade Rules

Windsurf supports project-level AI rules via a .windsurfrules file in your project root. This file shapes how Cascade behaves for your specific codebase.

# .windsurfrules

- Use TypeScript strict mode for all new files
- Prefer functional components with hooks over class components
- Run `npm run lint` after making changes
- Never modify files in the /generated directory

Place this file at the project root. Cascade reads it automatically on each interaction. Use it to enforce coding standards, prevent unwanted modifications, and guide Cascade toward your team’s conventions.

Step 6: Explore Key Features

Autocomplete (Tab): Windsurf provides inline completions as you type. Press Tab to accept, Esc to dismiss.

Cmd+K inline edits: Select code, press ⌘ + K, and describe the change. Cascade edits the selection in-place.

Multi-file context: Cascade automatically indexes your project. Use @ mentions in the chat to reference specific files, folders, or symbols:

@src/auth/login.ts refactor the token validation to use jose instead of jsonwebtoken

Terminal integration: Cascade can read terminal output. If a build fails, type “fix this error” and Cascade picks up the terminal context.

Tips and Best Practices

• Be specific in prompts. “Add input validation to the signup form using zod” produces better results than “improve the form.”
• Use .windsurfrules early. Define conventions before Cascade writes code you’ll need to refactor later.
• Review diffs carefully. Accept edits file-by-file. Cascade sometimes modifies files outside the intended scope.
• Leverage @ mentions. Pointing Cascade to specific files reduces hallucination and speeds up responses.
• Check free tier limits. The free plan includes limited Cascade interactions per month. Monitor usage in the account panel to avoid hitting walls mid-session.

Troubleshooting Common Issues

Cascade not indexing files: Large monorepos may take time to index. Check the status bar for indexing progress. Add large generated directories to .windsurfignore.

Extensions missing after import: Some VS Code extensions aren’t on Open VSX. Search the Windsurf marketplace for alternatives, or install .vsix files manually.

Slow completions: Disable other AI extensions (GitHub Copilot, Codeium VS Code extension) to avoid conflicts. Only one AI completion provider should be active.

FAQ