Windsurf IDE Complete Installation Guide: Download, Cascade AI Setup, Custom Models & Git Integration

Windsurf IDE Complete Installation Guide: From Download to Your First AI-Powered Project

Windsurf IDE by Codeium is an AI-native code editor built on a VS Code foundation, featuring Cascade — an agentic AI coding assistant that understands your entire codebase. This guide walks you through every step from installation to launching your first project with full AI and Git integration.

Step 1: Download and Install Windsurf IDE

• Visit the official Windsurf website at codeium.com/windsurf and click Download for Free.
• Select your operating system (Windows, macOS, or Linux).
• Run the installer: # Windows — run the downloaded .exe installer WindsurfSetup-x.x.x.exe

sudo rpm -i windsurf-x.x.x.x86_64.rpm

• Launch Windsurf IDE. On first launch, you will be prompted to sign in or create a Codeium account.
• Sign up using your email, Google, or GitHub account to activate the free tier.

Step 2: Initial Configuration and Theme Setup

• On first launch, Windsurf offers to import settings from VS Code. Select Import Settings if you are migrating.
• Choose your preferred color theme and keymap bindings.
• Open Settings with Ctrl+, (Windows/Linux) or Cmd+, (macOS) to customize editor preferences:

// settings.json recommended baseline
{
  "editor.fontSize": 14,
  "editor.minimap.enabled": false,
  "editor.formatOnSave": true,
  "editor.tabSize": 2,
  "windsurf.cascade.autoContext": true
}

Step 3: Activate and Configure Cascade AI Assistant

Cascade is Windsurf's flagship AI feature. It operates in two modes: **Write mode** (code generation and editing) and **Chat mode** (Q&A and codebase exploration).

• Open the Cascade panel by pressing Ctrl+L (or Cmd+L on macOS), or click the Cascade icon in the sidebar.

• Verify your account is connected — you should see your username at the bottom of the panel.

• Test Cascade by typing a prompt: Create a REST API with Express.js that has CRUD endpoints for a todo list with input validation

• Cascade will analyze your workspace, generate files, and offer to apply changes. Click Accept All to apply.

Cascade Modes Explained

Step 4: Select and Configure Custom AI Models

Windsurf supports multiple AI models. You can switch models based on task complexity.

• Open the Cascade panel and click the model selector dropdown at the top.

• Available models include GPT-4o, Claude Sonnet, Claude Opus, and Codeium’s own models. Pro and Ultimate tier users unlock premium models.

• For API-based custom model configuration, navigate to Settings > Windsurf > Model Configuration: // Custom model provider configuration { “windsurf.modelProvider”: “custom”, “windsurf.customEndpoint”: “https://api.your-provider.com/v1”, “windsurf.customApiKey”: “YOUR_API_KEY”, “windsurf.customModelId”: “your-model-name” }

• Test the connection by sending a simple prompt to Cascade after saving.

Step 5: Git Integration Setup

Windsurf inherits VS Code's Git integration and adds AI-enhanced commit workflows.

• Ensure Git is installed on your system: git —version

Linux: sudo apt install git

• Configure your Git identity:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

• Initialize a repository or clone an existing one:

# New project
mkdir my-project && cd my-project
git init

# Clone existing
git clone https://github.com/your-username/your-repo.git
cd your-repo

• Open the project in Windsurf:

windsurf .

• Use the Source Control panel (Ctrl+Shift+G) to stage, commit, and push. Cascade can auto-generate commit messages — click the sparkle icon in the commit message box.

Step 6: Start Your First Project

• Create a new project directory and open it in Windsurf.
• Open Cascade (Ctrl+L) and describe what you want to build:

Scaffold a Next.js 14 project with TypeScript, Tailwind CSS, and a landing page component with a hero section and feature grid

• Review the proposed changes in the diff view. Cascade shows exactly what files will be created or modified.
• Accept the changes and run the development server:

npm install
npm run dev

• Continue iterating by giving Cascade follow-up instructions to refine your code.

Pro Tips for Power Users

• Context Pinning: Use @file or @folder mentions in Cascade prompts to direct the AI’s attention to specific parts of your codebase: @src/utils/auth.ts refactor this to use JWT tokens.
• Terminal Integration: Cascade can read terminal output. If a build fails, paste the error or ask Cascade to check the terminal for errors.
• Multi-file Awareness: Cascade indexes your entire workspace. Ask broad questions like “Where is the user authentication logic and how does it connect to the database?”
• Keyboard Shortcut Mastery: Press Ctrl+Shift+P and type Windsurf to see all available AI commands.
• Extension Compatibility: Most VS Code extensions work in Windsurf. Install them via the Extensions panel (Ctrl+Shift+X).
• Memory and Rules: Create a .windsurfrules file in your project root to define persistent instructions for Cascade, such as coding style or framework preferences.

Troubleshooting Common Issues

Frequently Asked Questions

Is Windsurf IDE free to use, and what are the plan differences?

Yes, Windsurf offers a free tier that includes Cascade AI with limited premium model credits, autocomplete, and full editor functionality. The Pro plan adds more credits and access to advanced models like Claude Opus and GPT-4o. The Ultimate plan provides unlimited flows and priority access to the latest models. All plans include Git integration, extension support, and the full editor experience.

Can I use Windsurf with existing VS Code extensions and settings?

Windsurf is built on the VS Code foundation and supports the vast majority of VS Code extensions. On first launch, you can import your existing VS Code settings, keybindings, and extensions. Some AI-specific extensions like GitHub Copilot may conflict with Cascade — it is recommended to disable competing AI autocomplete extensions to avoid duplicate suggestions.

How does Cascade differ from regular AI code assistants like Copilot?

Cascade is an agentic AI assistant, meaning it can autonomously perform multi-step tasks across multiple files. Unlike traditional autocomplete-based assistants, Cascade can read your entire codebase, create and modify multiple files in a single operation, run terminal commands, and maintain context across a conversation. It operates more like an AI pair programmer than a suggestion engine.