Hooks: گردش‌کار سفارشی خود را بسازید

Hooks در Claude Code چیست؟

Hooks سیستم رویداد Claude Code است که به شما امکان می‌دهد پیش و پس از فراخوانی‌های ابزار، اسکریپت‌های shell سفارشی اجرا کنید. linterها را پس از ذخیره فایل به‌طور خودکار اجرا کنید، آزمون‌ها را پیش از commit اجرا کنید، یا هنگام دسترسی به فایل‌های حساس هشدار ایجاد کنید — همه بدون دخالت دستی.

پیکربندی سه سطح تودرتو دارد: رویداد، یک matcher که ابزارها را فیلتر می‌کند، و اسکریپت شما درون آرایه داخلی hooks. اسکریپت JSON این رویداد را از stdin می‌خواند و با کدهای خروج پاسخ می‌دهد: 0 یعنی مخالفتی نیست، 2 در رویدادهایی که اجازه می‌دهند فراخوانی را مسدود می‌کند. برای چهار رویداد زیر، یک هوک از نوع command در مهلت پیش‌فرض 600 ثانیه‌ای خود لغو می‌شود؛ این چهار مورد رایج‌اند، نه فهرست کامل رسمی (بررسی‌شده در 2026-09-22).

سه نمونه عملی خودکارسازی

سه مورد زیر یک ساختار مشترک دارند: رویداد را انتخاب کنید، آن را با matcher محدود کنید و اسکریپت را در آرایه داخلی hooks قرار دهید. قطعه‌کدها فقط قصد را نشان می‌دهند؛ بنابراین مرجع رسمی را منبع نام فیلدها و تودرتویی بدانید و هر چیزی را که اسکریپت‌تان باید بررسی کند از همان JSON روی stdin بخوانید.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "command": "if echo \"$TOOL_INPUT\" | grep -q 'git commit'; then npm run format; fi"
    }]
  }
}

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "command": "if echo \"$TOOL_INPUT\" | grep -q 'pytest\\|npm test'; then notify-send 'Tests completed'; fi"
    }]
  }
}

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "command": "if echo \"$TOOL_INPUT\" | grep -qE '\\.env|credentials|secrets'; then exit 2; fi"
    }]
  }
}

پیکربندی settings.json

Hooks خود را در .claude/settings.json تعریف کنید

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "~/scripts/pre-bash-hook.sh"
      },
      {
        "matcher": "Edit|Write",
        "command": "~/scripts/protect-sensitive-files.sh"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "command": "~/scripts/post-bash-hook.sh"
      }
    ],
    "Notification": [
      {
        "command": "~/scripts/send-notification.sh"
      }
    ],
    "Stop": [
      {
        "command": "~/scripts/on-stop.sh"
      }
    ]
  }
}

پرسش‌های متداول