Try this tool today

Accelerate your vibe coding workflow with our partner link.

Get Started →

Windsurf is an AI-assisted code editor built by Codeium, constructed as a fork of VS Code. It matters when your workflow requires code completion, generation, or chat assistance integrated directly in the editor rather than shunted to a separate interface or browser tab. The editor preserves VS Code’s extension ecosystem while layering on AI features through a combination of /commands, a persistent chat panel, and agent mode. This reference page covers getting started, common tasks, configuration, and the failure modes you’ll actually encounter.

Starting up and basic operation

Windsurf is distributed as a standalone application bundle for macOS, Windows, and Linux. The binary is typically found at /Applications/Windsurf.app/Contents/MacOS/Windsurf on macOS, C:\Program Files\Windsurf\Windsurf.exe on Windows, or extracted from the tarball on Linux. On first launch, the editor prompts for an API key tied to a Codeium account. If you already have a Codeium account used with their VS Code extension, the same credentials work here.

Once running, the interface resembles VS Code: activity bar on the left, editor in the center, and a chat panel accessible via the right-side button or ⌘L (macOS) / Ctrl+L (Windows/Linux). The chat panel is the default entry point for AI interaction, but the real distinctive feature set lives in the /commands palette, opened with ⌘ShiftP (macOS) / Ctrl+Shift+P (Windows/Linux).

Writing and editing code with AI

Chat-assisted editing

The chat panel supports free-form requests. You can select a region of code in the editor, focus the chat input, and type a request like “refactor this function to use dependency injection” or “explain what this regex does.” Windsurf sends the selected context plus your prompt to the configured LLM and returns a response that can be applied as a code edit with a single click, or dismissed.

/commands palette

The /commands palette is organized by task category. Each command is a pre-prompted interaction that sends a specific structured request to the LLM. Here are the commands that ship with the default installation:

  • /docs – Takes a natural language question and searches the open workspace for relevant code, returning snippets with file paths and line numbers. Useful for answering “where is the API route handler defined?” without leaving the editor.
  • /compact – Summarizes the currently selected code or the entire active file. The output is a concise paraphrase suitable for pasting into meeting notes or documentation.
  • /terminal – Given a description of what you want to achieve, generates a shell command. For example, typing “list all Python files modified in the last 7 days” produces a find or git log command. The command is inserted into the terminal panel, where you can review and execute it.
  • /fix – When you have compilation errors or test failures visible in the PROBLEMS panel, /fix sends the error messages and surrounding context to the LLM and returns a patch. Apply the patch to auto-resolve the issue, or inspect it first.
  • /explain – Given selected code, returns a plain-English breakdown of what it does, line by line. Helpful for onboarding or revisiting code you wrote months ago.

Each command remains in the history of the chat panel after execution, so you can iterate—asking the model to adjust the generated code, add error handling, or rewrite in a different style.

Agent mode

Windsurf includes an agent mode accessible from the chat panel’s mode selector. When enabled, the agent can edit multiple files, run terminal commands, and commit changes based on a high-level goal you state. For example, “add a health check endpoint to the service and run the tests” might cause the agent to modify routes.py, update Dockerfile instructions, and execute pytest. The agent operates within the bounds of your workspace and respects .gitignore and .windsurfignore patterns. You retain a review step before any change is finalized; the agent never pushes directly to a remote repository.

Configuration

Windsurf’s configuration lives in two places: the VS Code–compatible settings.json file, and a windsurf top-level object within that same file for AI–specific keys.

settings.json entries

{
  "windsurf.aiProvider": "openai",
  "windsurf.model": "gpt-4o-mini",
  "windsurf.apiKey": "sk-…",
  "windsurf.chat.agentEnabled": true,
  "windsurf.chat.maxTokens": 4096,
  "editor.tabSize": 2
}
  • windsurf.aiProvider selects the LLM backend. Supported values include openai, anthropic, and google. If unset, Windsurf defaults to the provider associated with your API key.
  • windsurf.model specifies the model name within the chosen provider. Values are provider-specific—for OpenAI, valid entries match the published model identifiers (gpt-4o, gpt-4o-mini, gpt-4-turbo, etc.).
  • windsurf.apiKey is the secret used to authenticate outbound requests. On macOS and Linux, the key can be stored in the keychain if you opt into the prompt on first run. On Windows, it’s written to a local file in the application data directory.
  • windsurf.chat.agentEnabled toggles agent mode on or off. When false, the agent button is removed from the chat UI and the model only responds to explicit prompts.
  • windsurf.chat.maxTokens caps the combined input+output token count for chat completions. If the context window is exceeded, the oldest messages are trimmed.

Agent sandboxing

When agent mode is enabled, Windsurf runs generated terminal commands in a subprocess with the current workspace as the working directory. The subprocess is constrained by the OS-level security model of your user account—it cannot, for example, escalate privileges or access files outside the project root unless you explicitly grant permission. A common failure mode is the agent attempting chmod 777 on a directory it doesn’t own, which silently fails on macOS System Integrity Protection–protected paths or on Linux when running as a non-root user. The error message in the terminal reads:

Permission denied @ apply2files - ...

If you encounter this, either adjust the directory ownership or disable agent mode for tasks requiring elevated permissions.

Common workflows

Onboarding into a new codebase

  1. Open the command palette and run /docs with the question “What is the request lifecycle for this app?”
  2. Review the returned snippets. Windsurf highlights the matching files in the sidebar.
  3. Follow up with /explain on any snippet that needs deeper clarification.
  4. Use /fix if the explanation reveals a pattern you want to refactor across multiple files.

Debugging a failing test

  1. Ensure the test failure is visible in the PROBLEMS panel.
  2. Open the chat panel and invoke /fix.
  3. The agent sends the full error output, stack trace, and surrounding test code to the LLM.
  4. The returned patch is displayed in a diff view. Accept or reject individual hunks.
  5. If the fix introduces a new error, repeat the process—/fix is idempotent and can be called iteratively.

Generating a new endpoint

  1. Create a new file (e.g., routes/health.py).
  2. In the chat, type a natural language description: “Add a GET /health endpoint that returns 200 OK with {"status": "ok"}.”
  3. Windsurf suggests a code block. You can accept it directly, or ask the model to adjust the response format or add logging.
  4. Use /terminal to generate the import statement or boilerplate if you’re working in an unfamiliar framework.

Sharp edges and failure modes

Context window exhaustion

Windsurf’s chat panel, like all LLM–backed editors, has a finite context window. When you’ve accumulated many turns, large file selections, or extensive /command histories, the editor begins dropping the oldest messages. You’ll notice the model’s answers become increasingly generic or “forgetful” of earlier context. There is no UI indicator of remaining tokens, but a practical signal is when the model starts asking “which file are you referring to?” or repeats itself. To mitigate this, periodically start a new chat tab for unrelated topics, or use /compact to distill long discussions into summaries before continuing.

Model availability and rate limits

If your windsurf.aiProvider is set to openai and you exhaust your rate limit, every subsequent request returns:

Error: 429 - Rate limit reached. Upgrade your plan or wait until the window resets.

The editor does not retry automatically. You must either wait, switch to a different provider configured in settings.json, or reduce the frequency of /command invocations. Similarly, if your API key is malformed or expired, the error is:

Error: 401 - Invalid or missing authentication credentials.

Verify the key in the Codeium dashboard and reload the editor.

Agent overreach

Agent mode is powerful but not infallible. In a few documented cases, the agent has attempted to write files outside the project root, modify .git metadata, or issue rm -rf commands on paths it misinterpreted. Windsurf mitigates this by confining the agent’s subprocess to the workspace root, but symbolic links and Docker mount points can blur those boundaries. If you observe the agent modifying files you didn’t intend, immediately stop the agent, revert the changes with git checkout -- ., and inspect the windsurf session log located at ~/.windsurf/sessions/<timestamp>.json for a record of what was executed.

Confused configuration keys

Two settings are easy to mix up:

  • windsurf.model – Selects which LLM model the chat and /commands use.
  • editor.defaultLanguageModel (a VS Code setting that also affects Windsurf) – Controls the inline completion model, which is separate from the chat /command model.

If your chat responses seem to use a different model than your inline completions, check both keys. The inline completion model is typically gpt-4o-mini by default, while the chat /command model is governed by windsurf.model. Setting one without the other leads to a disjointed experience where completion suggestions and chat answers come from different backends.

windsurfignore patterns

Windsurf respects a .windsurfignore file at the workspace root for agent operations and /command context selection. Patterns follow the same syntax as .gitignore, but a common mistake is placing .windsurfignore in a subdirectory where the agent doesn’t look. If the agent reports “no files found” despite files being present, verify that .windsurfignore is at the top level of the workspace. Inverted patterns (e.g., !important.txt) are supported but must appear after the matching pattern to take effect—a detail that catches out users migrating from .gitignore habits.

Closing notes

Windsurf’s value lies in collapsing the distance between idea and implementation. The /commands palette, chat panel, and agent mode each address a distinct point in the development cycle—querying code, explaining it, fixing it, or generating it—but they share the same underlying LLM configuration and context model. Keep your API key current, monitor context window usage, and inspect agent diffs before acceptance. The editor’s strength is its familiarity to VS Code users while surfacing AI assistance at the exact moments it’s most useful, without requiring you to context-switch to a separate tool or web interface.

This page was rewritten on 11 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.