Windsurf

Overview

Windsurf is an AI-native IDE released by Codeium in 2024; in 2026 it is ranked alongside Cursor as a top-tier AI-native IDE. Rather than simply bolting a plugin onto VS Code, it deeply refactors the platform. Its core feature, Cascade, is an agent that understands both editor and terminal context at the same time, enabling a collaborative workflow of "editor writes code + terminal runs commands" so the AI can debug and iterate like a real developer.

Core features: AI-native IDE, Cascade agent, editor/terminal collaboration, beyond code completion.

Installation

Download the installer from the official site; Windows, macOS, and Linux are supported. After installation you can one-click import your VS Code configuration and extensions, so migration cost is minimal.

# Download links
# Official site: https://windsurf.com
# Download page: https://windsurf.com/download

# Windows: download the .exe installer and run it
# macOS:   download the .dmg and drag it into Applications
# Linux:   download the .tar.gz or .deb

# First launch → sign in to your Codeium account → import VS Code settings

Windsurf offers a free tier and a Pro version; the free tier already includes the core capabilities of the Cascade agent.

Basic Usage

At the heart of Windsurf is the Cascade panel (Cmd/Ctrl+L), which senses both editor content and terminal state. You can have it write code, run commands, read errors, and auto-fix them in a closed loop. Write mode is good for creating from scratch, Chat mode for Q&A, and Cascade mode is the fully autonomous Agent.

# Launch the Cascade agent
Cmd/Ctrl + L    # Open the Cascade panel

# Cascade example (autonomous agent)
"Initialize an Express + TypeScript project, set up ESLint and tests, and get hello world running"

# Cascade will automatically:
# 1. Create package.json and tsconfig.json
# 2. Install dependencies (run npm install in the terminal)
# 3. Write code, run tests, and fix errors

# Inline completion: press Tab to accept

Cascade shows every step of its plan and actions, and you can pause or change direction at any time.

Tips

Windsurf's strength is the deep collaboration between editor and terminal—Cascade can see terminal errors and fix them automatically, with no need to copy error messages by hand. Use @ to reference files or terminal output to control context precisely. For large tasks, discuss the plan in Chat mode first, then execute in Cascade mode. Codeium's free tier is very friendly to individual developers.

# Reference context precisely
"Following the structure in @src/models/user.ts, fill in the CRUD endpoints in @src/api/users.ts"

# Have Cascade read the terminal error and fix it
# After a terminal error, type in Cascade:
"The terminal just errored, help me fix it"

# Switch modes
# Toggle at the top of the Cascade panel: Write / Chat / Agent

Tip: Cascade asks for confirmation before running terminal commands; for sensitive operations (e.g. rm, deploy), keep confirmation on.

Configuration

Windsurf is configured through the Cascade panel and a project-level rules file. The Cascade panel toggles between Write, Chat, and Agent modes and lets you pick a model. A .windsurfrules file in the project root defines conventions the agent follows, similar to .cursorrules. Sign in with a Codeium account to unlock the free tier or Pro features.

# Project rules (project root)
# .windsurfrules
Prefer TypeScript strict mode.
Never use 'any'; add JSDoc to public functions.

# Mode switching (top of Cascade panel)
# Write  — generate code from scratch
# Chat   — Q&A, no edits
# Agent  — fully autonomous (runs commands, fixes errors)

# Model selection
# Cascade panel -> model dropdown

# Reference context precisely
"Following the structure in @src/models/user.ts, fill in @src/api/users.ts"

# Account & billing
# Sign in with Codeium account -> free tier or Pro

Cascade asks for confirmation before terminal commands; keep confirmation on for sensitive ops like rm or deploy.

FAQ

Common questions cover the free tier, model selection, Cascade vs Chat, privacy, and how Cascade reads terminal errors. Windsurf's free tier includes the core Cascade agent; Pro adds faster models and higher limits. Cascade senses both editor and terminal state, so it can auto-fix errors without you copying messages.

Q: Is there a free tier?
A: Yes—Windsurf's free tier includes the core Cascade agent; Pro adds
   faster models and higher limits.

Q: How is Cascade different from Chat?
A: Chat is Q&A only; Cascade (Agent) edits files, runs terminal commands,
   and auto-fixes errors in a closed loop.

Q: Can Cascade see terminal errors?
A: Yes—Cascade senses terminal state, so after an error just ask it to
   fix the problem without pasting the message.

Q: How do I control context?
A: Use @ to reference files, folders, or terminal output precisely.

Q: How do I cut token costs?
A: Discuss plans in Chat mode first, then execute in Cascade; avoid long
   autonomous loops on the most expensive models.

For large tasks, discuss the plan in Chat mode first, then execute in Cascade mode.