Local Agent Hooks
Install FireGuard Agent Hooks for Windsurf, Devin, Cursor, and Claude Code.
Local Agent Hooks install Python entry scripts into each agent's hook directory and register them in the agent's hook configuration. Restart the IDE or agent after installation so the new hook configuration is loaded.
Requirements
python3available onPATH.- A FireGuard API key.
- A FireGuard project ID with the policies and security guardrails you want to enforce.
Install Commands
Install one agent:
curl -fsSL https://raw.githubusercontent.com/fireravenai/fireraven-agent-hooks/refs/heads/main/install.sh | sh -s -- --agent windsurf
curl -fsSL https://raw.githubusercontent.com/fireravenai/fireraven-agent-hooks/refs/heads/main/install.sh | sh -s -- --agent cursor
curl -fsSL https://raw.githubusercontent.com/fireravenai/fireraven-agent-hooks/refs/heads/main/install.sh | sh -s -- --agent claudeInstall all supported local agents:
curl -fsSL https://raw.githubusercontent.com/fireravenai/fireraven-agent-hooks/refs/heads/main/install.sh | sh -s -- --agent allConfigure Each Install
Edit config.env in each installed hooks directory:
FIRERAVEN_GUARDRAILS_API_KEY=fg_...
FIRERAVEN_PROJECT_ID=00000000-0000-0000-0000-000000000000Installed paths:
| Agent | Hooks directory | Registration file |
|---|---|---|
| Windsurf / Devin | ~/.codeium/windsurf/hooks/ | ~/.codeium/windsurf/hooks.json |
| Cursor | ~/.cursor/hooks/ | ~/.cursor/hooks.json |
| Claude Code | ~/.claude/hooks/ | ~/.claude/settings.json |
Keep config.env private. The installer creates it with restricted permissions when possible.
Windsurf / Devin
Windsurf and Devin run the windsurf_guardrail.py entry script.
| Event | Mode | What FireGuard checks |
|---|---|---|
pre_user_prompt | Blocking | User prompts before the agent receives them. |
pre_run_command | Blocking | Shell commands and working directory context. |
pre_mcp_tool_use | Blocking | MCP server, tool name, and arguments. |
pre_write_code | Blocking | File path and proposed edits. |
pre_read_code | Blocking | File path and, for small files, a content preview. |
post_cascade_response | Audit | Agent response text after generation. |
post_write_code | Audit | Applied file-write content. |
Blocked pre-hook events exit with code 2. Audit events log unsafe output but do not block the already-completed action.
Cursor
Cursor runs the cursor_guardrail.py entry script.
| Event | What FireGuard checks |
|---|---|
beforeSubmitPrompt | User prompts before submission. |
beforeShellExecution | Shell commands before execution. |
beforeMCPExecution | MCP tool name and arguments. |
beforeReadFile | File read paths. |
preToolUse | Generic tool name and tool input where available. |
Cursor blocks by returning:
{
"permission": "deny",
"user_message": "Blocked by Fireraven FireGuard.",
"agent_message": "Blocked by Fireraven FireGuard."
}Claude Code
Claude Code runs the claude_guardrail.py entry script through PreToolUse hooks.
The installer registers a matcher for all tools:
{
"matcher": ".*",
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/claude_guardrail.py"
}
]
}Unsafe tool input exits with code 2, which blocks the tool use.
Local Sensitive Path Blocking
The hooks include a local path guard for common sensitive path patterns before sending file-read requests to FireGuard. Paths containing values such as .env, id_rsa, credentials, secret, .pem, token, or api_key are blocked locally.
Verify
From a clone of github.com/fireravenai/fireraven-agent-hooks, use:
./fg doctorThe doctor command checks python3, config.env, and hook registration for the supported local agents.
Uninstall
Remove all local hook registrations:
curl -fsSL https://raw.githubusercontent.com/fireravenai/fireraven-agent-hooks/refs/heads/main/uninstall.sh | sh -s -- --agent allOr from a clone:
./fg uninstall --agent all
./fg uninstall --agent cursor