# Hooks & Agents

> How Infa CLI configures Claude Code hooks during automated runs to report progress back to the cloud.

Source: https://infa.ai/docs/infa-cli-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.

## 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.

## Hook configuration

Infa writes three hook types:

```json title=".claude/settings.local.json (generated)"
{
  "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
      }]
    }]
  }
}
```

| Hook | When it fires | Type |
| ---- | ------------- | ---- |
| `PostToolUse` (Edit\|Write\|MultiEdit\|Bash) | After every file edit or shell command | HTTP |
| `Stop` | When Claude finishes responding | HTTP |
| `SessionEnd` | When the Claude process exits | Shell `curl` |

## Environment variables

Claude is also spawned with these environment variables:

| Variable | Value | Purpose |
| -------- | ----- | ------- |
| `INFA_RUN_ID` | Unique run identifier | Identify the run in hook payloads |
| `INFA_RUN_TOKEN` | User's OAuth access token | Authenticate hook requests |
| `INFA_PAPER_ID` | Cloud Paper ID (if set) | Link session output to a Paper |

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

## 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

## 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.

**Don't commit settings.local.json** This file contains a bearer token. Ensure .claude/settings.local.json is in your .gitignore.

## Next steps

- [Run Modes](https://infa.ai/docs/infa-cli-run-modes) — when hooks are active vs not
- [CLI Reference](https://infa.ai/docs/infa-cli-reference)
