# Windsurf

Agentic AI code editor built around the Cascade agent, created by Codeium and now maintained by Cognition as Devin Desktop.

Schema: 1.0 · Data: ee5de863c30bdbe4fe7dd3e07c7e22ea9bf4ab2248dbc7c35cdbf60bc28be1db

## Configuration

### MCP

Status: supported

Configure MCP servers for Cascade in mcp_config.json under the mcpServers key, or install from the built-in MCP Marketplace. Supports stdio, Streamable HTTP, and SSE with OAuth for each transport.

- global: `~/.codeium/windsurf/mcp_config.json` (json) — key: mcpServers — Also editable via the MCP Marketplace / MCP Servers settings UI.
- `command`: string — Command to start a local (stdio) server, e.g. npx, docker, node.
- `args`: string[] — Arguments passed to the command.
- `env`: record<string, string> — Environment variables for the server. Supports ${env:...} and ${file:...} interpolation.
- `serverUrl`: string — Endpoint URL for a remote (HTTP/SSE) server. url is also accepted.
- `headers`: record<string, string> — HTTP headers for a remote server (e.g. API keys, Authorization). Supports interpolation.
- `disabledTools`: string[] — Tools to disable for this server (excluded from enterprise whitelist matching).
- transports: stdio, http, sse
- auth: oauth, headers
- Tools: supported
- Prompts: supported
- Resources: supported
- Remote servers use a serverUrl (or url) field instead of command/args.
- Cascade has a limit of 100 total MCP tools enabled at any given time; individual tools can be toggled per server.
- command, args, env, serverUrl, url, and headers support ${env:VAR_NAME} and ${file:/path/to/file} interpolation to avoid hardcoding secrets.
- One-click installs via windsurf://windsurf-mcp-registry deeplinks; teams can whitelist servers or point at custom MCP registries (enterprise).

Local stdio server
```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

```


Remote HTTP server with header interpolation
```json
{
  "mcpServers": {
    "remote-http-mcp": {
      "serverUrl": "<your-server-url>/mcp",
      "headers": {
        "API_KEY": "Bearer ${env:AUTH_TOKEN}"
      }
    }
  }
}

```

Source: https://docs.devin.ai/desktop/cascade/mcp
Checked: 2026-07-12

### Skills

Status: supported

Folder-based SKILL.md skills (Agent Skills standard) that bundle instructions with supporting files. Cascade sees only name and description until it invokes the skill (progressive disclosure).

- project: `.windsurf/skills/<name>/SKILL.md` (markdown) — Workspace skills, committed with the repo.
- global: `~/.codeium/windsurf/skills/<name>/SKILL.md` (markdown) — Global skills, available in all workspaces. Not committed.
- enterprise: `/etc/windsurf/skills/<name>/SKILL.md` (markdown) — System skills deployed by IT (Linux path; macOS: /Library/Application Support/Windsurf/skills/, Windows: C:\ProgramData\Windsurf\skills\). Read-only for end users.
- `name`: string (required) — Unique skill identifier (lowercase letters, numbers, hyphens). Displayed in the UI and used for @-mentions.
- `description`: string (required) — Brief explanation shown to the model so Cascade can decide when to invoke the skill.
- invocation: automatic, @skill-name
- Supporting files (scripts, templates, checklists) placed next to SKILL.md become available when the skill is invoked.
- For cross-agent compatibility, skills are also discovered in .agents/skills/ and ~/.agents/skills/; with Claude Code config reading enabled, .claude/skills/ and ~/.claude/skills/ are scanned too.
- Skills can also be created from the Cascade Customizations UI (+ Workspace / + Global).

Skill with frontmatter
```markdown
---
name: deploy-to-production
description: Guides the deployment process to production with safety checks
---

## Pre-deployment Checklist
1. Run all tests
2. Check for uncommitted changes
3. Verify environment variables

## Deployment Steps
Follow these steps to deploy safely...

```

Source: https://docs.devin.ai/desktop/cascade/skills
Checked: 2026-07-12

### Rules

Status: supported

User-defined rules at global, workspace, and system level, with per-rule activation modes (always_on, glob, model_decision, manual). AGENTS.md files are fed into the same rules engine with location-based scoping.

- project: `.windsurf/rules/*.md` (markdown) — One file per rule with frontmatter activation mode. .devin/rules/*.md is preferred in newer builds.
- project: `.windsurfrules` (markdown) — Legacy single-file workspace rules at the repo root; still read.
- project: `AGENTS.md` (markdown) — Root and any subdirectory. Root = always-on, subdirectory = auto-glob for that directory. No frontmatter.
- global: `~/.codeium/windsurf/memories/global_rules.md` (markdown) — Single always-on file applied across all workspaces. Max 6,000 characters.
- enterprise: `/etc/windsurf/rules/*.md` (markdown) — System rules deployed by IT (Linux path; macOS: /Library/Application Support/Windsurf/rules/, Windows: C:\ProgramData\Windsurf\rules\). Merged with user rules, read-only.
- `trigger`: string — Activation mode declared in the rule's frontmatter. Values: always_on, model_decision, glob, manual
- `description`: string — Shown in the system prompt for model_decision rules; Cascade reads the full rule when it decides the description is relevant.
- `globs`: string — Glob pattern(s) for glob-triggered rules (e.g. **/*.test.ts); applied when Cascade reads or edits matching files.
- invocation: @rule-name
- Newer builds prefer .devin/rules/*.md over .windsurf/rules/*.md; both are read (.devin takes precedence).
- Rules are discovered in the workspace, its subdirectories, and parent directories up to the git root.
- Workspace rule files are limited to 12,000 characters each; the global rules file to 6,000 characters.
- Root-level AGENTS.md is always-on; AGENTS.md in a subdirectory becomes a glob rule for <directory>/**. agents.md (lowercase) also works.
- Cascade also auto-generates Memories (stored locally in ~/.codeium/windsurf/memories/) that are retrieved when relevant; these are separate from user-defined rules.

Glob-scoped workspace rule
```markdown
---
trigger: glob
globs: **/*.test.ts
---

All test files must use `describe`/`it` blocks and mock external API calls.

```

Source: https://docs.devin.ai/desktop/cascade/memories
Checked: 2026-07-12

### Hooks

Status: supported

Cascade Hooks run shell commands at key points in the agent workflow, configured in hooks.json at system, user, and workspace level (merged, executed system -> user -> workspace). Hooks receive event JSON on stdin; pre-hooks can block the action by exiting with code 2.

- project: `.windsurf/hooks.json` (json) — key: hooks — Workspace hooks, version-controlled with the repo.
- global: `~/.codeium/windsurf/hooks.json` (json) — key: hooks — User-level hooks (JetBrains plugin reads ~/.codeium/hooks.json).
- enterprise: `/etc/windsurf/hooks.json` (json) — key: hooks — System hooks deployed by IT (Linux path; macOS: /Library/Application Support/Windsurf/hooks.json, Windows: C:\ProgramData\Windsurf\hooks.json).
- `command`: string — Shell command to run on macOS/Linux (via bash -c). At least one of command or powershell is required.
- `powershell`: string — Command to run on Windows (via powershell -Command). Falls back to command when omitted.
- `show_output`: boolean — Whether to display the hook's stdout/stderr in the Cascade UI.
- `working_directory`: string — Directory to run the command from. Defaults to the workspace root; ~ expansion is not supported.
- events: pre_read_code, post_read_code, pre_write_code, post_write_code, pre_run_command, post_run_command, pre_mcp_tool_use, post_mcp_tool_use, pre_user_prompt, post_cascade_response, post_cascade_response_with_transcript, post_setup_worktree
- Exit code 0 = proceed; exit code 2 = blocking error (pre-hooks only); other codes = non-blocking error.
- Only pre_user_prompt, pre_read_code, pre_write_code, pre_run_command, and pre_mcp_tool_use can block actions.
- Every hook receives common JSON fields: agent_action_name, trajectory_id, execution_id, timestamp, model_name, and event-specific tool_info.
- post_cascade_response_with_transcript writes a full JSONL conversation transcript to ~/.windsurf/transcripts/{trajectory_id}.jsonl.
- Enterprise teams can also distribute hooks via the cloud dashboard (Team Settings > Cascade Hooks); cloud hooks load before system, user, and workspace hooks.

Block dangerous commands and format after edits
```json
{
  "hooks": {
    "pre_run_command": [
      {
        "command": "python3 /Users/yourname/hooks/block_dangerous_commands.py",
        "show_output": true
      }
    ],
    "post_write_code": [
      {
        "command": "bash /Users/yourname/hooks/format_code.sh",
        "show_output": false
      }
    ]
  }
}

```

Source: https://docs.devin.ai/desktop/cascade/hooks
Checked: 2026-07-12

### Commands

Status: supported

Workflows are markdown prompt templates invoked manually with /workflow-name slash commands. Cascade processes the steps sequentially; workflows can call other workflows.

- project: `.windsurf/workflows/*.md` (markdown) — Workspace workflows, committed with the repo.
- global: `~/.codeium/windsurf/global_workflows/*.md` (markdown) — Global workflows available in every workspace. Not committed.
- enterprise: `/etc/windsurf/workflows/*.md` (markdown) — System workflows deployed by IT (Linux path; macOS: /Library/Application Support/Windsurf/workflows/, Windows: C:\ProgramData\Windsurf\workflows\). Highest precedence, read-only.
- invocation: /workflow-name
- Manual-only: Cascade never invokes a workflow automatically (use a Skill for model-invoked procedures).
- Workflow files are limited to 12,000 characters each.
- Workflows are discovered in the workspace, its subdirectories, and parent directories up to the git root.
- Precedence when names collide: system > workspace > global > built-in (e.g. /plan).
- Workflows contain a title, description, and a series of steps; a workflow can include instructions like 'Call /other-workflow'.

Workflow to address PR comments
```markdown
1. Check out the PR branch: `gh pr checkout [id]`
2. Get comments on the PR via `gh api`
3. For EACH comment: analyze the file and line range, make the change
   if it is clear, otherwise ask for clarification.
4. After all comments are processed, summarize what you did and which
   comments need the USER's attention.

```

Source: https://docs.devin.ai/desktop/cascade/workflows
Checked: 2026-07-12

### Settings

Status: partial

Agent-relevant settings live in the in-app settings UI (Cascade gitignore access, diff zones, terminal allow/deny lists, marketplace URL); there is no documented user-editable settings file for agent behavior. Enterprises can enforce settings centrally via OS-level policies.

- enterprise: `/etc/windsurf/policies/policy.json` (json) — Linux JSON policy file deployed by IT. Windows uses registry-based group policy, macOS uses configuration profiles.
- `AllowedExtensions`: string (JSON) — Allowlist of permitted extension publishers, e.g. {"windsurf": true, "github": true}.
- `UpdateMode`: string — Controls how the editor updates (e.g. manual).
- `EnableTelemetry`: boolean — Enable or disable telemetry.
- User settings are managed via the settings UI (top-right dropdown or Command Palette > Open User Settings) rather than a documented config file.
- Enterprise policy values override settings configured at any level (default, user, workspace).
- Windows policies are read from the registry at Software\Policies\Windsurf\{ProductName}; macOS uses .mobileconfig configuration profiles.
- Documented policies include AllowedExtensions (JSON allowlist of extension publishers), UpdateMode, EnableTelemetry, and EnableFeedback.

Linux policy file
```json
{
  "AllowedExtensions": "{\"publisher1\": true, \"publisher2\": true}",
  "UpdateMode": "manual"
}

```

Source: https://docs.devin.ai/desktop/enterprise-policies
Checked: 2026-07-12

## Search, browser & identification

Not researched. Unknown does not mean unsupported.