$devvkit learn --librarie windsurf-guide

Windsurf Guide

[ai][editor][agent][vibe-coding]

AI / LLM Tools

Install

# Download from codeium.com/windsurf/download
# Or:
brew install --cask windsurf
# Windows/Linux: download from codeium.com/windsurf

Windsurf (by Codeium) is an AI-native IDE built from the ground up (not a VS Code fork). Its signature feature is Cascade — an agentic mode that writes code, runs terminal commands, detects and fixes errors, and navigates your codebase without explicit instructions.

Cascade works in two modes: Write (agentic — creates files, runs commands, fixes issues) and Chat (conversational — answer questions, explain code). Cascade automatically detects errors: if it writes code that has a TypeScript error, it reads the error, analyzes the fix, and applies it without asking.

Windsurf's Supercomplete provides inline autocomplete that considers your entire codebase, not just the open file. The Indexer builds a codebase-wide semantic index for more relevant completions. Windsurf is free for individual use with a Codeium account.

Setup

Open Cascade— Start an AI session.

# Windows/Linux: Ctrl+Shift+A
# Mac: Cmd+Shift+A

# Cascade panel opens on the right
# Two modes: Write (agent) and Chat (conversation)

# Or use quick actions:
# Cmd+Shift+I: Inline chat
# Ctrl+Space: Trigger Supercomplete

Index your codebase— Improve AI understanding.

# Windsurf builds a semantic index of your project
# This powers: Supercomplete + Cascade codebase awareness

# Check index status:
# Click the flame icon in the status bar
# Shows: "Indexing complete" or "Indexing in progress"

# Force re-index:
# Settings > Windsurf > Rebuild Index

# Exclude files (to save resources):
# Settings > Windsurf > Index Exclude Patterns
# Add: **/node_modules/**, **/.next/**

Cascade — Write Mode

Cascade Write— Agentic multi-file edits.

# Switch Cascade to "Write" mode
# Describe what you want:
"Create a full authentication system with NextAuth"

# Cascade will:
# 1. Read relevant existing files
# 2. Create new files
# 3. Install necessary packages
# 4. Run the build and fix errors
# 5. Show you the final result

# Cascade auto-detects and fixes errors!
# If it writes broken code, it reads the error
# and fixes it immediately

Auto-fix workflow— Cascade fixes its own errors.

# Cascade's killer feature: automatic error recovery

# Example workflow:
# 1. You: "Add a Prisma User model with email and password"
# 2. Cascade writes schema.prisma, generates client
# 3. Cascade runs `npx prisma generate`, detects error
# 4. Cascade fixes the error, re-runs, succeeds
# 5. Cascade: "Done. The schema is ready at prisma/schema.prisma"

# You only see the final working result.

Cascade — Chat Mode

Cascade Chat— Conversational Q&A.

# Switch to "Chat" mode for questions:
"Explain this authentication flow"
"What does this error mean?"
"Where are the API routes defined?"
"How does the database schema relate to the types?"
"Suggest improvements for this function"

# Chat mode reads your codebase naturally
# Ask about specific files or the whole project

Supercomplete

Supercomplete— Codebase-aware autocomplete.

# Supercomplete triggers automatically as you type
# It considers:
# - Your entire codebase (not just open file)
# - Imports and types from dependencies
# - Existing patterns in the project
# - Recent edits and cursor context

# Always accept: Tab
# Ctrl+Right: Accept next word
# Ctrl+Left: Accept previous suggestion
# Ctrl+] : Next suggestion
# Ctrl+[ : Previous suggestion

# Tip: Type well-named function signatures
# Supercomplete fills the implementation

Tips

Flow mode— Distraction-free coding.

# Toggle Flow mode: Ctrl+Shift+Enter
# Hides the sidebar, focuses on editor
# Cascade panel auto-hides when not in use

# In Flow mode:
# - Type normally for autocomplete
# - Press Escape to open Cascade
# - Press Escape again to hide Cascade

# Best for: deep focus sessions
# where you want minimal UI distraction