Windsurf Setup

Clawkeeper integrates with Windsurf Cascade's hook system. Shell commands and file writes are intercepted before execution, giving you stronger write-path enforcement than other IDE integrations.

What gets monitored

Windsurf provides pre-execution hooks for file writes, which is not available in Cursor or Copilot. This makes Windsurf the strongest option when file write blocking is required.

Installation

Get your API key from Settings → API Keys in the dashboard, then run the installer:

bash install-hooks.sh --ide windsurf --project /path/to/project

The installer writes .windsurf/hooks.json to the project root.

What gets generated

{
  "hooks": {
    "pre_tool_call": [
      {
        "tools": ["run_command", "write_file", "str_replace", "user_message"],
        "handler": {
          "type": "http",
          "url": "https://clawkeeper.dev/api/v1/evaluate?tool=windsurf",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    ],
    "post_tool_call": [
      {
        "tools": ["read_file"],
        "handler": {
          "type": "http",
          "url": "https://clawkeeper.dev/api/v1/audit?tool=windsurf",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    ]
  }
}

Commit .windsurf/hooks.json to your repo. Windsurf loads the config automatically when the project is opened.

How blocking works in Windsurf

Windsurf uses exit codes to determine the hook verdict:

• Exit 0 — tool call is allowed to proceed
• Exit 1 (non-zero) — tool call is blocked; Windsurf displays the hook's stderr output to the user

Clawkeeper returns a non-2xx HTTP status code with a JSON body describing the block reason. Windsurf surfaces this as an inline message in the Cascade panel.

Note: Windsurf does not have a warn-only feedback mechanism. Events logged as "warn" by Clawkeeper policies are allowed to proceed — the warning appears in the Clawkeeper audit trail but Windsurf does not distinguish between warn and pass verdicts.

Known limitations

No MCP hooks. Windsurf does not expose hooks for MCP tool calls. MCP activity is not visible in Clawkeeper for Windsurf sessions.

No warn feedback in UI. Warn-only policies work for audit purposes, but Windsurf only shows user-visible feedback when a tool is blocked (non-zero exit). Users do not see any indication that a tool call was warned.

str_replace blocking. When Windsurf's str_replace tool is blocked mid-edit, the file may be left in a partially modified state. Test file write policies in a development environment before enforcing them on production repos.

Workstations auto-register on first event. Clawkeeper doesn't expose a separate session check-in endpoint for Windsurf — the first pre_tool_call or post_tool_call hook automatically creates the workstation record. No additional configuration required.

Enforcement status