AI Training Hub
Windsurf Track β€” Module 25

Windsurf Setup & Configuration

Getting Windsurf configured correctly from the start β€” the right model, keybindings, context settings, and memories β€” determines your productivity ceiling. This module covers every step from download to first agentic edit, with screenshots at each stage.

Step 1 β€” Download & Install

Download Windsurf

Go to codeium.com/windsurf and download for your OS (macOS, Windows, Linux). Windsurf installs as a standalone VS Code-compatible editor β€” all VS Code extensions, themes, and keybindings work inside it.

Import VS Code Settings (Optional)

On first launch, Windsurf detects any existing VS Code installation and offers to migrate your extensions, keybindings, and settings.json. Accept this for a zero-friction transition.

Sign In to Codeium

Click Sign In in the bottom-left status bar. For enterprise, use your SSO provider. Your account manages model access, usage limits, and Cascade Memories synced across devices.

Windsurf β€” Cascade in Action

shopmate β€” Windsurf
shopmate β€” Windsurf βŠ™ ⊞ βŠ› πŸ”€ EXPLORER β–Ύ shopmate β–Ύ agents support_agent.py order_agent.py β–Ύ routes api.py webhooks.py β–Ύ tests test_agents.py .windsurfrules requirements.txt support_agent.py order_agent.py Γ— 1 2 3 4 5 6 7 8 import anthropic , json, os # Shopmate support agent with tools SYSTEM_PROMPT = """You are ShopMate...""" def run_agent (query: str ): """Single support conversation turn.""" messages = [{ "role" : "user" , "content" : query}] ⬑ Cascade claude-4 You Β· 2 min ago Add retry logic for rate limit errors in run_agent Cascade I'll add exponential backoff retry logic. Editing support_agent.py βœ“ Added tenacity import βœ“ Wrapped create() call βœ“ Added @retry decorator βœ“ Tests passing (8/8) βœ“ Accept All βœ— Reject Ask Cascade anything… ⏎ βŽ‡ main βŠ™ Python 3.11 ⚠ 0 βœ— 0 Cascade: Active

Step 2 β€” Select Model & Configure Cascade

SettingLocationRecommended Value
Default modelSettings β†’ Cascade β†’ Modelclaude-sonnet-4-6 (best balance)
Context scopeSettings β†’ Cascade β†’ ContextWorkspace-wide for most projects
Auto-indexingSettings β†’ Cascade οΏ½οΏ½οΏ½ IndexEnabled β€” updates as you edit
Max output tokensSettings β†’ Cascade β†’ Tokens8192 (increase for large edits)
Confirmation for writesSettings β†’ Cascade β†’ SafetyEnabled for production repos

Step 3 β€” Create .windsurfrules

The .windsurfrules file lives in your project root and is read by Cascade automatically on every session. It encodes your team's conventions once so you never have to repeat them.

Text β€” .windsurfrules (project root)
# ── Language & Runtime ─────────���─────────────────────────────���
Python: 3.11+. Use type hints everywhere. Never use bare `except`.
Node: 20 LTS. TypeScript strict mode. ESM imports only.

# ── Code Style ────────────────────────────────────────────────
Formatter: black (Python), prettier (TS/JS).
Linter: ruff (Python), eslint (TS/JS).
Max line length: 100 chars.
Imports: stdlib β†’ third-party β†’ local, sorted alphabetically.

# ── Architecture ───────────��─────────────────────────────��────
Pattern: Clean architecture. Routes β†’ Services β†’ Repositories.
Forbidden: No business logic in route handlers.
Database: SQLAlchemy ORM. Never raw SQL in application code.
Tests: pytest. Every public function needs a test. Coverage > 80%.

# ── AI / Claude Integration ───────────────────────────────────
Client: Always use the shared `client` singleton from `core/ai.py`.
Model: claude-sonnet-4-6 for production. Haiku for classification.
Errors: Catch anthropic.RateLimitError and retry with backoff.
Tokens: Log input/output tokens for every production API call.

# ── What NOT to do ─────────────────────���──────────────────────
NEVER: Hardcode API keys. Use environment variables.
NEVER: Delete tests. Fix them.
NEVER: Use print() for debugging. Use logging.getLogger(__name__).

Step 4 β€” Set Up Cascade Memories

Memories persist across sessions and devices. Open the Memories panel with Cmd/Ctrl+Shift+M and add entries for your project context:

Cascade Memories β€” Suggested Entries
# Add these in the Memories panel (Cmd+Shift+M)

"This is ShopMate β€” an AI customer support assistant for ThreadCo,
 a T-shirt e-commerce brand. Backend: FastAPI + PostgreSQL."

"Primary AI model: claude-sonnet-4-6. All Claude calls go through
 shopmate/core/ai.py. Never instantiate Anthropic() directly."

"Test framework: pytest with fixtures in conftest.py.
 Run tests with: make test. CI runs on every push to main."

"Database migrations with Alembic. Never modify existing migrations.
 Create new ones with: alembic revision --autogenerate -m 'description'"

Essential Keybindings

ActionMacWindows / Linux
Open Cascade chatCmd+LCtrl+L
Start new Cascade Flow (inline)Cmd+ICtrl+I
Accept inline completionTabTab
Accept next word onlyCmd+β†’Ctrl+β†’
Dismiss completionEscEsc
Open Memories panelCmd+Shift+MCtrl+Shift+M
Toggle AI sidebarCmd+Shift+ACtrl+Shift+A
Accept all Cascade changesCmd+EnterCtrl+Enter
Reject all Cascade changesCmd+BackspaceCtrl+Backspace
πŸ’‘
.windsurfrules is Your Most Valuable Config File

A well-crafted .windsurfrules file that captures your team's conventions, preferred patterns, and forbidden anti-patterns is worth more than any individual prompt. Invest 30 minutes writing it on day one β€” it compounds over every session thereafter. Commit it to your repository so the whole team benefits.

← Windsurf Overview Next: Cascade Engine β†’