Hooks

Hooks are scripts that run automatically at specific points in a coding agent's lifecycle. They enable automation, validation, and customization of agent behavior.

What Are Hooks?

Hooks are shell commands or scripts that execute in response to events during an agent session. They run on your local machine, not in the AI model.

┌─────────────┐     ┌──────────────┐     ┌────────────┐
│ Tool Called │ ──► │ Pre-Tool     │ ──► │ Execute    │
│             │     │ Hook (runs)  │     │ Tool       │
└─────────────┘     └──────────────┘     └──────┬─────┘
                                                │
                                                ▼
                                         ┌──────────────┐
                                         │ Post-Tool    │
                                         │ Hook (runs)  │
                                         └──────────────┘

Hook Types

Hook	When It Runs	Use Cases
Pre-Tool	Before a tool executes	Validation, blocking, logging
Post-Tool	After a tool executes	Formatting, cleanup, notifications

Common Use Cases

Auto-Format Code

Format files automatically after the agent edits them:

Trigger: File edited or written
Action: Run prettier/black/gofmt on the file
Result: All generated code matches project formatting standards

This fixes the "last 10%" that would otherwise fail CI—the agent writes correct code, and the hook ensures correct formatting.

Lint on Save

Run linting after file changes:

Trigger: File edited or written
Action: Run eslint/ruff/clippy with auto-fix
Result: Common issues fixed automatically

Validate Before Commit

Check for issues before allowing commits:

Trigger: Git commit command
Action: Run tests, linting, type checking
Result: Broken code never gets committed

Block Dangerous Commands

Prevent destructive operations:

Trigger: Command matching pattern (e.g., rm -rf)
Action: Block execution, warn user
Result: Accidental destruction prevented

Custom Notifications

Send notifications on specific events:

Trigger: Git push
Action: Send Slack message or desktop notification
Result: Team knows code was pushed

Environment Variables

Hooks typically receive context through environment variables:

Variable	Description
File path	Path to the affected file
Tool name	Name of the tool being used
Tool input	Input parameters for the tool
Tool output	Output from the tool (post-hooks only)

The specific variable names depend on your coding agent's implementation.

Best Practices

Keep Hooks Fast

Slow hooks impact the agent's workflow:

• Target < 1 second for most hooks
• Use async where possible for longer operations
• Cache expensive operations to avoid repeated work

Fail Gracefully

Don't break the workflow unnecessarily:

• Allow non-critical hooks to continue on error
• Log failures for debugging without stopping work
• Make blocking behavior explicit and intentional

Log for Debugging

Include logging to diagnose issues:

#!/bin/bash
echo "[Hook] Formatting $FILE_PATH" >> /tmp/agent-hooks.log
prettier --write "$FILE_PATH"

Test Hooks Independently

Before adding a hook, test the command manually:

FILE_PATH="src/example.ts" prettier --write "$FILE_PATH"

Hooks vs Other Features

Feature	Use When
Hooks	You need to run external commands automatically
Project Instructions	You want to give the agent instructions
Skills	You want to define reusable prompts
MCP Servers	You need to expose external tools to the agent

Hooks complement these features—use them together for powerful automation.

Learn More

For implementation details specific to your coding agent:

• Claude Code: Hooks Documentation
• Other agents: Check your agent's documentation for lifecycle event support

The concepts above apply broadly, but configuration syntax varies by agent.