Cursor

Cursor connector wires user hooks for observe-only inspection or event-native action denial.

The Cursor connector wires DefenseClaw into Cursor's user-scoped hooks.json so documented prompt, tool, shell, MCP, file, and lifecycle events can be evaluated.

Cursor runs every matching hook and merges conflicts in Enterprise > Team > Project > User priority. DefenseClaw owns only the user hook. It cannot prove that an Enterprise, Team, or Project source is absent, and Cursor exposes no safe API for detecting an actual higher-priority conflict. DefenseClaw reports that limitation and does not infer a conflict. Ordinary user-hook action mode returns the documented native deny response on supported pre-action events and writes failClosed: true; observe remains allow/would_block with failClosed: false. Native ask/HITL is not enabled. No Enterprise or Team hook system is implemented by this connector.

Platform support

Platform	Status	Connector path
macOS and Linux	Supported	User-scoped command hooks invoke the portable DefenseClaw hook.
Native Windows x64	Supported	User-scoped command hooks invoke the managed `cursor-hook.ps1` pipeline adapter and protected `defenseclaw-hook.exe`. Validation metadata remains empty and `live=false`; the support label does not fabricate certification evidence.

Setup

defenseclaw setup cursor
defenseclaw setup cursor --mode action --no-human-approval

The default command installs observe-mode user hooks. Action mode returns event-native deny responses and deliberately leaves native HITL disabled.

defenseclaw setup cursor
defenseclaw setup cursor --mode action --no-human-approval

DefenseClaw writes %USERPROFILE%\.cursor\hooks.json and registers the managed cursor-hook.ps1 adapter. The adapter preserves Cursor's JSON pipeline input, synchronously invokes the protected defenseclaw-hook.exe, waits for its documented response, and returns that response to Cursor. WSL and mixed Windows/WSL paths are outside this native connector path.

This defaults to the observe template. Cursor talks directly to its native upstream; DefenseClaw inspects and, in action mode, denies through hooks. There is no proxy-enforcement path for Cursor. DefenseClaw does not claim enterprise-wide authority or native human approval.

What `setup cursor` actually does

The table highlights convenience options rather than the complete alias surface. The alias also accepts --mode, --rule-pack, --fail-mode, approval, block-message, add/replace, workspace, and rule-pack-directory options. See the quick-alias reference; use full guardrail setup for scanner, detection-strategy, and judge-provider configuration.

Flag	Default	What it does
`--yes / -y`	off	Skip the confirmation prompt.
`--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 run `setup local-observability up`; follow the command's printed gateway-restart step after it writes the export destination.

setup cursor is the dedicated Cursor alias. It uses the shared guardrail setup backend, defaults to observe mode, and can join an existing hook-connector roster when you choose Add.

--mode action pins the managed registration to failClosed: true; --mode observe pins it to failClosed: false. A conflicting --fail-mode value is ignored with a warning so observe cannot become blocking and action cannot silently become fail-open. Human approval remains disabled. Setup/repair reports readiness only after the current 21-event type: command, 30-second, mode-matched registration, managed runtime adapter, contract lock, and complete active-connector roster agree. Adding or repairing another connector waits for that full roster, so it cannot report success after displacing an already configured Cursor registration.

Common variations — pick the recipe that fits your phase

defenseclaw setup cursor

Confirms once, wires observe-mode hooks against ~/.cursor/hooks.json, and restarts the gateway. Findings flow to mandatory SQLite event history and the TUI; configured v8 destinations receive only the buckets/signals their routes select. No traffic is intercepted and observe mode does not block. Pass --yes to skip the confirmation in CI.

defenseclaw setup cursor --mode action --no-human-approval --yes

Registers all 21 managed command hooks with failClosed: true. Policy blocks on supported pre-action events return Cursor's event-native deny shape. Confirm verdicts remain attributed alerts because DefenseClaw does not enable native ask/HITL. Status and Doctor report action plus user-hook enforcement while also reporting that higher-priority conflict detection is unavailable.

defenseclaw setup cursor --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. That command writes the export destination after the alias has already restarted the gateway, so run its printed defenseclaw-gateway restart step before expecting exports. See Local observability.

export DEFENSECLAW_LLM_KEY='replace-with-your-key'

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

The alias selects Cursor; the follow-up setup guardrail --connector cursor swaps in the strict rule pack, keeps scanning local, and turns the LLM judge on as a second-pass adjudicator on regex-flagged events. Configure the remote scanner separately through full guardrail setup, which validates its endpoint and API-key environment variable.

Decision aids — should I turn this on?

Human-in-the-loop (HITL)

DefenseClaw does not enable Cursor native ask/HITL; confirm verdicts remain attributed alerts.

Full setup guardrail flag reference

The complete flag surface for `setup guardrail --connector cursor`.

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)

Fresh setup ignores ambient DEFENSECLAW_CURSOR_CONFIG_HOME and binds the official %USERPROFILE%\.cursor location. Only an authenticated persisted DefenseClaw custody record may restore or migrate a historical path.

Local inventory covers:

project and user .cursor/mcp.json; same-name scope candidates and dynamic extension servers are retained as unverified rather than assigned an invented winner;
recursive SKILL.md discovery under project/user .cursor/skills, .agents/skills, .claude/skills, and .codex/skills, including nested project .cursor/skills and .agents/skills roots;
.cursor/rules/**/*.mdc plus root and nested AGENTS.md;
project/user .cursor/agents, .claude/agents, and .codex/agents, with project over user and .cursor over compatibility roots; and
existing local plugins under ~/.cursor/plugins/local, inventory-only.

Scanning is bounded and does not follow symlinks, junctions, or reparse points. Multi-root effective selection, cloud agents, marketplace/team/private sources, dynamic plugin/MCP sources, user UI rules, and runtime-only assets remain explicitly unverified.

Hook capabilities

Block events

preToolUse
subagentStart
beforeShellExecution
beforeMCPExecution
beforeReadFile
beforeTabFileRead
beforeSubmitPrompt

Native ask events

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

The current documented roster includes subagentStart. Result inspection lifts and bounds tool_output, error_message, shell output, MCP result_json, file edits, agent text, and subagent summary from their event-specific schemas. beforeMCPExecution preserves its exact tool_input and URL/command and derives a stable digest identity without inventing a vendor name.

Action blocking is limited to preToolUse, subagentStart, beforeShellExecution, beforeMCPExecution, beforeReadFile, beforeTabFileRead, and beforeSubmitPrompt. beforeSubmitPrompt blocks with continue: false; the permission-gated events use permission: "deny". Observe maps the same policy findings to allow plus would_block audit state. sessionStart and sessionEnd are not gates. stop and subagentStop accept only a follow-up message and are not blocking surfaces.

The hook payload's cursor_version is the Cursor application/Desktop version. It is not Agent CLI evidence. The connector keeps agent --version contract selection separate and remains pinned to the exact reviewed Agent build; no Desktop release number is promoted into that Agent contract.

Cursor spawns command-hook processes and automatically reloads hooks.json. If a change is not loaded, restart Cursor. Teardown therefore restores the exact pre-DefenseClaw config or removes only DefenseClaw-owned entries, then removes only managed adapter files; it does not rely on an undocumented cached hook process.

Disable

defenseclaw guardrail disable --connector cursor --yes