Claude Code Hooks Library

Save as .claude/hooks/block-dangerous-bash.sh, make it executable, and register it under PreToolUse with matcher Bash in .claude/settings.json.

#!/usr/bin/env bash
INPUT="$(cat)"
COMMAND="$(echo "$INPUT" | jq -r '.tool_input.command // ""')"

if echo "$COMMAND" | grep -Eiq '(rm\s+-rf\s+(/|~|\$HOME)|sudo\s|git\s+push\s+.*--force|curl[^|]*\|\s*(ba)?sh|wget[^|]*\|\s*(ba)?sh|DROP\s+(TABLE|DATABASE)|TRUNCATE\s+TABLE|mkfs|dd\s+if=.*of=/dev/)'; then
  jq -n --arg msg "Blocked destructive command: $COMMAND. Explain what you are trying to do and propose a safer alternative."     '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": $msg } }'
  exit 0
fi

jq -n '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow" } }'

Save as .claude/hooks/block-package-installs.sh, make it executable, and register it under PreToolUse with matcher Bash in .claude/settings.json.

#!/usr/bin/env bash
INPUT="$(cat)"
COMMAND="$(echo "$INPUT" | jq -r '.tool_input.command // ""')"

if echo "$COMMAND" | grep -Eiq '(npm install|npm i |pnpm add|yarn add|bun add|pip install|uv add|composer require|cargo add|go get)'; then
  jq -n --arg msg "Package install blocked for review: $COMMAND. Do not install packages automatically. Explain why the dependency is needed and ask for approval."     '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": $msg } }'
  exit 0
fi

jq -n '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow" } }'

Save as .claude/hooks/protect-env-files.sh, make it executable, and register it under PreToolUse with matcher Edit|Write|MultiEdit in .claude/settings.json.

#!/usr/bin/env bash
INPUT="$(cat)"
FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')"

if echo "$FILE_PATH" | grep -Eiq '(^|/)(\.env|\.env\.|secrets?/|credentials|\.pem$|\.key$|id_rsa)'; then
  jq -n --arg msg "Blocked write to protected path: $FILE_PATH. Secrets and environment files are managed manually. Ask the user instead."     '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": $msg } }'
  exit 0
fi

jq -n '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow" } }'

Save as .claude/hooks/prevent-secrets-in-code.sh, make it executable, and register it under PreToolUse with matcher Edit|Write|MultiEdit in .claude/settings.json.

#!/usr/bin/env bash
INPUT="$(cat)"
CONTENT="$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""')"

if echo "$CONTENT" | grep -Eq '(sk-[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{30,}|xox[baprs]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,})'; then
  jq -n --arg msg "Possible hardcoded secret detected in the edit. Block the write, show the offending line, and propose moving the value to an environment variable."     '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": $msg } }'
  exit 0
fi

jq -n '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow" } }'

Save as .claude/hooks/block-commit-to-main.sh, make it executable, and register it under PreToolUse with matcher Bash in .claude/settings.json.

#!/usr/bin/env bash
INPUT="$(cat)"
COMMAND="$(echo "$INPUT" | jq -r '.tool_input.command // ""')"

if echo "$COMMAND" | grep -Eq '(git\s+(commit|push)).*(main|master)|git\s+push\s+(origin\s+)?(main|master)(\s|$)'; then
  jq -n --arg msg "Direct commits/pushes to main are blocked. Create a feature branch, commit there, and open a pull request."     '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": $msg } }'
  exit 0
fi

jq -n '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow" } }'

Save as .claude/hooks/typecheck-after-edit.sh, make it executable, and register it under PostToolUse with matcher Edit|Write|MultiEdit in .claude/settings.json.

#!/usr/bin/env bash
INPUT="$(cat)"
FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')"

# Only care about TypeScript files
echo "$FILE_PATH" | grep -Eq '\.(ts|tsx)$' || { echo '{}'; exit 0; }

# Only run when the project has a typecheck script
[ -f package.json ] && jq -e '.scripts["typecheck"]' package.json >/dev/null 2>&1 || { echo '{}'; exit 0; }

if ! npm run typecheck >/tmp/claude-typecheck.log 2>&1; then
  REASON="Typecheck failed after editing $FILE_PATH. Fix the errors before continuing:\n$(tail -n 20 /tmp/claude-typecheck.log)"
  jq -n --arg msg "$REASON" '{ "decision": "block", "reason": $msg }'
  exit 0
fi

jq -n '{}'

Save as .claude/hooks/lint-after-edit.sh, make it executable, and register it under PostToolUse with matcher Edit|Write|MultiEdit in .claude/settings.json.

#!/usr/bin/env bash
INPUT="$(cat)"
FILE_PATH="$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')"

echo "$FILE_PATH" | grep -Eq '\.(js|jsx|ts|tsx)$' || { echo '{}'; exit 0; }

[ -f package.json ] && jq -e '.scripts["lint"]' package.json >/dev/null 2>&1 || { echo '{}'; exit 0; }

if ! npm run lint >/tmp/claude-lint.log 2>&1; then
  REASON="Lint failed after editing $FILE_PATH. Fix the reported issues before continuing:\n$(tail -n 20 /tmp/claude-lint.log)"
  jq -n --arg msg "$REASON" '{ "decision": "block", "reason": $msg }'
  exit 0
fi

jq -n '{}'

Save as .claude/hooks/session-start-context.sh, make it executable, and register it under SessionStart in .claude/settings.json.

#!/usr/bin/env bash
# Runs on SessionStart (startup, resume, clear). Injects context into the session.
REMINDER="You operate under The Learner Brain methodology.
- Follow the rules in .claude/ and CLAUDE.md at all times.
- When you detect repetition, manual labor, or a preference correction, propose a Brain Upgrade (Observation / Suggestion / Benefit / Action) and wait for approval.
- Never store memory without explicit approval."

jq -n --arg ctx "$REMINDER" \
  '{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": $ctx } }'

Save as .claude/hooks/upgrade-proposal-reminder.sh, make it executable, and register it under UserPromptSubmit in .claude/settings.json.

#!/usr/bin/env bash
INPUT="$(cat)"
PROMPT="$(echo "$INPUT" | jq -r '.prompt // ""')"

if echo "$PROMPT" | grep -Eiq '(again|as i (said|told you)|like last time|stop doing|stop using|every time|i keep (saying|telling)|for the (third|3rd|fourth|4th) time|you keep)'; then
  CONTEXT="Correction language detected in the user's prompt. Under the Learner Brain meta-learning rule: if this is a repeated correction or preference, propose a Brain Upgrade (Observation / Suggestion / Benefit / Action: Shall I create this rule?) before continuing the task."
  jq -n --arg ctx "$CONTEXT" \
    '{ "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": $ctx } }'
  exit 0
fi

jq -n '{}'

Save as .claude/hooks/prompt-friction-log.sh, make it executable, and register it under UserPromptSubmit in .claude/settings.json.

#!/usr/bin/env bash
INPUT="$(cat)"
PROMPT="$(echo "$INPUT" | jq -r '.prompt // ""')"
LOG_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/friction-log"
mkdir -p "$LOG_DIR"
echo "$PROMPT" >> "$LOG_DIR/$(date +%F).log"

jq -n '{}'

Save as .claude/hooks/run-tests-before-stop.sh, make it executable, and register it under Stop in .claude/settings.json.

#!/usr/bin/env bash
# Stop hook: block the agent from finishing while tests fail.
[ -f package.json ] && jq -e '.scripts["test"]' package.json >/dev/null 2>&1 || { echo '{}'; exit 0; }

if ! npm test >/tmp/claude-tests.log 2>&1; then
  REASON="Tests failed — you are not done. Fix the failing tests before stopping:\n$(tail -n 30 /tmp/claude-tests.log)"
  jq -n --arg msg "$REASON" '{ "decision": "block", "reason": $msg }'
  exit 0
fi

jq -n '{}'

Save as .claude/hooks/notify-on-stop.sh, make it executable, and register it under Stop in .claude/settings.json.

#!/usr/bin/env bash
if command -v osascript >/dev/null 2>&1; then
  osascript -e 'display notification "Claude Code task completed — review the diff before committing" with title "Claude Code"'
elif command -v notify-send >/dev/null 2>&1; then
  notify-send "Claude Code" "Task completed — review the diff before committing"
fi

jq -n '{}'

Save as .claude/hooks/subagent-stop-summary.sh, make it executable, and register it under SubagentStop in .claude/settings.json.

#!/usr/bin/env bash
CONTEXT="A subagent just finished. Treat its output as a distilled report: cite it, do not re-run its work, and keep the main context lean."
jq -n --arg ctx "$CONTEXT" \
  '{ "hookSpecificOutput": { "hookEventName": "SubagentStop", "additionalContext": $ctx } }'

Save as .claude/hooks/todo-discipline-check.sh, make it executable, and register it under UserPromptSubmit in .claude/settings.json.

#!/usr/bin/env bash
INPUT="$(cat)"
PROMPT="$(echo "$INPUT" | jq -r '.prompt // ""')"

if echo "$PROMPT" | grep -Eiq '(then|after that|first .* (then|and then)|step by step|migrate|refactor|across (all|every)|multiple files)'; then
  CONTEXT="This looks like a multi-step task. Before writing code: state a short plan (or use TodoWrite), confirm the order of operations, and flag risky steps."
  jq -n --arg ctx "$CONTEXT" \
    '{ "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": $ctx } }'
  exit 0
fi

jq -n '{}'