Hooks Configuration - Agents Squads

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:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "squads status",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Tool Hooks

Execute before or after specific tool calls:

{
  "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

{
  "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

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

Squad Status on Session Start

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "squads status",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Git Commit Validation

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

Notify on Completion

{
  "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

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

Common pitfalls:

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

Debugging Hooks

Check Hook Execution

# Enable verbose logging
export CLAUDE_VERBOSE=1
claude

Test Commands Manually

# Run the hook command directly
squads status

Validate JSON Syntax

# Check settings.json is valid
cat .claude/settings.json | jq .

MCP Configuration

Connect external tools and services

Secrets Management

Handle sensitive configuration

​What Are Hooks?

​Hook Types

​Session Hooks

​Tool Hooks

​Configuration

​Location

​Schema

​Event Types

​Examples

​Auto-Format on Write

​Squad Status on Session Start

​Git Commit Validation

​Notify on Completion

​Environment Variables

​Best Practices

​Debugging Hooks

​Check Hook Execution

​Test Commands Manually

​Validate JSON Syntax

​Related

MCP Configuration

Secrets Management

What Are Hooks?

Hook Types

Session Hooks

Tool Hooks

Configuration

Location

Schema

Event Types

Examples

Auto-Format on Write

Squad Status on Session Start

Git Commit Validation

Notify on Completion

Environment Variables

Best Practices

Debugging Hooks

Check Hook Execution

Test Commands Manually

Validate JSON Syntax

Related