Hooks & Automation

What are Hooks?

Hooks allow you to run commands before or after Claude Code does something. You can also optionally block Claude's action.

Example Use Cases

• • Run a code formatter after Claude edits a file
• • Stop Claude from reading sensitive files like .env
• • Check for TODO comments and log them automatically
• • Run tests automatically after a file is changed
• • Block file edits that violate naming conventions
• • Prevent usage of deprecated functions

Available Tools to Monitor

Read       # Read a file
Edit       # Edit an existing file
MultiEdit  # Multiple edits in one operation
Write      # Create a file and write to it
Bash       # Execute a shell command
Glob       # Find files/folders by pattern
Grep       # Search for content in files
Task       # Create a sub-agent

Building a Hook: 4 Steps

Exit Codes

Configuration File

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "node /path/to/hook.js"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write"
          }
        ]
      }
    ]
  }
}

Example 1: Protect .env Files

This hook prevents Claude from reading sensitive files like .env that contain API keys and secrets.

async function main() {
  const chunks = [];
  for await (const chunk of process.stdin) {
    chunks.push(chunk);
  }
  const toolArgs = JSON.parse(Buffer.concat(chunks).toString());

  // Get the file path Claude is trying to read
  const readPath = toolArgs.tool_input?.file_path ||
                   toolArgs.tool_input?.path || "";

  // Block .env files
  if (readPath.includes(".env")) {
    console.error("Access denied: .env files are protected");
    process.exit(2); // Block the read
  }

  process.exit(0); // Allow other reads
}

main();

Example 2: TypeScript Type Checking

Run the TypeScript compiler after every edit to catch type errors immediately.

import * as ts from "typescript";

async function main() {
  const input = await readInput();
  const file = input.tool_response?.filePath ||
               input.tool_input?.file_path;

  // Only check TypeScript files
  if (!file || !/\.(ts|tsx)$/.test(file)) {
    process.exit(0);
  }

  const errors = runTypeCheck("./tsconfig.json");
  if (errors) {
    console.error(errors);
    process.exit(2); // Report errors to Claude
  }
}

main();

Beyond PreToolUse and PostToolUse

Claude Code provides several additional hook types for different lifecycle events:

Practical Example: Auto-Format on Save

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Tip 9: Code Formatting with PostToolUse

Automatically runs Prettier every time Claude modifies a file, keeping code style consistent.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_response.filePath // .tool_input.file_path' | xargs npx prettier --write 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Tip 10: Permission Management with /permissions

Use the /permissions command to check and manage the current session's permissions.

Tip 12: ralph-loop Plugin (Long-running Tasks)

Implements a self-referencing loop that automatically restarts Claude after task completion. Can be used with background agents to automate long-running tasks.

# Re-invoke Claude from the Stop hook
{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "claude --continue"
          }
        ]
      }
    ]
  }
}

Official Plugins

# Install
claude plugins add github:anthropics/hookify

# Run hook creation wizard
/hookify:create

# Install
claude plugins add github:anthropics/ralph-loop

# Start long-running task
/ralph-loop:start "Perform large-scale refactoring"