Cursor Integration

Use the Cursor integration when you want FireGuard to check agent activity before Cursor submits prompts or runs actions in your workspace.

Requirements

• python3 available on PATH.
• A FireGuard API key.
• A FireGuard project ID with the policies and security guardrails you want to enforce.

Install

Install the Cursor hooks:

curl -fsSL https://raw.githubusercontent.com/fireravenai/fireraven-agent-hooks/refs/heads/main/install.sh | sh -s -- --agent cursor

Or install from a local clone of github.com/fireravenai/fireraven-agent-hooks:

./fg install --agent cursor
./fg doctor

Configure

Edit config.env in ~/.cursor/hooks/:

FIRERAVEN_GUARDRAILS_API_KEY=fg_...
FIRERAVEN_PROJECT_ID=00000000-0000-0000-0000-000000000000

Optional overrides (installer defaults are normal / open if omitted):

FIRERAVEN_API_URL=https://api.fireraven.ai
# FIRERAVEN_EXECUTION_MODE=fast
FIRERAVEN_REQUEST_TIMEOUT_SEC=15
# FIRERAVEN_FAIL_MODE=closed

Restart Cursor after editing config.env.

Configuration reference

FIRERAVEN_EXECUTION_MODE

Controls how FireGuard runs policy and security checks for each hook invocation. The value is passed as execution_mode on input and output guardrail API requests.

This setting can override the project default for agent hook calls without changing the project configuration in the Fireraven app. See FireGuard concepts — Execution modes.

FIRERAVEN_FAIL_MODE

Controls hook behavior when FireGuard cannot be reached because of a network error, request timeout, or HTTP failure.

closed and open apply only to FireGuard connectivity failures. Policy violations, guardrail blocks, and missing FIRERAVEN_GUARDRAILS_API_KEY or FIRERAVEN_PROJECT_ID always block regardless of FIRERAVEN_FAIL_MODE.

What Cursor Checks

Blocking responses

beforeSubmitPrompt blocks with:

{
  "continue": false,
  "user_message": "Blocked by Fireraven FireGuard."
}

Other blocking events return:

{
  "permission": "deny",
  "user_message": "Blocked by Fireraven FireGuard.",
  "agent_message": "Blocked by Fireraven FireGuard."
}

afterFileEdit is audit-only and returns an empty success object.

Human override

On FireGuard policy or security violations for beforeShellExecution, beforeMCPExecution, beforeReadFile, preToolUse, and subagentStart, the hook shows a blocking OS confirmation dialog (zenity or kdialog on Linux, osascript on macOS, MessageBox on Windows):

• Allow continues that action once.
• Deny, timeout, or no display keeps the deny.

Local sensitive-path blocks and missing FIRERAVEN_GUARDRAILS_API_KEY or FIRERAVEN_PROJECT_ID are not overridable. Prompt blocks on beforeSubmitPrompt stay hard deny — edit the prompt instead.

Cursor’s native permission: "ask" is not used; it is not reliably enforced today.

If Cursor also loads Claude Code third-party hooks, Fireraven’s Claude adapter no-ops under Cursor so enforcement stays on these native Cursor hooks.

JSONC and existing hooks

~/.cursor/hooks.json may contain JSONC comments (// or /* */). That is useful for temporarily disabling hooks or documenting entries.

The Fireraven installer reads JSONC and applies surgical edits so:

• Existing comments and formatting stay in place.
• Third-party hooks (for example another tool’s preToolUse matcher) are kept alongside Fireraven’s live preToolUse entry.
• Commented-out Fireraven blocks stay commented; the installer registers separate live Fireraven entries.

If install fails with a JSONC parse error, fix syntax problems in the file (not comments). Re-run the installer after correcting the file.

Verify

From a clone of the hooks repository, use:

./fg doctor

Windows

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/fireravenai/fireraven-agent-hooks/refs/heads/main/install.ps1))) -Agent cursor

The PowerShell installer writes:

The installer registers Cursor hooks as py -3 hooks/cursor_guardrail.py, which Cursor runs from %USERPROFILE%\.cursor. After editing config.env, restart Cursor or reload the window, then check View > Output > Hooks if a hook does not appear to run.

If the Python launcher is not available in Cursor's hook environment, edit hooks.json to use the fallback:

{
  "command": "powershell -NoProfile -ExecutionPolicy Bypass -File hooks/run_cursor_guardrail.ps1"
}

Related Pages