moai-cc-hooks

Configuring Claude Code Hooks System. Design, implement, and manage PreToolUse/PostToolUse/SessionStart/Notification/Stop hooks. Use when enforcing safety checks, auto-formatting, running linters, or triggering automated workflows based on development events.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill facilitates the design, implementation, and management of the Claude Code Hooks System. It allows developers to automate critical workflows by triggering scripts during lifecycle events such as PreToolUse and PostToolUse. By integrating these hooks, users can enforce security guardrails, automate code formatting and linting, and manage session context effectively, significantly enhancing both development safety and productivity.

Use Cases

  • Automated Security Guardrails: Implement a 'Dangerous Command Blocker' using PreToolUse hooks to intercept and prevent the execution of destructive terminal commands like 'rm -rf' or unauthorized system modifications.
  • Continuous Code Quality: Automatically trigger linters and formatters (e.g., Prettier, Black, or Gofmt) immediately after file edits to maintain consistent coding standards across the project.
  • Session Context Seeding: Use SessionStart hooks to automatically generate and display project status cards, tech stack summaries, or recent task updates whenever a new Claude Code session begins.
  • Permission and Environment Management: Create hooks to save and restore file permissions or environment states before and after tool execution to ensure system stability during automated refactoring.
namemoai-cc-hooks
description"Configuring Claude Code Hooks System. Design, implement, and manage PreToolUse/PostToolUse/SessionStart/Notification/Stop hooks. Use when enforcing safety checks, auto-formatting, running linters, or triggering automated workflows based on development events."
allowed-tools"Read, Write, Edit, Glob, Bash"

Skill Metadata

Field Value
Version 1.0.0
Tier Ops
Auto-load When configuring hook system

What It Does

Hook system 설정 및 관리를 위한 전체 가이드를 제공합니다. PreToolUse, PostToolUse, SessionStart 등 다양한 hook type의 설계와 구현 방법을 다룹니다.

When to Use

  • Safety check나 validation hook을 추가할 때
  • Auto-formatting이나 linting을 자동화할 때
  • Session lifecycle event에 응답하는 로직을 작성할 때
  • 개발 이벤트 기반 workflow를 트리거할 때

Configuring Claude Code Hooks System

Hooks are lightweight (<100ms) automated scripts triggered by Claude Code lifecycle events. They enforce guardrails, run quality checks, and seed context without blocking user workflow.

Hook Types & Events

Hook Type Trigger Event Execution Time Use Cases
PreToolUse Before tool execution (Read, Edit, Bash, etc.) <100ms Command validation, permission checks, safety gates
PostToolUse After tool execution succeeds <100ms Auto-formatting, linting, permission restoration
SessionStart Session initialization <500ms Project summary, context seeding, status card
Notification User notification event N/A macOS notifications, alerts, wait status
Stop Session termination N/A Cleanup, final checks, task summary

Hook Configuration in settings.json

High-Freedom Approach: Events-Driven Hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/pre-bash-validator.js"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/pre-edit-guard.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/post-edit-lint.sh"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/session-status-card.js"
          }
        ]
      }
    ]
  }
}

Medium-Freedom: Hook Patterns

Pattern 1: Pre-Command Validation

#!/bin/bash
# pre-bash-validator.sh: Block dangerous patterns

FORBIDDEN_PATTERNS=(
  "rm -rf /"
  "sudo rm"
  "chmod 777 /"
  "eval \$(curl"
)

COMMAND="$1"
for pattern in "${FORBIDDEN_PATTERNS[@]}"; do
  if [[ "$COMMAND" =~ $pattern ]]; then
    echo "🔴 Blocked: $pattern detected" >&2
    exit 2  # Block execution
  fi
done

exit 0  # Allow execution

Pattern 2: Post-Edit Auto-Formatting

#!/bin/bash
# post-edit-format.sh: Auto-format after edits

FILE="$1"
EXT="${FILE##*.}"

case "$EXT" in
  js|ts)
    npx prettier --write "$FILE" 2>/dev/null
    ;;
  py)
    python3 -m black "$FILE" 2>/dev/null
    ;;
  go)
    gofmt -w "$FILE" 2>/dev/null
    ;;
esac

exit 0

Pattern 3: SessionStart Status Card

#!/bin/bash
# session-status-card.sh: Show project status

echo "🚀 Claude Code Session Started"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

if [ -f ".moai/config.json" ]; then
  PROJECT=$(jq -r '.name' .moai/config.json 2>/dev/null || echo "Unknown")
  echo "📦 Project: $PROJECT"
  echo "🏗️  Framework: $(jq -r '.tech_stack' .moai/config.json 2>/dev/null || echo "Auto-detect")"
fi

echo "📋 Recent SPECS:"
ls .moai/specs/ 2>/dev/null | head -3 | sed 's/^/  ✓ /'

echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

Low-Freedom: Security-Focused Hook Scripts

Permission Preservation Hook

#!/bin/bash
set -euo pipefail
# preserve-permissions.sh: Save/restore file permissions

HOOK_TYPE="${1:-pre}"  # 'pre' or 'post'
FILE="${2:-.}"

PERMS_FILE="/tmp/perms_${FILE//\//_}.txt"

if [[ "$HOOK_TYPE" == "pre" ]]; then
  stat -c "%a %u:%g" "$FILE" > "$PERMS_FILE" 2>/dev/null || true
  exit 0
elif [[ "$HOOK_TYPE" == "post" ]]; then
  if [[ -f "$PERMS_FILE" ]]; then
    SAVED_PERMS=$(cat "$PERMS_FILE")
    chmod ${SAVED_PERMS%% *} "$FILE" 2>/dev/null || true
    rm "$PERMS_FILE"
  fi
  exit 0
fi

Dangerous Command Blocker

#!/usr/bin/env python3
import json
import sys
import re

BLOCKED_PATTERNS = [
    (r"rm\s+-rf\s+/", "Blocking rm -rf /"),
    (r"sudo\s+rm", "Blocking sudo rm without confirmation"),
    (r">\s*/etc/\w+", "Blocking writes to system files"),
    (r"curl.*\|\s*bash", "Blocking curl | bash (code injection risk)"),
]

try:
    data = json.load(sys.stdin)
    command = data.get("tool_input", {}).get("command", "")

    for pattern, msg in BLOCKED_PATTERNS:
        if re.search(pattern, command):
            print(f"🔴 BLOCKED: {msg}", file=sys.stderr)
            sys.exit(2)  # Block

    sys.exit(0)  # Allow
except Exception as e:
    print(f"Hook error: {e}", file=sys.stderr)
    sys.exit(0)  # Allow on error (fail open)

Hook Exit Codes

Code Meaning Behavior
0 Success Tool proceeds normally
1 Warning + Stderr Warning logged, tool proceeds
2 Blocked + Error Tool execution blocked

Best Practices

✅ DO:

  • Keep hook scripts < 100ms execution time
  • Use specific matchers (not wildcard * unless necessary)
  • Log errors clearly to stderr
  • Test hooks before deploying to team

❌ DON'T:

  • Make network calls in PreToolUse hooks
  • Block common operations (use warnings instead)
  • Write to user files from hooks
  • Create complex logic (delegate to sub-agents)

Hook Validation Checklist

  • All scripts have proper shebang (#!/bin/bash or #!/usr/bin/env python3)
  • Scripts are executable: chmod +x hook.sh
  • Exit codes are correct (0, 1, or 2)
  • Paths are absolute (not relative)
  • Tested for < 100ms latency
  • Error messages are user-friendly
  • No hardcoded secrets or credentials

Reference: Context7 Claude Code Hooks documentation Version: 1.0.0