Windsurf

Windsurf connector wires Cascade hooks across pre_user_prompt, pre_read_code, pre_write_code, pre_run_command, and pre_mcp_tool_use.

The Windsurf connector wires DefenseClaw into Codeium's Cascade hooks so every prompt, code read, code write, command run, and MCP tool call is scored before it lands.

Setup

defenseclaw setup windsurf

Pins claw.mode=windsurf, wires hooks against ~/.codeium/windsurf/hooks.json. DefenseClaw discovers existing MCP / rules but never auto-creates workspace configuration. There is no proxy-enforcement path for Windsurf — blocking happens hook-side via Cascade's pre_user_prompt, pre_read_code, pre_write_code, pre_run_command, and pre_mcp_tool_use events. Windsurf has no native ask surface, so HITL approvals downgrade to confirm verdicts in the DefenseClaw TUI.

What `setup windsurf` actually does

The wrapper accepts exactly three flags. The underlying guardrail config falls back to the values DefenseClaw ships with — schema-defined in internal/config/config.go and documented on the Defaults page.

Flag	Default	What it does
`--yes / -y`	off	Skip the confirmation prompt (alias: `--non-interactive`, `--accept-defaults`).
`--restart / --no-restart`	`--restart`	Bounce `defenseclaw-gateway` after applying changes so the new hooks wire in.
`--with-local-stack / --no-local-stack`	`--no-local-stack`	Also bring up the bundled Prom/Loki/Tempo/Grafana stack via `setup local-observability up`.

Pinned by the alias regardless of flags: claw.mode=windsurf, guardrail.connector=windsurf, guardrail.mode=observe, guardrail.scanner_mode=local, guardrail.judge.enabled=false, guardrail.detection_strategy=regex_only. To tune any of those after install, use defenseclaw setup guardrail --connector windsurf — see the variations below.

Common variations — pick the recipe that fits your phase

defenseclaw setup windsurf

Confirms once, wires the hooks against ~/.codeium/windsurf/hooks.json, restarts the gateway. Findings flow to ~/.defenseclaw/gateway.jsonl and the TUI; no traffic is intercepted, no requests are blocked. Pass --yes to skip the confirmation in CI.

defenseclaw setup windsurf --yes --with-local-stack

Same as standard but also runs setup local-observability up so Prom/Loki/Tempo/Grafana come up locally for ad-hoc dashboards. See Local observability.

export DEFENSECLAW_LLM_KEY=<your-key>

defenseclaw setup windsurf                                # base alias first
defenseclaw setup guardrail \
  --connector windsurf \
  --rule-pack strict \
  --scanner-mode both \
  --detection-strategy regex_judge \
  --judge-model anthropic/claude-sonnet-4-20250514 \
  --judge-api-key-env DEFENSECLAW_LLM_KEY \
  --restart

The alias keeps the connector pinned; the follow-up setup guardrail swaps in the strict rule pack, runs both local + Cisco AI Defense scanners, and turns the LLM judge on as a second-pass adjudicator on regex-flagged events.

Windsurf has no proxy enforcement, but its hooks themselves can block. After setup windsurf, edit ~/.defenseclaw/config.yaml and set the per-connector hook mode:

connector_hooks:
  windsurf:
    enabled: true
    mode: action          # observe (default) | action
    fail_mode: open       # open | closed

Then defenseclaw setup guardrail --restart to re-wire. With mode: action, Cascade hooks block on findings; HITL approvals downgrade to confirm verdicts in the DefenseClaw TUI since Windsurf has no native ask surface — make sure operators are reachable there.

Decision aids — should I turn this on?

Human-in-the-loop (HITL)

Per-connector ask matrix. Windsurf downgrades to confirm verdicts in the TUI / audit log since it has no native ask.

Full setup guardrail flag reference

All ~20 flags you can pass via `setup guardrail --connector windsurf` after the alias has pinned things.

Defaults & rule packs

What permissive / default / strict actually ship, and which one matches your risk tolerance.

Interactive wizard

Animated terminal demo of the prompt-by-prompt setup flow — the safest path the first time.

Not sure what to pick? Run defenseclaw setup guardrail (no flags) — the interactive wizard walks you through every choice with safe defaults pre-selected and inline help. The Prompt → flag mapping table gives you the CI-shaped command for the same configuration.

Files DefenseClaw will modify

hooks.json (DefenseClaw entries appended)

Hook capabilities

Block events

pre_user_prompt
pre_read_code
pre_write_code
pre_run_command
pre_mcp_tool_use

Native ask events

None — confirm verdicts are downgraded with the raw action preserved.

Windsurf has no native human-approval surface. HITL approvals downgrade to confirm verdicts; operators see them in the DefenseClaw TUI / audit log instead of inside Cascade.

Subprocess policy

none — Windsurf executes commands inside its own runtime; DefenseClaw observes via the pre_run_command hook rather than the openshell sandbox.

Disable

defenseclaw setup guardrail --disable