Windsurf + Greenlight Setup Guide

Greenlight works with Windsurf's Cascade hooks system. All four hook types are supported: command execution, file writes, file reads, and MCP tool use. Permission requests arrive on your phone as push notifications, and you can build always-allow rules so Cascade interrupts you less over time.

What You'll Need

Check with:

jq --version
curl --version

If either is missing: brew install jq on macOS, or apt install jq on Ubuntu/Debian.

Step 1: Get Your Device ID

Open Greenlight on your phone and go to the About tab. Tap your Device ID to copy it to the clipboard.

Step 2: Install the Hook Script

curl -o ~/greenlight-windsurf.sh https://getgreenlight.github.io/greenlight-windsurf.sh
chmod +x ~/greenlight-windsurf.sh

Step 3: Configure Windsurf

Create or edit the hooks configuration file at ~/.codeium/windsurf/hooks.json:

{
  "hooks": {
    "pre_run_command": [{
      "command": "~/greenlight-windsurf.sh --device-id YOUR_DEVICE_ID",
      "show_output": true
    }],
    "pre_write_code": [{
      "command": "~/greenlight-windsurf.sh --device-id YOUR_DEVICE_ID",
      "show_output": true
    }],
    "pre_read_code": [{
      "command": "~/greenlight-windsurf.sh --device-id YOUR_DEVICE_ID",
      "show_output": true
    }],
    "pre_mcp_tool_use": [{
      "command": "~/greenlight-windsurf.sh --device-id YOUR_DEVICE_ID",
      "show_output": true
    }]
  }
}

Replace YOUR_DEVICE_ID with the ID from the app.

What each hook covers

Hook Triggers when Cascade wants to…
pre_run_command Execute a shell command
pre_write_code Write or edit a file
pre_read_code Read a file
pre_mcp_tool_use Call an MCP tool

You can omit any hook type you don't want Greenlight to gate. For example, if you're comfortable with Cascade reading files freely, leave out pre_read_code.

Project detection

The Windsurf hook script detects the project name automatically from the git repository root or working directory. You don't need a --project flag (though you can override with one if you prefer).

Per-project configuration

You can also place a .windsurf/hooks.json file in a project directory to configure hooks for that project only.

Step 4: Test It

Open a project in Windsurf, start a Cascade session, and ask it to run a command or edit a file. You should see the request appear in Greenlight with a windsurf badge.

How the Rules Work

The rules system works the same way across all agents. When you tap "Always Allow," a pattern is generated and stored for that project. Future matching requests are auto-approved silently.

Commands

Patterns are subcommand-aware. npm install express creates the pattern Bash(npm install **), which matches any npm install but not npm publish. Destructive commands like rm use exact matching for safety.

File operations

File reads and writes match on the directory. Granting a write to src/components/Header.tsx creates a rule for Edit(src/components/**), covering future edits in that directory.

MCP tools

MCP tool calls show the server name, tool name, and arguments. Always-allow rules for MCP tools use the tool name as the pattern.

Using Greenlight with Multiple Agents

If you use both Windsurf and Claude Code, Greenlight works as a single approval layer across both. Rules are scoped per-project, not per-agent — a rule you create from a Claude Code request will also auto-approve the same action from Windsurf, and vice versa. Each request shows an agent badge so you know which tool sent it.

Troubleshooting

See the troubleshooting section of the support page for common issues.

Questions?

Email greenlight@dnmfarrell.com.