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

# Hooks Configuration

> Automate agent behavior with lifecycle hooks

## What Are Hooks?

Hooks are shell commands that execute automatically in response to agent lifecycle events. They enable:

* **Session initialization** - Set up context at start
* **Tool interception** - Validate or modify tool calls
* **Event reactions** - Respond to specific actions

## Hook Types

### Session Hooks

Execute when a session starts or ends:

```json theme={null}
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "squads status",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
```

### Tool Hooks

Execute before or after specific tool calls:

```json theme={null}
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Bash command: $TOOL_INPUT'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --fix"
          }
        ]
      }
    ]
  }
}
```

## Configuration

### Location

Hooks are configured in `.claude/settings.json`:

```
project/
└── .claude/
    └── settings.json    # Hook definitions
```

### Schema

```json theme={null}
{
  "hooks": {
    "<EventType>": [
      {
        "matcher": "<ToolPattern>",  // Optional: filter by tool
        "hooks": [
          {
            "type": "command",
            "command": "<shell command>",
            "timeout": 30,           // Optional: seconds
            "workingDirectory": "."  // Optional: cwd
          }
        ]
      }
    ]
  }
}
```

## Event Types

| Event          | Trigger                  | Common Uses               |
| -------------- | ------------------------ | ------------------------- |
| `SessionStart` | Agent session begins     | Load context, show status |
| `SessionEnd`   | Agent session ends       | Save state, cleanup       |
| `PreToolUse`   | Before any tool executes | Validation, logging       |
| `PostToolUse`  | After any tool executes  | Formatting, side effects  |
| `Notification` | Agent sends notification | Alerts, integrations      |

## Examples

### Auto-Format on Write

```json theme={null}
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$TOOL_OUTPUT_PATH\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
```

### Squad Status on Session Start

```json theme={null}
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "squads status",
            "timeout": 10
          }
        ]
      }
    ]
  }
}
```

### Git Commit Validation

```json theme={null}
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit:*)",
        "hooks": [
          {
            "type": "command",
            "command": "npm test",
            "timeout": 120
          }
        ]
      }
    ]
  }
}
```

### Notify on Completion

```json theme={null}
{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Agent completed\" with title \"Squads\"'"
          }
        ]
      }
    ]
  }
}
```

## Environment Variables

Hooks have access to context via environment variables:

| Variable           | Description                     |
| ------------------ | ------------------------------- |
| `TOOL_NAME`        | Name of the tool being called   |
| `TOOL_INPUT`       | Input parameters (JSON)         |
| `TOOL_OUTPUT`      | Output result (post-hooks only) |
| `TOOL_OUTPUT_PATH` | File path (for file operations) |
| `SESSION_ID`       | Current session identifier      |

## Best Practices

<Check>
  * Keep hooks fast (\< 10 seconds typical)
  * Use timeouts to prevent hangs
  * Log hook failures for debugging
  * Test hooks in isolation before deploying
  * Use matchers to target specific tools
</Check>

<Warning>
  **Common pitfalls:**

  * Infinite loops (hook triggers itself)
  * Missing error handling
  * Blocking hooks that slow agent work
  * Hardcoded paths that break across machines
</Warning>

## Debugging Hooks

### Check Hook Execution

```bash theme={null}
# Enable verbose logging
export CLAUDE_VERBOSE=1
claude
```

### Test Commands Manually

```bash theme={null}
# Run the hook command directly
squads status
```

### Validate JSON Syntax

```bash theme={null}
# Check settings.json is valid
cat .claude/settings.json | jq .
```

## Related

<CardGroup cols={2}>
  <Card title="MCP Configuration" icon="plug" href="/guides/mcp-configuration">
    Connect external tools and services
  </Card>

  <Card title="Secrets Management" icon="key" href="/guides/secrets-management">
    Handle sensitive configuration
  </Card>
</CardGroup>