Hooks — Automating Claude's Actions

What hooks do

A hook runs a shell command at a specific point in Claude's workflow — think of them as event listeners for the agentic loop. Depending on configuration they run synchronously, blocking the next action until they finish, or asynchronously, firing off and letting Claude continue.

That distinction matters. A synchronous hook is a gate: if it fails, the action it guards is stopped. An asynchronous hook is a side effect: it notifies or logs without slowing anything down. Choosing the right mode for each job is the core skill of hook design.

Hook types

Five lifecycle events let you attach behavior at every meaningful phase of a session.

Setting up hooks in settings.json

Hooks are configured in .claude/settings.json under a top-level "hooks" key. Each event holds an array of rules; each rule has a matcher that scopes when it fires and a list of hooks commands to run.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": {"tool_name": "write_file", "file_paths": ["**/*.ts", "**/*.tsx"]},
        "hooks": [
          {"type": "command", "command": "npx eslint --fix ${file_path}"},
          {"type": "command", "command": "npx prettier --write ${file_path}"}
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": {"tool_name": "bash", "command_pattern": "git push"},
        "hooks": [
          {"type": "command", "command": "npm run typecheck && npm test"}
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {"type": "command", "command": "echo 'Session started at $(date)' >> ~/.claude/session.log"}
        ]
      }
    ]
  }
}

Here the PreToolUse hook is a gate — if typecheck or tests fail, the git push never happens. The PostToolUse hook is cleanup that lints and formats every TypeScript file Claude writes.

Practical hook patterns

A few rules cover most of what teams actually want automated. Auto-format after every TypeScript edit:

{"matcher": {"file_paths": ["**/*.ts"]}, "hooks": [{"command": "npx prettier --write ${file_path}"}]}

Notify Slack when Claude finishes a session:

{"type": "PostSessionEnd", "command": "curl -X POST $SLACK_WEBHOOK -d '{\"text\": \"Claude Code session finished\"}'"}

Run a security scan before any commit:

{"matcher": {"tool_name": "bash", "command_pattern": "git commit"}, "hooks": [{"command": "npm run security-scan"}]}

Environment variable expansion

Hooks receive context about the action that triggered them, exposed as variables you can interpolate into commands:

• ${file_path} — the file the tool acted on
• ${tool_name} — the tool that triggered the hook
• ${working_directory} — the directory the session is running in

Use them to make hooks file-aware and context-sensitive — that's how prettier --write ${file_path} formats exactly the file Claude just edited rather than the whole tree.

Hooks for sub-agents

Hooks can also be defined directly in a sub-agent's frontmatter, scoping them to that agent's behavior only. This is ideal for specialized agents that need different quality gates — a security-review agent might run extra scans that the rest of your workflow doesn't need.

Pitfalls and best practices

Claude Code Hooks FAQ