Hooks & Agents

During automated local and remote / cloud runs, Infa CLI automatically configures Claude Code hooks. These hooks report activity back to Supabase in real time, so the Infa web UI can show live progress as Claude works.

Interactive sessions (infa session start) do not use hooks.

Copy link

What are hooks?

Claude Code hooks are HTTP or shell callbacks that fire on specific events during a session. Infa writes them to .claude/settings.local.json in the target repo before spawning Claude. The file is automatically deleted when the session ends.

Copy link

Hook configuration

Infa writes three hook types:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write|MultiEdit|Bash",
      "hooks": [{
        "type": "http",
        "url": "https://{project}.supabase.co/functions/v1/run-hook",
        "timeout": 10,
        "headers": { "Authorization": "Bearer {run_token}" }
      }]
    }],
    "Stop": [{
      "hooks": [{
        "type": "http",
        "url": "https://{project}.supabase.co/functions/v1/run-hook",
        "timeout": 10,
        "headers": { "Authorization": "Bearer {run_token}" }
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "command": "curl -s -X POST '{hook_url}' -H 'Content-Type: application/json' -H 'Authorization: Bearer {token}' -d '{\"event\":\"session_end\",\"run_id\":\"{runId}\"}'",
        "timeout": 1
      }]
    }]
  }
}

Copy link

Environment variables

Claude is also spawned with these environment variables:

These are available inside Claude sessions — for example, a custom agent prompt can reference $INFA_RUN_ID.

Copy link

The run-hook edge function

All hooks point to the run-hook Supabase Edge Function. This function:

• Receives the event payload from Claude
• Updates the run record in the runs table (status, session_url, etc.)
• Stores the Claude session URL when detected in output (format: https://claude.ai/...)
• Broadcasts updates via Supabase Realtime to the web UI

Copy link

Cleanup

Hooks are automatically removed when the session ends:

Session exits (code 0 or non-zero)
    └─ .claude/settings.local.json is deleted

If a session crashes before cleanup, the file is left on disk and will be overwritten the next time a run starts on the same repo.

Copy link

Next steps

• Run Modes — when hooks are active vs not
• CLI Reference