Windsurf

Windsurf's Cascade agent gets workspace hooks for prompts, file writes, terminal commands and responses, plus an always-on rule. Cascade has no project-level MCP file, so comity init prints the MCP entry for you to add to your user config.

Set up

cd your-repo
comity init --tools windsurf
git add .windsurf/hooks.json .windsurf/rules/comity.md
git commit -m "Set up Comity for Windsurf"

Then:

1. Open the repo in Windsurf outside Restricted Mode. Cascade doesn't load or run hooks in Restricted Mode.
2. Add the MCP server to your user-level config (see MCP).

If the repo already defines hooks in .devin/hooks.json, init merges into that file instead. Windsurf ignores the legacy .windsurf/hooks.json whenever .devin/hooks.json defines hooks.

What init writes

.windsurf/hooks.json

Each handler has a POSIX command (run via bash -c) and a powershell variant (run via powershell -Command on Windows). Both exit quietly when the CLI isn't installed. Shown for one event:

{
  "hooks": {
    "pre_write_code": [
      {
        "command": "command -v comity >/dev/null 2>&1 || exit 0; exec comity hook --tool windsurf --event pre_write_code",
        "powershell": "$c = Get-Command comity -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1; if (-not $c) { exit 0 }; & $c.Source hook --tool windsurf --event pre_write_code; exit $LASTEXITCODE"
      }
    ]
  }
}

Your own hooks in the file are kept. Cascade has no session start/end events; Comity uses Cascade's trajectory_id as the session.

.windsurf/rules/comity.md

A trigger: always_on rule with Comity's coordination instructions. Because hooks can't add context in Cascade, this rule and the MCP server are how the agent learns about Comity.

MCP

Cascade reads MCP servers only from the user-level mcp_config.json: %APPDATA%\devin\mcp_config.json on Windows, ~/.config/devin/mcp_config.json on macOS/Linux, or ~/.codeium/windsurf/mcp_config.json in older Windsurf builds. Open it from the Cascade panel (⋯ → MCPs → Open MCP config file) and add:

{
  "mcpServers": {
    "comity": { "command": "node", "args": ["-e", "<launcher>", "mcp"] }
  }
}

Copy the exact line comity init --tools windsurf prints: it fills in <launcher>, a short node -e script that finds comity on any OS, so the same entry works on Windows, macOS and Linux. Node must be on PATH.

Cascade starts comity mcp, a local stdio bridge to the Comity server that uses the login stored by comity login. No token goes into any file, and nothing has to be exported.

What your agent sees

• Before a file write or terminal command: a block stops the action (exit code 2). Cascade shows the agent Comity's reason.
• Everything else: nothing from the hooks. Cascade hooks can't inject context, so the agent sees briefings, warnings and conflicts only when it calls the Comity MCP tools.

Verify

comity doctor

Expect windsurf hooks all 6 events installed (not in Restricted Mode) and windsurf mcp configured in …/mcp_config.json. Turn on "show_output": true on a hook entry to see its output in Cascade while debugging.

Limits

• No context injection: Cascade hooks communicate only through exit codes and stderr.
• These hooks apply to the Cascade agent. The Devin Local agent in Devin Desktop has its own hooks and MCP config and isn't covered.
• Workspace hooks have no timeout setting. A slow Comity server delays Cascade's actions until comity hook gives up.