Windsurf Tutorial

Step 1: Install Windsurf and Authenticate

First, open Visual Studio Code. Go to the Extensions marketplace (the square icon on the left sidebar or press Ctrl+Shift+X). Search for 'Windsurf'. You'll see 'Windsurf – Codeium's AI Editor' – install it. Once installed, a Windsurf icon (a surfboard on a wave) will appear in your left sidebar. Click it. A welcome pane will open. Click 'Sign In'. This will open your browser to authenticate with Codeium. I recommend signing in with GitHub; it's seamless for the next steps. After auth, VS Code will confirm you're connected. What surprised me was how lightweight the install was—it doesn't feel like a bulky overlay, but a native part of the editor. You're now ready to provide context.

Step 2: Connect Your Repository and Index Your Codebase

This is the critical step most beginners miss. Windsurf's power comes from deep context. In the Windsurf sidebar, find and click the 'Repositories' section. Click 'Add Repository'. You'll see a list of your GitHub repos. For your first test, pick a small-to-medium project you understand well—not a massive monorepo. Click 'Add' next to it. Windsurf will begin 'indexing' the repo. This is where it analyzes your entire codebase to understand the structure, dependencies, and patterns. In my experience, indexing a 50-file project takes under a minute. A progress bar will show in the bottom status bar. Wait for it to complete. You'll know it's done when you can browse your project's files from within the Windsurf sidebar. This index is what allows Cascade to work its magic across files.

Step 3: Craft Your First Cascade Command

Now for the fun part. Cascade is Windsurf's flagship feature. Don't just ask for a single-line change. Think bigger. In the Windsurf sidebar, click the 'Cascade' tab (it looks like a waterfall). In the command input, describe a multi-file change. For example: 'Add a new configuration setting called `timeoutSeconds` to the config loader in `src/config.js`, then update all API call functions in `src/api/` to use this new setting, and finally add a unit test for the config loader change in `test/config.test.js`.'. Be specific about files and intent. Then, press Enter. Windsurf will analyze your request, break it down, and show you a detailed, step-by-step plan in the chat pane. It will list every file it intends to change and why. This transparency is what sold me—you're not running a black box.

Step 4: Review, Approve, and Execute the Plan

Windsurf's plan will appear in the chat. Read it carefully. I've tested this on dozens of projects, and its dependency mapping is impressive, but not infallible. It might, for instance, correctly identify that a utility function in `src/utils/helpers.js` also needs the new config parameter. If the plan looks good, click the 'Approve' button. Windsurf will then start executing. It opens each file in a temporary 'diff' view, showing you the proposed changes in green (additions) and red (removals), just like a Git diff. You can review each change inline. If something looks off, you can reject that specific file change. Once you're satisfied, click 'Apply All'. The changes are written to your actual files. The feeling of watching it correctly refactor five files in 30 seconds is exhilarating.

Step 5: Use Chat and Completions for Daily Work

Beyond Cascade, Windsurf is your always-on pair programmer. For small tasks, open the Chat (the message bubble icon in the sidebar). Here, you can ask questions about your code. The key difference from Copilot Chat? It uses your indexed repository for context. Try '@' mentioning a file: 'Explain the `calculateInvoice` function in `@src/billing.js`.'. It will pull the actual code and give a precise explanation. For real-time coding, just type. Windsurf's inline completions (light grey suggestions) are powered by the same context. I found them more accurate than vanilla Codeium for project-specific patterns. They often suggest whole blocks of code that match your existing style. My stance: use Chat for exploration and explanations, Cascade for heavy lifting, and completions for flow state coding.

Step 6: Explore Settings and Manage Context

To make Windsurf truly yours, open VS Code Settings (Ctrl+,) and search for 'Windsurf' or 'Codeium'. Key settings I adjust: 'Windsurf: Cascade Auto-Approval' (keep this OFF as a beginner), and 'Codeium: Enable Line Completions' (I leave this ON). More importantly, manage your indexed context. In the Windsurf sidebar, go back to 'Repositories'. You'll see your connected repo. Hover over it and click the '...' menu. Here you can 'Re-index' if you've made major changes outside of Windsurf, or 'Remove' it. I recommend re-indexing after large merges or architectural shifts. The free tier has generous limits, but be mindful of indexing huge, unused repos as they count against your context window. This management is crucial for maintaining accuracy.