​
Windsurf Development Environment Setup Guide

​
Overview

Windsurf workspaces rely exclusively on open‑source tooling for compiling, linting, and debugging. Microsoft’s proprietary Visual Studio components cannot be redistributed, so we integrate community‑maintained language servers, debuggers, and compilers instead. This guide covers two stacks:
  1. .NET / C# – targeting both .NET Core and .NET Framework (via Mono)
  2. C / C++ – using clang‑based tooling
You can install either or both in the same workspace.
⚠️ Important: The examples below are templates that you must customize for your specific project. You’ll need to edit file paths, project names, and build commands to match your codebase.

​
1. .NET / C# development

Choose the flavour that matches your codebase.

​
.NET Core / .NET 6+

Extensions:
  • C# (muhammad-sammy.csharp) – bundles OmniSharp LS and NetCoreDbg, so you can hit F5 immediately
  • .NET Install Tool (ms-dotnettools.vscode-dotnet-runtime) – auto‑installs missing runtimes/SDKs
  • Solution Explorer (fernandoescolar.vscode-solution-explorer) – navigate and manage .NET solutions and projects
Debugger: Nothing else is required—the extension already contains the language server and an open‑source debugger suitable for .NET Core. Build: dotnet build

​
.NET Framework via Mono

Extensions:
  • Mono Debug (chrisatwindsurf.mono-debug) – debug adapter for Mono (Open VSX)
  • C# (muhammad-sammy.csharp) for language features
Debugger: You must also install the Mono tool‑chain inside the workspace. Follow the install guide in the Mono repo. The debugger extension connects to that runtime at debug time.
⚠️ .NET Framework Configuration: After installing Mono, to use the C# extension with .NET Framework projects, you need to toggle a specific setting in the IDE Settings. Go to Settings (in the C# Extension section) and toggle off “Omnisharp: Use Modern Net”. This setting uses the OmniSharp build for .NET 6, which provides significant performance improvements for SDK-style Framework, .NET Core, and .NET 5+ projects. Note that this version does not support non-SDK-style .NET Framework projects, including Unity.
Build: mcs Program.cs

​
Configure tasks.json for Your Project

You must create/edit .vscode/tasks.json in your workspace root and customize these templates: 
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-dotnet",
      "type": "shell",
      "command": "dotnet",
      "args": ["build", "YourProject.csproj"], // ← Edit this
      "group": "build",
      "problemMatcher": "$msCompile"
    },
    {
      "label": "build-mono",
      "type": "shell",
      "command": "mcs",
      "args": ["YourProgram.cs"], // ← Edit this
      "group": "build"
    }
  ]
}

​
Configure launch.json for Debugging

You must create/edit .vscode/launch.json in your workspace root and update the paths: 
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Launch",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build-dotnet",
      "program": "${workspaceFolder}/bin/Debug/net6.0/YourApp.dll", // ← Edit this path
      "cwd": "${workspaceFolder}",
      "args": [] // Add command line arguments if needed
    },
    {
      "name": "Mono Launch",
      "type": "mono",
      "request": "launch",
      "preLaunchTask": "build-mono",
      "program": "${workspaceFolder}/YourProgram.exe", // ← Edit this path
      "cwd": "${workspaceFolder}"
    }
  ]
}

​
CLI equivalents

# .NET Core
$ dotnet build
$ dotnet run

# Mono / .NET Framework
$ mcs Program.cs
$ mono Program.exe

​
.NET Framework Limitations

⚠️ Important: .NET Framework codebases with mixed assemblies (C++/CLI) or complex Visual Studio dependencies have significant limitations in Windsurf. These codebases typically require Visual Studio’s proprietary build system and cannot be fully compiled or debugged in Windsurf due to dependencies on Microsoft-specific tooling and assembly reference resolution. Recommended approaches for .NET Framework projects:
  • Use Windsurf alongside Visual Studio for code generation and editing
  • Migrate compatible portions to .NET Core where possible

​
2. C / C++ development

Required Extensions:
ExtensionPurpose
Windsurf C++ Tools (Codeium.windsurf-cpptools)This is a bundle of the three extensions we recommend using to get started. Package that contains C/C++ LSP support, debugging support, and CMake support.
Note: Installing the Windsurf C++ Tools bundle will automatically install the individual extensions listed below, so you only need to install the bundle.
ExtensionPurpose
clangd (llvm-vs-code-extensions.vscode-clangd)clangd language‑server integration. If clangd is missing it will offer to download the correct binary for your platform.
CodeLLDB (vadimcn.vscode-lldb)Native debugger based on LLDB for C/C++ and Rust code.
CMake Tools (ms-vscode.cmake-tools)Project configuration, build, test, and debug integration for CMake‑based projects.
For non‑CMake workflows you can still invoke make, ninja, etc. via custom tasks.json targets.

​
Configure C/C++ Build Tasks

Create/edit .vscode/tasks.json for your C/C++ project: 
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build-cpp",
      "type": "shell",
      "command": "clang++",
      "args": ["-g", "main.cpp", "-o", "main"], // ← Edit for your files
      "group": "build",
      "problemMatcher": "$gcc"
    }
  ]
}

​
3. Notes & Gotchas

  • Open‑source only – decline any prompt to install proprietary Microsoft tooling; Windsurf containers cannot ship it.
  • Container vs Host – SDKs/compilers must be present inside the Windsurf workspace container.
  • Keyboard shortcuts
    • Ctrl/⌘ + Shift + B → compile using the active build task
    • F5 → debug using the selected launch.json config

​
4. Setup Checklist

  • Install the required extensions for your language stack
  • Create and customize .vscode/tasks.json with your project’s build commands
  • Create and customize .vscode/launch.json with correct paths to your executables
  • For Mono: install the runtime and verify mono --version
  • Update file paths, project names, and build arguments to match your codebase
  • Test your setup: Press Ctrl/⌘ + Shift + B to build, then F5 to debug
💡 Tip: The configuration files are project-specific. You’ll need to adapt the examples above for each workspace.