Hooks

Automate workflows with Claude Code hooks

title: Hooks description: Automate workflows with Claude Code hooks

Hooks allow you to run custom commands at specific points during Claude Code's operation. Use them to automate workflows, enforce standards, and integrate with external tools.

Overview

Hooks execute shell commands in response to Claude Code events:

• Pre-tool hooks - Run before a tool executes
• Post-tool hooks - Run after a tool completes
• Notification hooks - Send alerts for specific events

Configuration

Hooks are configured in your settings file:

Location: ~/.claude/settings.json (global) or .claude/settings.json (project)

Pre-Tool Hooks

Run commands before Claude executes a tool.

Basic Example

With File Path

Conditional Execution

Stop tool execution if the hook fails:

If eslint exits with a non-zero code, the write is cancelled.

Post-Tool Hooks

Run commands after a tool completes.

Basic Example

Run Tests After Changes

Auto-Format Code

Git Auto-Stage

Matcher Patterns

Matchers specify which tools trigger hooks:

Tool Name Only

Matches any Write tool execution.

Tool with File Pattern

Matches Write operations on TypeScript files.

Glob Patterns

Matches Write operations on TSX files in src directory.

Multiple Extensions

Matches Write operations on any JS/TS file.

Bash Commands

Matches npm commands executed via Bash tool.

All Tools

Matches any tool execution.

Environment Variables

Hooks have access to these environment variables:

| Variable | Description | |----------|-------------| | $CLAUDE_TOOL | Name of the tool being executed | | $CLAUDE_FILE_PATH | File path (for file operations) | | $CLAUDE_WORKING_DIR | Current working directory | | $CLAUDE_EXIT_CODE | Tool exit code (post hooks only) | | $CLAUDE_OUTPUT | Tool output (post hooks only) |

Using Variables

Hook Options

blocking

If true, hook failure stops the tool execution:

timeout

Maximum execution time in milliseconds:

shell

Specify which shell to use:

cwd

Set working directory:

Notification Hooks

Send notifications for specific events:

Desktop Notification

Slack Notification

Sound Alert

Common Patterns

1. Code Quality Pipeline

2. Auto-Documentation

3. Security Scanning

4. Backup Before Changes

5. Auto-Commit

6. Test Runner

7. Build Trigger

8. Change Log

Advanced Patterns

Chained Hooks

Run multiple commands in sequence:

Conditional Logic

Use shell conditionals:

Script Files

For complex logic, use external scripts:

.claude/hooks/on-file-write.sh:

Debugging Hooks

Verbose Mode

This shows:

• Which hooks are triggered
• Command being executed
• Exit codes and output

Test Commands Manually

Before adding to config, test commands:

Log Hook Execution

Troubleshooting

Hook Not Executing

1. Check matcher pattern matches the tool
2. Verify command exists and is executable
3. Check for syntax errors in JSON
4. Enable debug mode

Hook Blocking Unexpectedly

1. Check exit codes of commands
2. Remove blocking: true temporarily
3. Test command manually
4. Add error handling to scripts

Performance Issues

1. Use async hooks where possible (remove blocking)
2. Avoid expensive operations in pre-hooks
3. Use file patterns to limit scope
4. Consider debouncing rapid changes

Security Considerations

1. Validate inputs - Don't blindly execute based on file paths
2. Use absolute paths - Avoid path injection
3. Limit scope - Use specific matchers instead of *
4. Review scripts - Audit hook scripts for vulnerabilities
5. Protect secrets - Don't log sensitive information

Next Steps

• Configure MCP servers →
• Set up IDE plugins →
• Learn about the API →