Hooks

Hooks are automated shell commands that run in response to agent events. They enable automatic code formatting, linting, testing, and validation without manual intervention.

How It Works

When an agent performs an action:

1. The event type is determined (PreToolUse, PostToolUse, etc.)
2. Matching hooks are identified based on event and tool matcher
3. The hook's shell command is executed
4. The agent receives the command output

File Location

Hooks are configured in .claude/settings.json:

1{
2  "hooks": {
3    "PostToolUse": [
4      {
5        "name": "prettier-on-write",
6        "matcher": "Write",
7        "command": "npx prettier --write $CLAUDE_FILE_PATH",
8        "timeout": 30000
9      }
10    ]
11  }
12}

Hook Events

Hook Configuration

name

Identifier for the hook. Used in logs and debugging.

matcher (optional)

Tool name to match. If specified, the hook only runs for that tool. Common matchers: Write, Edit, Bash.

command

Shell command to execute. Can include environment variables.

timeout

Maximum execution time in milliseconds. Default: 30000 (30 seconds).

Environment Variables

Hooks have access to context variables:

• $CLAUDE_FILE_PATH - The file being operated on
• $CLAUDE_TOOL_NAME - The tool being executed

Built-in Hook Templates

prettier-on-write

Auto-format files after writing.

1{
2  "name": "prettier-on-write",
3  "event": "PostToolUse",
4  "matcher": "Write",
5  "command": "npx prettier --write $CLAUDE_FILE_PATH",
6  "timeout": 30000
7}

eslint-on-write

Run ESLint after writing.

1{
2  "name": "eslint-on-write",
3  "event": "PostToolUse",
4  "matcher": "Write",
5  "command": "npx eslint --fix $CLAUDE_FILE_PATH",
6  "timeout": 30000
7}

typecheck-on-write

Run TypeScript type checking.

1{
2  "name": "typecheck-on-write",
3  "event": "PostToolUse",
4  "matcher": "Write",
5  "command": "npx tsc --noEmit",
6  "timeout": 60000
7}

test-on-write

Run related tests after writing.

1{
2  "name": "test-on-write",
3  "event": "PostToolUse",
4  "matcher": "Write",
5  "command": "npm test -- --findRelatedTests $CLAUDE_FILE_PATH",
6  "timeout": 120000
7}

block-secrets

Prevent committing files with secrets.

1{
2  "name": "block-secrets",
3  "event": "PreToolUse",
4  "matcher": "Bash",
5  "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'git commit'; then git diff --cached --name-only | xargs grep -l 'API_KEY\\|SECRET\\|PASSWORD' && exit 1 || exit 0; fi",
6  "timeout": 10000
7}

Complete Settings Example

1{
2  "hooks": {
3    "PreToolUse": [
4      {
5        "name": "block-secrets",
6        "matcher": "Bash",
7        "command": "echo 'Checking for secrets...'",
8        "timeout": 10000
9      }
10    ],
11    "PostToolUse": [
12      {
13        "name": "prettier-on-write",
14        "matcher": "Write",
15        "command": "npx prettier --write $CLAUDE_FILE_PATH",
16        "timeout": 30000
17      },
18      {
19        "name": "eslint-on-write",
20        "matcher": "Write",
21        "command": "npx eslint --fix $CLAUDE_FILE_PATH",
22        "timeout": 30000
23      }
24    ],
25    "Stop": [
26      {
27        "name": "final-check",
28        "command": "npm run lint && npm test",
29        "timeout": 180000
30      }
31    ]
32  }
33}

Configuration in Agent Workshop

In the Levers Configuration step, the Hooks tab lets you:

• Add from templates - Use pre-built hook templates
• Create custom - Define your own hooks
• Select event - Choose when the hook fires
• Configure matcher - Specify which tools trigger the hook
• Set command - Define the shell command to run
• Adjust timeout - Set execution time limit
• Enable/disable - Toggle individual hooks

Best Practices

Keep Commands Fast

Slow hooks disrupt the workflow. Use appropriate timeouts and optimize commands for speed.

Use Matchers Appropriately

Don't run formatting on non-code files. Use matchers to target specific tools and file types.

Handle Failures Gracefully

Consider what happens if a hook fails. For PostToolUse, failures are usually warnings. For PreToolUse, failures block operations.

Test Hooks Thoroughly

Test your hook commands manually before enabling them. Broken hooks can disrupt agent operation.

Be Careful with PreToolUse

PreToolUse hooks can block legitimate operations. Only use them for critical safety checks.