> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raigal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent hooks

> Interception hooks for Claude Code, Cursor, and OpenCode.

Raigal can inspect code edits proposed by AI coding agents before they are saved to disk.

## How hooks work

When a coding agent modifies a file:

1. The hook executes a scoped in-memory AST scan on the changed files via `runScopedScan`.
2. Heavy processes (network audits, type-checking, and formatters) are skipped to keep turn latency low.
3. If the edit introduces pattern violations (such as swallowed exceptions or unsafe type assertions), the hook returns structured feedback into the agent turn.
4. The agent reads the machine-readable feedback and can self-correct within the same turn.

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Developer
    participant Agent as Claude / Cursor
    participant Hook as Raigal Hook
    participant Code as Workspace File
    Developer->>Agent: Prompt: "Add user profile validation"
    Agent->>Hook: Propose edit with redundant 'as any'
    Hook->>Hook: Run in-process AST scan
    Hook-->>Agent: Diagnostic: ai-slop/unsafe-type-assertion on line 42
    Agent->>Agent: Self-corrects to proper Zod schema
    Agent->>Code: Writes clean, validated code
```

## Installing hooks

Install hooks for all detected agents on your system:

```bash theme={null}
raigal hook install
```

Or target specific tools:

```bash theme={null}
raigal hook install --claude
raigal hook install --cursor
raigal hook install --gemini
```

Pass `--project` to scope hooks to the current repository only instead of your global user directory.

## Status, baselines, and safety

### Status and sentinel integrity

Check active hooks and verified SHA-256 sentinel hashes:

```bash theme={null}
raigal hook status
```

### Capturing baselines

Record pre-existing technical debt before running incremental checks:

```bash theme={null}
raigal hook baseline
```

This writes a fingerprint snapshot to `.raigal/baseline.json`. Subsequent agent edits are evaluated using 3-stage baseline matching, ensuring pre-existing debt does not trigger false regressions.

### Safe uninstallation

Remove hooks cleanly without disturbing hand-written editor settings:

```bash theme={null}
raigal hook uninstall
```

> [!NOTE]
>
> To connect Raigal tools directly to your agent tool-calling loop instead of relying on file system hooks, see the [Raigal MCP server](/automation-and-ci-cd/mcp-server.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.