Claude Code Hooks: Enforce Rules and Automate Actions

A hook is a function that Claude Code invokes at a specific point in the tool-execution lifecycle: either before a tool runs (pre-tool hook) or after it completes and returns a result (post-tool hook). The hook receives context about the request — what tool, what arguments, what working directory — and returns a decision:

• Allow — tool executes as normal
• Reject — tool is blocked, and Claude Code is told why it failed
• Modify — hook changes the arguments (e.g., git push origin main becomes git push origin my-feature)
• Augment (post-tool only) — hook adds data to the result (e.g., test stdout becomes test stdout + Slack notification sent)

Hooks are registered in .claude/settings.json under the hooks key, or loaded from .claude/hooks/ as individual files. They can be synchronous (return immediately) or asynchronous (wait for a network call to complete), and they can be JavaScript, Python, or shell scripts.

Running example: a payments-api repository has three hooks:

1. Pre-tool, git: block any commit to main 2. Pre-tool, bash: prevent commands that write to the database without a transaction 3. Post-tool, bash: post a Slack message when tests pass

Pre-tool hooks fire right after Claude Code decides to call a tool but before the tool actually runs. They are the place to enforce policy: no commits to main, no deletes without confirmation, no database changes without explicit approval.

Example: your team rule is "no direct push to main." Add this hook:

1// .claude/hooks/block-main-push.js2module.exports = async (context) => {3  const { tool, args } = context;4  if (tool === "bash" && args.command.includes("git push") && args.command.includes("origin main")) {5    return {6      allowed: false,7      reason: "Direct pushes to main are blocked. Create a pull request instead: git push -u origin <branch>, then open a PR.",8      suggestion: `git push -u origin $(git rev-parse --abbrev-ref HEAD)`,9    };10  }11  return { allowed: true };12};

When Claude Code tries to execute git push origin main, this hook will reject it with a message and a suggested alternative. Claude Code will show the error to the user and ask what to do next — user can approve a retry with the suggested command, or give Claude Code a new instruction.

Another example: block database writes outside of transactions:

1// .claude/hooks/require-transaction.js2module.exports = async (context) => {3  const { tool, args } = context;4  if (tool === "bash" && args.command.includes("psql") && !args.command.includes("BEGIN")) {5    return {6      allowed: false,7      reason: "Database commands must be wrapped in a transaction (BEGIN...COMMIT). Add BEGIN; and COMMIT; to your command.",8    };9  }10  return { allowed: true };11};

Post-tool hooks fire after a tool completes and returns a result. They are useful for notifications, logging, conditional triggers, and adding context to the result.

Example: when tests pass, post a Slack notification:

1// .claude/hooks/notify-slack-on-test-pass.js2module.exports = async (context) => {3  const { tool, result } = context;4  if (tool === "bash" && result.command.includes("npm test") && result.exitCode === 0) {5    await fetch(process.env.SLACK_WEBHOOK_URL, {6      method: "POST",7      body: JSON.stringify({8        text: `✅ Tests passed in ${context.workingDirectory}`,9      }),10    });11    return {12      augment: {13        message: "Slack notification sent.",14      },15    };16  }17  return {};18};

When Claude Code runs npm test and it succeeds, this hook will automatically post to Slack and add a note to Claude Code's output.

Another example: log file writes to an audit trail:

1// .claude/hooks/audit-file-writes.js2module.exports = async (context) => {3  const { tool, args, result } = context;4  if (tool === "edit" && result.success) {5    console.log(`[AUDIT] File edited: ${args.path} by session ${context.sessionId}`);6  }7  return {};8};

This hook logs every file edit without changing Claude Code's behavior — useful for compliance, incident investigation, or understanding what the agent did.

Claude Code ships with optional built-in hooks that cover common security and quality concerns. You enable them in .claude/settings.json:

1{2  "hooks": {3    "builtIn": {4      "preventSecretExposure": true,5      "preventDangerousCommands": true,6      "requireLintPass": false,7      "requireTypeCheck": false8    }9  }10}

preventSecretExposure (default: true) — blocks commands that would write secrets to files or logs. If Claude Code tries to commit .env to Git, this hook rejects it.

preventDangerousCommands (default: true) — blocks high-risk commands without confirmation: rm -rf /, database drops, production deployments without tags. You can still run them, but Claude Code will ask explicitly.

requireLintPass (default: false) — after any file edit, run your linter (ESLint, Clippy, etc.) and reject the change if it fails. Useful for teams that want style enforcement automatic.

requireTypeCheck (default: false) — after TypeScript/Kotlin/Rust files are edited, run the type checker and reject if it fails.

You can customize thresholds in .claude/settings.json. For example:

1{2  "hooks": {3    "builtIn": {4      "preventDangerousCommands": {5        "enabled": true,6        "whitelist": ["rm src/temp/**"],7        "requireConfirmation": ["deployment", "database-alter"]8      }9    }10  }11}

You can write hooks in JavaScript (Node.js), Python, or shell (bash/zsh). Hooks are registered by path in .claude/settings.json:

1{2  "hooks": {3    "preTool": [4      { "path": ".claude/hooks/block-main.js" },5      { "path": ".claude/hooks/check-env.py", "timeout": 5000 },6      { "path": ".claude/hooks/audit.sh" }7    ],8    "postTool": [9      { "path": ".claude/hooks/notify.js" }10    ]11  }12}

JavaScript hooks run in Node.js and receive the context as a parameter. They must return a Promise resolving to a decision object:

1// .claude/hooks/my-hook.js2module.exports = async (context) => {3  // context = { tool, args, workingDirectory, sessionId, environment, result (post-tool only) }4  return {5    allowed: true,6    // or: { allowed: false, reason: "...", suggestion: "..." }7    // or: { modification: { args: { ... } } }  (pre-tool only)8    // or: { augment: { message: "..." } }  (post-tool only)9  };10};

Python hooks follow the same pattern but use standard input/output for context and response:

1#!/usr/bin/env python32import json3import sys4 5context = json.loads(sys.stdin.read())6if context['tool'] == 'bash':7    print(json.dumps({'allowed': True}))8else:9    print(json.dumps({'allowed': False, 'reason': 'tool not allowed'}))

Shell hooks receive context as environment variables and output JSON to stdout:

1#!/bin/bash2if [[ "$CLAUDE_TOOL" == "bash" ]] && [[ "$CLAUDE_COMMAND" == *"rm "* ]]; then3  echo '{"allowed": false, "reason": "Destructive commands require approval"}'4else5  echo '{"allowed": true}'6fi

Use whichever language your team is most comfortable with. JavaScript is easiest for I/O-heavy hooks (HTTP calls, database lookups), Python for data processing, shell for quick checks.

Most teams start with a few simple pre-tool hooks (block dangerous commands) and gradually add post-tool hooks for notifications and logging. Here are three real patterns:

Pattern 1: Guardrails for shared repositories — New teams often use hooks to prevent accidental commits to main, deployments without testing, or secrets in Git. One pre-tool hook per rule keeps the policy obvious and audit-able.

Pattern 2: Team notifications — Post-tool hooks automatically notify Slack, Teams, or Discord when important events happen: test pass, deployment complete, merge request created. This keeps the team in sync without Claude Code waiting for manual updates.

Pattern 3: Cost control in production — Pre-tool hooks that call a cloud provider API (AWS, GCP, Azure) and estimate the cost of a command before it runs. For expensive operations (spinning up infrastructure, running large batch jobs), the hook can ask for approval or suggest a cheaper alternative.