Windsurf Setup

Agent Keeper 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:

export AGENTKEEPER_API_URL="https://YOUR_AGENTKEEPER_URL"
export AGENTKEEPER_API_KEY="ak_live_..."
bash <(curl -fsSL "$AGENTKEEPER_API_URL/install-hooks.sh") --ide windsurf

The installer stores the API key in ~/.agentkeeper/config, installs ~/.codeium/windsurf/hooks/agentkeeper-hook.sh, and merges Agent Keeper commands into ~/.codeium/windsurf/hooks.json.

What gets generated

{
  "hooks": {
    "pre_run_command": [
      {"command": "bash ~/.codeium/windsurf/hooks/agentkeeper-hook.sh", "show_output": true}
    ],
    "pre_write_code": [
      {"command": "bash ~/.codeium/windsurf/hooks/agentkeeper-hook.sh", "show_output": true}
    ],
    "pre_read_code": [
      {"command": "bash ~/.codeium/windsurf/hooks/agentkeeper-hook.sh", "show_output": true}
    ],
    "pre_mcp_tool_use": [
      {"command": "bash ~/.codeium/windsurf/hooks/agentkeeper-hook.sh", "show_output": true}
    ]
  }
}

For team rollout, deploy the same hook file and Windsurf config through your device management tool, or package a repo-level config after validating it in a test workspace.

How blocking works in Windsurf

Windsurf uses exit codes to determine the hook verdict:

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

Agent Keeper returns a structured decision to the local hook. The hook exits 2 for block verdicts and writes the policy reason to stderr so Windsurf can surface it in Cascade.

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

Known limitations

MCP hook support depends on Windsurf release. Agent Keeper installs pre_mcp_tool_use when Windsurf exposes it. Older Windsurf releases may omit MCP events.

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. Agent Keeper does not expose a separate session check-in endpoint for Windsurf. The first hook event automatically creates the workstation record.

Enforcement status