Claude Integration

Use the Claude integration when you want FireGuard to check Claude Code tool calls and typed prompts before they run.

Requirements

• python3 available on PATH (Windows: Python launcher py -3).
• A FireGuard API key.
• A FireGuard project ID with the policies and security guardrails you want to enforce.

Install

Install the Claude Code hooks:

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

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

./fg install --agent claude
./fg doctor

Configure

Edit config.env in ~/.claude/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 Claude Code after editing config.env.

FIRERAVEN_EXECUTION_MODE

See FireGuard concepts — Execution modes.

FIRERAVEN_FAIL_MODE

The installer registers Claude Code hooks in ~/.claude/settings.json.

What Claude Checks

Claude Code runs the claude_guardrail.py entry script on these events:

Prompts and tool calls reach FireGuard; conversations appear in the dashboard even when no tools run.

FileChanged and SubagentStart are not registered as guardrail gates (SubagentStart cannot block; Agent prompts are already covered by PreToolUse).

Human override

On FireGuard policy or security violations for PreToolUse, the hook returns:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Blocked by Fireraven FireGuard."
  }
}

Claude Code’s UI then prompts Allow or Deny. That click is the override — there is no config flip. Local sensitive-path blocks and missing credentials stay hard deny (exit 2). UserPromptSubmit stays hard deny; edit the prompt instead.

If Cursor has third-party Claude Code hooks enabled, it may also invoke ~/.claude/settings.json hooks during Cursor sessions. Fireraven’s Claude adapter detects Cursor (cursor_version / CURSOR_VERSION) and exits without enforcing so native Cursor hooks remain the only FireGuard path. To stop those invocations entirely, disable Include third-party Plugins, Skills, and other configs in Cursor Settings → Rules, Skills, Subagents.

The installer registers entries like:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /home/you/.claude/hooks/claude_guardrail.py"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /home/you/.claude/hooks/claude_guardrail.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /home/you/.claude/hooks/claude_guardrail.py"
          }
        ]
      }
    ]
  }
}

On Linux and macOS the installer uses an absolute python3 path. On Windows it uses py -3 with a forward-slash absolute path — see Windows below.

Verify

From a clone of the hooks repository:

./fg doctor

In Claude Code after install:

1. Trigger a tool call — a session file should appear under ~/.claude/hooks/state/.
2. Submit a benign chat prompt — it should proceed normally.
3. Submit a policy-violating prompt — Claude Code should block it with a UserPromptSubmit hook error (exit 2) before responding.
4. Trigger a policy-violating tool call — Claude Code should prompt Allow/Deny via PreToolUse ask (not a silent hard fail).
5. Confirm a Claude Code conversation appears in the FireGuard dashboard (including prompt-only sessions with no tools).

Smoke-test the hook script directly:

echo '{"session_id":"test","hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"echo hi"}}' \
  | python3 ~/.claude/hooks/claude_guardrail.py

echo '{"session_id":"test","hook_event_name":"UserPromptSubmit","prompt":"hello"}' \
  | python3 ~/.claude/hooks/claude_guardrail.py

Windows

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

The PowerShell installer writes:

Claude Code runs hook commands through a POSIX shell (Git Bash), not PowerShell. The installer registers hooks as a direct py -3 call with a forward-slash absolute path — for example py -3 C:/Users/you/.claude/hooks/claude_guardrail.py. Do not wrap hooks in PowerShell with $input; Git Bash expands $input to empty, PowerShell fails to parse the pipe, and Claude Code silently allows tools through unguarded.

Piping a PowerShell string into Python can add a UTF-8 BOM and break JSON parsing; the direct py -3 command avoids that because stdin arrives as clean UTF-8.

Confirm %USERPROFILE%\.claude\settings.json uses direct py -3 C:/.../claude_guardrail.py commands (no powershell wrapper) for PreToolUse, UserPromptSubmit, and PostToolUse.

Related Pages