Windsurf Local Dev Loop

Overview

Set up a fast, AI-augmented local development workflow using Windsurf's Cascade, Turbo mode, Previews, and terminal integration. The goal is a tight loop: edit with Cascade, preview in-IDE, iterate, test, commit.

Prerequisites

• Windsurf authenticated and project open
• Node.js 18+ or Python 3.10+
• Git initialized in project

Instructions

Step 1: Create .windsurfrules for Project Context

<!-- .windsurfrules - placed at project root, committed to git -->

# Project: my-app

## Stack
- Language: TypeScript (strict mode)
- Framework: Next.js 14 (App Router)
- Styling: Tailwind CSS v3
- Testing: Vitest + Testing Library
- Package manager: pnpm

## Architecture
- Server Components by default
- Client Components only when state/interactivity needed
- API routes in app/api/
- Business logic in lib/services/
- Types in lib/types/

## Conventions
- Named exports, never default
- async/await, never raw .then()
- zod for all runtime validation
- Error handling: Result pattern in services

Step 2: Configure .codeiumignore

# .codeiumignore - exclude from AI indexing (same syntax as .gitignore)
node_modules/
.next/
dist/
build/
coverage/
*.min.js
*.map
.env
.env.*

Step 3: Set Up Turbo Mode for Fast Terminal Execution

Turbo mode lets Cascade auto-execute terminal commands without asking permission for each one.

Enable: Windsurf Settings > Cascade > Terminal Execution Level > Turbo

Configure safety lists:

// Settings (JSON) — search "cascadeCommands"
{
  "windsurf.cascadeCommandsAllowList": [
    "npm", "pnpm", "npx", "node", "tsc",
    "vitest", "jest", "eslint", "prettier",
    "git status", "git diff", "git log", "git add"
  ],
  "windsurf.cascadeCommandsDenyList": [
    "rm -rf", "sudo", "git push --force",
    "git reset --hard", "DROP TABLE", "shutdown"
  ]
}

Step 4: Use Previews for UI Development

Ask Cascade to preview your web app:

"Start the dev server and preview the app"

Cascade starts the server and opens an in-IDE Preview tab. From the Preview:

• Click "Send element" (bottom-right) to select a UI element and send it to Cascade
• Console errors are automatically forwarded to Cascade for debugging
• Iterate by describing changes: "Make the header sticky and add a dark mode toggle"

Step 5: The Dev Loop

1. Open Cascade (Cmd/Ctrl+L)
2. Describe the feature or fix
3. Cascade edits files and runs commands (Turbo mode)
4. Preview updates in-IDE (hot reload)
5. Click broken elements → send to Cascade
6. Cascade fixes → repeat until correct
7. Run tests: "Run vitest for the files you changed"
8. Commit: "Commit these changes with message: add dark mode toggle"

Step 6: Terminal Integration

Use Cmd/Ctrl+I in the terminal for natural language commands:

Type: "find all files importing the Button component"
Windsurf generates: grep -rl "import.*Button" src/

Type: "run tests for auth module only"
Windsurf generates: npx vitest run src/auth/

Highlight terminal errors and press Cmd/Ctrl+L to send to Cascade for diagnosis.

Error Handling

Examples

Quick Project Bootstrap

Cascade prompt: "Initialize a new Next.js 14 project with TypeScript,
Tailwind CSS, and Vitest. Set up the folder structure matching
our .windsurfrules conventions."

Debug-Fix Loop

1. See error in terminal or Preview console
2. Highlight error text → Cmd/Ctrl+L → "Fix this error"
3. Cascade reads error, finds root cause, applies fix
4. Preview auto-reloads → verify fix

Resources

• Windsurf Terminal Docs
• Windsurf Previews
• Cascade Overview

Next Steps

See windsurf-sdk-patterns for workspace configuration patterns.