Claude Code Hook

Install the CLI if you haven't — see Getting Started.

Log in the hook (a separate credential from aevrin login, so hook and CLI usage stay independently attributable even for the same person):

aevrin hook setup

This prints a ready-to-paste JSON snippet pointing at the hook script bundled inside your aevrin install — the same package you already installed via pip/pipx.

Merge the printed snippet into your project's .claude/settings.json. If the file already has a hooks key, merge rather than overwrite it — the snippet looks like this:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python3 /path/to/hook_script.py", "timeout": 8 }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "python3 /path/to/hook_script.py", "timeout": 8 }]
      }
    ]
  }
}

Try it — ask Claude Code to add an MCP server. The hook checks it before the install runs.

Check for a cached result first — one fast POST /hook/cache call (a Supabase lookup, not a live scan). The request body keeps pasted configuration out of URL logs, while the short lookup stays within the hook's timeout budget.

Clean cached scan → allow silently, with a small confirmatory note (Aevrin: clean scan on record (score N/100)).

Cached scan has unresolved critical/high findings → block, with the score and each finding's title, severity, OWASP category, file/line, and remediation in the denial reason — plus three explicit options: fix it directly, run aevrin hook allow <target> to install anyway, or aevrin findings triage <id> false_positive --reason "..." to dispute a specific finding.

Cached scan's tools couldn't run → block as incomplete, never silently allowed. Docker down, a missing binary, or no network access on the machine that scanned it means the findings list is empty because nothing ran — not because the target is clean. See Concepts → Incomplete scans.

No cached result → allow, with a visible "not yet scanned" warning. The actual scan starts server-side in the background (the /hook/cache endpoint kicks it off via FastAPI BackgroundTasks) — the hook script itself never runs or waits on a scan, only ever makes one short HTTP request. The next install attempt of the same target will have a cached result to check against.