windsurf-cascade

# Windsurf Cascade Agent Skill

This skill provides a comprehensive guide and set of workflows for utilizing the Windsurf IDE and its Cascade AI agent, including all features from Wave 13 (January 2026).

## Installation

### Download

Download Windsurf Editor from [windsurf.com](https://windsurf.com) for your platform:
- **macOS**: `.dmg` installer (Intel and Apple Silicon)
- **Windows**: `.exe` installer
- **Linux**: `.deb` package (Debian/Ubuntu) or `.tar.gz` tarball

### Post-Installation Setup

**Add to PATH (optional but recommended):**

During onboarding, you can optionally install `windsurf` in PATH to launch from the command line:

```bash
# macOS - create symlink manually if needed
sudo ln -sF /Applications/Windsurf.app/Contents/Resources/app/bin/windsurf /usr/local/bin/windsurf

# Open a project from terminal
windsurf /path/to/project
```

**Import existing configuration:**

Windsurf supports importing settings, extensions, and keybindings from VS Code or Cursor during onboarding. You can also do this later via the Command Palette:

```
Cmd+Shift+P → "Import VS Code Settings"
Cmd+Shift+P → "Import Cursor Settings"
```

### WSL Setup (Windows)

Windsurf supports WSL (Beta). Connect to your WSL instance:
1. Click the bottom-left remote connection button
2. Select "Connect to WSL" or use Command Palette: `Remote-WSL: Connect to WSL`

For CLI access from WSL terminal, create a helper script:

```bash
#!/bin/bash
CURRENT_PATH=$(readlink -f "$1")
windsurf --folder-uri "vscode-remote://wsl+Ubuntu$CURRENT_PATH"
```

### Authentication

Sign up or log in to your Windsurf (formerly Codeium) account during onboarding or via the profile menu.

## Cascade — The AI Agent

Cascade is Windsurf's agentic AI assistant. It understands your entire codebase, tracks your real-time actions (edits, terminal, clipboard), and can autonomously create files, edit code across multiple files, run terminal commands, and maintain project memory.

### Cascade Modes

Cascade comes in two primary modes:

- **Write Mode** (`Cmd+L` / `Ctrl+L`): Full write access — creates files, edits code, runs terminal commands, and makes modifications to your codebase.
- **Chat Mode** (`Cmd+Shift+L` / `Ctrl+Shift+L` to toggle): Read-only — answers questions about your codebase and general coding principles without making changes.

### Model Selection

Switch between models from the dropdown below the Cascade input box. Available models include:

- **SWE-1.5** (Windsurf's own near-frontier model, free for all users)
- **Claude Opus 4.6**, Claude Sonnet 4.5
- **GPT-5.2**, GPT-5.2-Codex, GPT-5.1, GPT-5.1-Codex
- **Gemini 3 Flash**, Gemini 3 Pro
- **Falcon Alpha** (stealth model, speed-optimized)
- **BYOK** (Bring Your Own Key) for custom models

Each prompt consumes credits depending on the model selected.

### Tool Calling

Cascade has a variety of built-in tools:

- **Search**: Semantic code search across your repository
- **Analyze**: Deep analysis of code structure and relationships
- **Web Search**: Search the web for documentation and references
- **MCP**: Call external tools via Model Context Protocol
- **Terminal**: Execute shell commands directly

Cascade can make up to **25 tool calls per prompt**. If the trajectory stops, type `continue` and Cascade will resume.

### Context Selection with @ Mentions

Reference specific files, functions, or context in your prompts:

```
@filename.ts
@src/components/
@function:calculateTotal
```

You can also:
- Drag and drop files from the File Explorer into Cascade
- Send problems from the Problems panel to Cascade
- Highlight errors and click "Explain and Fix"
- @-mention previous conversations for cross-session context

### Voice Input

Use voice input to interact with Cascade via speech-to-text transcription.

### Checkpoints and Reverts

Cascade creates named checkpoints. You can revert changes by hovering over a prompt and clicking the revert arrow, or via the table of contents. **Reverts are currently irreversible.**

## Keyboard Shortcuts

| Action | macOS | Windows/Linux |
|---|---|---|
| Open Cascade (Write) | `Cmd+L` | `Ctrl+L` |
| Toggle Write/Chat | `Cmd+Shift+L` | `Ctrl+Shift+L` |
| Command Palette | `Cmd+Shift+P` | `Ctrl+Shift+P` |
| Inline AI (terminal) | `Cmd+I` | `Ctrl+I` |
| Accept focused diff hunk | `Option+Enter` | `Alt+Enter` |
| Reject focused diff hunk | `Option+Shift+Backspace` | `Alt+Shift+Backspace` |
| Fast Context (first msg) | `Cmd+Enter` | `Ctrl+Enter` |

## Skills

Skills let you bundle instructions, templates, checklists, and supporting files into folders that Cascade can invoke for complex, multi-step tasks.

### Creating a Skill

1. Click the Customizations icon in Cascade's top-right slider menu
2. Navigate to the Skills panel
3. Click `+ Workspace` (project-specific) or `+ Global`
4. Name the skill (lowercase letters, numbers, hyphens only)

### Skill Structure

Each skill is a folder with a `SKILL.md` file and optional supporting files:

```
.windsurf/skills/deploy-to-production/
├── SKILL.md
├── deployment-checklist.md
├── rollback-procedure.md
└── config-template.yaml
```

### SKILL.md Format

```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 pending migrations
3. Verify environment variables
...
```

The `name` field is used for display and @-mentions. The `description` helps Cascade decide when to automatically invoke the skill.

### Invoking Skills

- **Automatic**: Cascade uses progressive disclosure to invoke skills when they're relevant to your task
- **Manual**: @-mention the skill name in your prompt

For the full Skills specification, visit [agentskills.io](https://agentskills.io).

## Workflows

Workflows define a series of steps to guide Cascade through repetitive tasks. They are saved as markdown files and invoked via slash commands.

### Creating a Workflow

1. Click Customizations icon → Workflows panel → `+ Workflow`
2. Or ask Cascade to generate a Workflow for you

### Workflow Storage

Workflows are saved in `.windsurf/workflows/` directories. Windsurf discovers them from:
- Current workspace and sub-directories
- Parent directories up to the git root (for git repos)
- Multiple workspace support with deduplication

Workflow files are limited to **12,000 characters** each.

### Invoking Workflows

```
/workflow-name
```

Workflows can call other workflows:

```markdown
## Steps
1. Call /lint-and-format
2. Call /run-tests
3. Deploy to staging
```

### Example Workflow — PR Review

```markdown
---
name: pr-review
description: Review PR comments and address them
---

## Steps
1. Check out the PR branch: `gh pr checkout [id]`
2. Get comments on PR:
   ```bash
   gh api --paginate repos/[owner]/[repo]/pulls/[id]/comments | jq '.[] | {user: .user.login, body, path, line}'
   ```
3. For EACH comment, address the feedback and commit the fix
4. Push changes and reply to each comment
```

## Memories & Rules

Memories persist context across Cascade conversations. Rules guide Cascade behavior.

### Memories

- **Auto-generated**: Cascade creates memories when it encounters useful context. Does NOT consume credits.
- **User-created**: Type `create memory ...` in Cascade to manually save context.
- Auto-generated memories are workspace-specific.

**Managing Memories:**
- Windsurf Settings → Settings tab → Manage next to "Cascade-Generated Memories"
- Or: three dots in Cascade → Manage Memories
- Toggle auto-generation: Settings → "Auto-Generate Memories"

### Rules

Rules are manually defined instructions for Cascade.

**Rule Levels:**
- `global_rules.md` — applies across all workspaces
- `.windsurf/rules/` — workspace-level directory with rules tied to globs or descriptions
- System-level rules (Enterprise) — deployed via MDM policies

**Activation Modes:**
- **Always**: Rule is always active
- **Glob**: Applied to files matching a pattern (e.g., `*.js`, `src/**/*.ts`)
- **Manual / Description-based**: Activated by natural language match

**Rules Best Practices:**
- Keep rules simple, concise, and specific
- Use bullet points and markdown formatting
- Avoid generic rules like "write good code"
- Use XML tags to group similar rules

**Example Rule:**

```markdown
# Coding Guidelines
- My project's programming language is Python
- Use early returns when possible
- Always add documentation when creating new functions and classes
- Use pytest for testing
- Follow PEP 8 style guide
```

## Terminal Integration

### Inline AI Terminal

Press `Cmd+I` / `Ctrl+I` in the terminal to access an inline chat box that generates CLI commands from natural language.

### Cascade Terminal Execution

Cascade can run terminal commands directly. Configure auto-execution levels in Windsurf Settings:

1. **Manual**: Always ask for permission (default)
2. **Semi-auto**: Auto-run safe commands
3. **Turbo Mode**: Auto-execute all commands without confirmation
4. **Custom**: Use Allow/Deny lists for specific commands

### Dedicated Terminal (Wave 13)

Windsurf uses a dedicated zsh shell for Cascade command execution, providing improved reliability. It uses your `.zshrc` environment variables and is fully interactive.

### ⚠️ Using with AI Agents / Automation

When running Windsurf from automated environments (AI agents, scripts, orchestrators), the IDE requires a GUI context. For headless automation scenarios, consider:

1. **Using Windsurf's Workflows**: Define multi-step tasks as Workflows that Cascade executes
2. **MCP Integration**: Connect external automation tools via MCP servers
3. **Cascade Hooks**: Execute custom shell commands at key points in Cascade's workflow

## MCP Integration

Windsurf supports Model Context Protocol (MCP) for connecting external tools and services.

### Configuration

Configure MCP servers in `mcp_config.json`:

```json
{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["github-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}
```

Access via: Windsurf Settings → Cascade → Manage MCPs → View raw config

### MCP Features

- **MCP Marketplace**: Browse curated servers in Windsurf Settings for one-click setup
- **@ Mentions**: Trigger MCP tools by @-mentioning in Cascade
- **Enable/Disable**: Toggle MCP servers from the Cascade header
- **Transports**: Supports stdio, Streamable HTTP, and SSE
- **Enterprise**: Team admins can whitelist/blacklist MCP servers

Each MCP tool call costs one prompt credit.

## Cascade Hooks

Execute custom shell commands at key points during Cascade's workflow:

- **On model response**: For logging, auditing, security controls
- **Pre/Post hooks**: For validation and governance (Enterprise)

## Simultaneous Cascades

Run multiple Cascade sessions in parallel:

- Open side-by-side Cascade panes
- Use Git worktrees to work on different branches without conflicts
- Start work in a new Cascade while another is executing

## Fast Context

Press `Cmd+Enter` / `Ctrl+Enter` on the first message to enable Fast Context. Uses SWE-grep models for up to 20x faster code retrieval from large codebases.

## Ignoring Files

Add files to `.codeiumignore` at the root of your workspace (same syntax as `.gitignore`). For global ignore rules across all repositories, place `.codeiumignore` in `~/.codeium/`.

## Workflows (Common Use Cases)

### Code Review

```
Review the changes in the current branch against main.
Focus on security and performance.
```

### Refactoring

```
Refactor src/utils.ts to reduce complexity and improve type safety.
```

### Debugging

```
Analyze the following error log and suggest a fix: [paste error]
```

Or: Highlight error → "Explain and Fix"

### Git Integration

```
Generate a commit message for the staged changes adhering to conventional commits.
```

### Deployment

Create a Workflow in `.windsurf/workflows/deploy.md`:

```markdown
---
name: deploy
description: Deploy to production with safety checks
---

## Steps
1. Run all tests: `npm test`
2. Build the project: `npm run build`
3. Run linter: `npm run lint`
4. If all pass, deploy: `npm run deploy:production`
5. Verify deployment health checks
```

Invoke with `/deploy` in Cascade.

### Live Preview

Windsurf has built-in live preview for web apps. Ask Cascade to start a dev server and preview will appear inside the editor. Click any element to let Cascade reshape it.

### App Deploy

Deploy your app with one click via Cascade tool calls (beta Netlify deployment support).

## Pricing

| Plan | Price | Credits/month | Best For |
|---|---|---|---|
| Free | $0 | 25 | Students, hobbyists |
| Pro | $15/mo | 500 | Individual developers |
| Teams | $30/user/mo | Custom | Development teams |
| Enterprise | $60/user/mo | Custom | Large organizations |

## Key Differences from Cursor

| Feature | Windsurf | Cursor |
|---|---|---|
| AI Agent | Cascade (agentic, flow-aware) | Cursor Agent (CLI-based) |
| Rules | `.windsurf/rules/` + `global_rules.md` | `.cursor/rules` + `CLAUDE.md` |
| Workflows | `.windsurf/workflows/` (slash commands) | N/A (manual) |
| Memories | Auto-generated + user-created | Codebase indexing + Project Rules |
| Skills | `.windsurf/skills/` (bundled folders) | N/A |
| Terminal | Dedicated zsh shell + Turbo Mode | Standard terminal |
| Live Preview | Built-in | Extension-based |
| MCP | Native with marketplace | Native |