Windsurf / Devin Desktop Setup

AgentKeeper integrates with both hook systems shipped by the current product: Cascade hooks for the Editor experience, and Devin lifecycle hooks for Devin CLI and the Devin Local agent inside Devin Desktop.

Windsurf's Cascade hooks are pre-execution for the installed file, command, MCP, and prompt events. Post hooks are useful for audit, but Windsurf documents that only pre-hooks can block.

Use Policy outcomes for the shared Monitor, Warn, and Block model; this page lists what the Windsurf surface can actually support.

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 > Access > API keys in the dashboard, then run the installer:

export AGENTKEEPER_API_URL="https://www.agentkeeper.dev"
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 one dual-protocol hook at ~/.codeium/windsurf/hooks/agentkeeper-hook.sh, merges Cascade commands into ~/.codeium/windsurf/hooks.json, and adds PreToolUse plus UserPromptSubmit to ~/.config/devin/config.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}
    ],
    "pre_user_prompt": [
      {"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

AgentKeeper 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: Cascade does not have a warn-only feedback mechanism, so WARN events proceed and remain visible in AgentKeeper Activity. Devin CLI/Local supports additionalContext; AgentKeeper injects prompt WARN context without blocking.

Known limitations

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

Prompt hooks require current Windsurf. The AgentKeeper installer registers pre_user_prompt, which Windsurf documents as a blocking pre-hook. Validate it on the installed Cascade release before using prompt blocking as a critical control.

Cascade WARN feedback. Warn-only policies work for audit purposes, but legacy Cascade only shows user-visible feedback when a tool is blocked. Devin CLI/Local can receive warning context on UserPromptSubmit.

File-edit validation. Test file write policies in a development workspace before enforcing them broadly. Windsurf should block pre-execution hook denials before the edit runs; if a future Windsurf release changes hook timing, verify with a harmless blocked-path test before rollout.

Workstations auto-register on first event. AgentKeeper does not expose a separate session check-in endpoint for Windsurf. The first hook event automatically creates the workstation record.

Outcome support status

For cross-IDE claims, see IDE runtime parity.