Claude Code Hooks: Tự Động Hóa Workflow Từ A-Z (2026)

Claude Code đã mang về $2,5 tỷ USD doanh thu hàng năm cho Anthropic (Anthropic Series G, tháng 2/2026). Hàng triệu developer đang dùng nó mỗi ngày. Nhưng bạn có bao giờ gặp tình huống này: Claude Code chạy xong một lệnh nguy hiểm trước khi bạn kịp phản ứng? Hoặc bạn phải tự format code thủ công sau mỗi lần Claude sửa file?

Vấn đề nằm ở chỗ: CLAUDE.md chỉ là “gợi ý” — Claude Code có thể nghe hoặc không. Hooks thì khác. Claude Code Hooks là shell commands tự động chạy tại các điểm cụ thể trong lifecycle, và chúng bắt buộc, deterministic, không bao giờ bị bỏ qua.

Mình dùng hooks hàng ngày cho blog ongboit.com — từ auto-format code sau khi Claude viết, đến notification khi task hoàn thành, đến chặn các lệnh nguy hiểm. Bài viết này chia sẻ mọi thứ mình đã học được.

Claude Code Hooks Là Gì?

Claude Code Hooks là shell commands tự động chạy tại các điểm cụ thể trong lifecycle của Claude Code, được giới thiệu chính thức trong tài liệu Anthropic. Với 24 hook events và 4 handler types, hooks cung cấp automation deterministic — khác hoàn toàn với CLAUDE.md chỉ là gợi ý. Theo Pragmatic Engineer Survey 2026 (n=906), 46% developer chọn Claude Code là AI coding tool yêu thích nhất.

Nghe trừu tượng quá? Nghĩ thế này cho dễ: Hooks giống như “camera giám sát” kết hợp “bảo vệ” cho workflow của bạn. Camera giám sát (non-blocking hooks) ghi lại mọi thứ đang xảy ra — log commands, track file changes. Bảo vệ (blocking hooks) có quyền chặn lại bất kỳ hành động nào không hợp lệ — như lệnh rm -rf hay ghi vào file .env.

Điểm khác biệt cốt lõi giữa Hooks và CLAUDE.md:

Cấu trúc nên nhớ: CLAUDE.md = “nên làm gì”, Hooks = “phải làm gì”, Skills = “làm như thế nào”. Ba thành phần này bổ sung cho nhau, không thay thế nhau.

24 Hook Events: Có Những Loại Nào?

Claude Code cung cấp 24 hook events chia thành 4 nhóm chính, theo tài liệu chính thức Anthropic. Trong số đó, 12 events có khả năng blocking (chặn hành động), 12 events là non-blocking (chỉ ghi nhận). Theo DataCamp (2025), việc hiểu rõ từng event là bước đầu tiên để xây dựng automation hiệu quả.

Bạn có biết tại sao các event này quan trọng đến vậy không? Vì mỗi event là một “điểm chèn” — nơi bạn có thể tự động hóa bất kỳ logic nào mà không cần Claude Code phải hiểu hay quyết định. OS chạy trực tiếp, không qua LLM.

Lifecycle Events

Tool Events

Agent & Task Events

System Events

Trong 24 events, PreToolUse và PostToolUse là hai event bạn sẽ dùng nhiều nhất, có lẽ 80% use case. PreToolUse để chặn lệnh nguy hiểm, PostToolUse để auto-format hay auto-test. Các event WorktreeCreate và WorktreeRemove hữu ích khi bạn làm việc với git worktree để chạy nhiều task song song. Nếu bạn mới bắt đầu, tập trung vào PreToolUse và PostToolUse trước.

4 Loại Handler: Command, HTTP, Prompt, Agent Khác Nhau Thế Nào?

Mỗi hook cần một handler để thực thi — và Claude Code hỗ trợ 4 loại handler khác nhau. Theo Hooks Guide chính thức, command là handler phổ biến nhất, chiếm đa số các use case thực tế. Theo GitButler (2025), hooks đã thay đổi cách developer tương tác với AI coding tools.

Vậy khi nào dùng loại nào? Cũng không phức tạp lắm đâu.

Command Handler — Phổ Biến Nhất

Command handler chạy shell commands trực tiếp trên máy của bạn. Đây là loại đơn giản nhất và phù hợp với 90% trường hợp. Bạn chỉ cần viết một script bash hoặc python, rồi trỏ hook đến nó.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

Khi nào dùng: Auto-format code, chạy tests, log activity, notification, chặn lệnh nguy hiểm. Bất cứ gì chạy được bằng shell command.

HTTP Handler — Gọi Remote Services

HTTP handler gửi request đến một URL. Hữu ích khi bạn muốn integrate với external services như Slack, Discord, hoặc custom webhook.

{
  "type": "http",
  "url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": "{\"text\": \"Claude Code finished a task!\"}"
}

Khi nào dùng: Slack/Discord notifications, webhook integrations, remote logging, API calls đến CI/CD systems. Nếu bạn muốn tích hợp sâu hơn với CI/CD, đọc bài Claude Code GitHub Actions để chạy Claude Code trực tiếp trong pipeline.

Prompt Handler — Đánh Giá Bằng LLM

Prompt handler gửi kết quả đến LLM để đánh giá. Khác với command handler chạy code trực tiếp, prompt handler dùng AI để phân tích output và quyết định tiếp theo.

{
  "type": "prompt",
  "prompt": "Review this code change for security issues. If you find any, output BLOCK and explain why. If safe, output PASS."
}

Khi nào dùng: Code review tự động, security analysis, quality gate cho output phức tạp mà regex không xử lý được.

Agent Handler — Xác Minh Phức Tạp

Agent handler là loại mạnh nhất — chạy một agent riêng để thực hiện verification phức tạp. Nó có thể đọc nhiều file, chạy nhiều lệnh, và đưa ra quyết định tổng hợp.

{
  "type": "agent",
  "prompt": "Verify that the changes maintain backward compatibility. Check all public API signatures, run type checks, and validate test coverage is above 80%."
}

Khi nào dùng: Verification phức tạp cần nhiều bước, backward compatibility checks, comprehensive code review. Lưu ý: agent handler tốn nhiều tokens hơn các loại khác.

Cách Cấu Hình Hooks Trong settings.json Như Thế Nào?

Claude Code Hooks được cấu hình trong file settings.json ở 3 cấp độ khác nhau, theo tài liệu Anthropic. Việc hiểu rõ thứ tự ưu tiên giữa các cấp là điều kiện tiên quyết để tránh xung đột. Theo GitHub claude-code-hooks-mastery (2025), hầu hết lỗi hooks đều xuất phát từ sai cấu hình.

3 Cấp Độ Cấu Hình

Mỗi cấp độ phục vụ một mục đích khác nhau. Bạn cần hiểu rõ để biết đặt hooks ở đâu cho đúng.

Thứ tự ưu tiên: Local > Project > User. Hooks từ cấp local sẽ override hooks cùng event từ cấp project và user.

Cấu Trúc File settings.json

Cấu trúc cơ bản của một hook trong settings.json gồm 3 phần: event name, matcher (regex), và danh sách handlers. Đây là một ví dụ đầy đủ:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/block-dangerous.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' '$CLAUDE_NOTIFICATION'"
          }
        ]
      }
    ]
  }
}

Matcher — Regex Pattern Matching

Matcher quyết định hook chạy với tool nào. Nó sử dụng regex pattern. Một số ví dụ:

• "Bash" — Chỉ chạy khi Claude dùng Bash tool
• "Write|Edit" — Chạy khi Write hoặc Edit tool
• ".*" — Chạy với tất cả tools
• "" (empty) — Tương tự .*, match tất cả
• "Read" — Chỉ khi Read tool

Một điều quan trọng: matcher chỉ có ý nghĩa với tool-related events như PreToolUse, PostToolUse, PermissionRequest. Với các event khác như SessionStart hay Notification, bạn có thể để matcher là empty string.

Environment Variables

Khi hook chạy, Claude Code tự động truyền các environment variables hữu ích:

• CLAUDE_PROJECT_DIR — Thư mục gốc của project
• CLAUDE_PLUGIN_ROOT — Thư mục gốc của plugin (nếu dùng plugin)
• CLAUDE_PLUGIN_DATA — Thư mục data của plugin
• CLAUDE_ENV_FILE — Đường dẫn đến file environment

Ngoài ra, stdin của hook nhận được JSON object chứa thông tin context cụ thể cho từng event. Ví dụ, PreToolUse nhận tool name và input parameters.

7 Hook Recipes Thực Tế (Copy-Paste)

Lý thuyết đã đủ. Giờ là lúc thực hành. Dưới đây là 7 recipes mình đang dùng hàng ngày trên ongboit.com và các dự án khác. Theo claude-code-hooks-mastery trên GitHub (2025, 500+ stars), đây là những pattern được cộng đồng sử dụng nhiều nhất.

Sau 3 tháng dùng hooks, mình giảm được khoảng 40% thời gian format code thủ công và gần như loại bỏ hoàn toàn các sự cố “lỡ delete file nhầm”. Còn bạn thì sao — đã bao giờ Claude Code xóa nhầm file chưa?

1. Auto-format Code Sau Khi Claude Viết File

Đây là hook mình dùng nhiều nhất. Mỗi khi Claude Code tạo hoặc sửa file, Prettier tự động chạy để format. Không cần nhớ, không cần làm thủ công.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$(echo $CLAUDE_TOOL_INPUT | jq -r '.file_path // .path // empty')\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Giải thích: Hook bắt event PostToolUse khi matcher match Write|Edit. Sau khi Claude viết file, Prettier tự động format. || true đảm bảo hook không fail nếu Prettier gặp lỗi (ví dụ file không phải JS/TS).

2. Chặn Lệnh Nguy Hiểm (rm -rf, DROP TABLE)

Đây là hook bảo vệ — chặn các lệnh có thể gây hại trước khi Claude Code thực thi. Sử dụng exit code 2 để block.

#!/bin/bash
# File: ~/.claude/hooks/block-dangerous.sh

# Đọc tool input từ stdin
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.command // empty')

# Danh sách lệnh bị cấm
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "DROP TABLE"
  "DROP DATABASE"
  "DELETE FROM.*WHERE 1"
  "mkfs\."
  "dd if=/dev/zero"
  "> /dev/sda"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qiE "$pattern"; then
    echo "BLOCKED: Lệnh nguy hiểm '$pattern' bị chặn bởi hook" >&2
    exit 2
  fi
done

exit 0

Và cấu hình trong settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ]
  }
}

Quan trọng: Khi exit code là 2, stderr được gửi lại cho Claude Code như feedback. Claude sẽ thấy message “BLOCKED: …” và hiểu rằng nó cần tìm cách khác.

3. Auto-run Tests Sau Mỗi Edit

Mỗi khi Claude sửa file code, tests tự động chạy. Nếu test fail, Claude nhận được kết quả và có thể tự fix.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && npm test -- --bail 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}

Tip: Dùng --bail để dừng ngay khi gặp test fail đầu tiên — tiết kiệm thời gian. tail -20 chỉ lấy 20 dòng cuối cùng để tránh output quá dài.

4. Notification Khi Claude Xong Việc

Khi Claude Code hoàn thành task dài, bạn nhận notification trên desktop. Cực kỳ hữu ích khi bạn đang làm việc khác.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code đã xong việc!', 'Notification')\""
          }
        ]
      }
    ]
  }
}

Linux/macOS: Thay command bằng notify-send 'Claude Code' 'Task completed!' (Linux) hoặc osascript -e 'display notification "Task completed!" with title "Claude Code"' (macOS).

5. Environment Setup Khi Bắt Đầu Session

Tự động thiết lập environment variables và kiểm tra dependencies khi bắt đầu làm việc.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cd $CLAUDE_PROJECT_DIR && [ -f .env ] && export $(cat .env | xargs) && echo 'Environment loaded' || echo 'No .env file found'"
          }
        ]
      }
    ]
  }
}

6. Log Tất Cả Bash Commands

Ghi lại mọi lệnh Bash mà Claude Code thực thi. Hữu ích để audit và debug sau này.

#!/bin/bash
# File: ~/.claude/hooks/log-commands.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.command // empty')
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
LOG_FILE="$CLAUDE_PROJECT_DIR/.claude/command-log.txt"

mkdir -p "$(dirname $LOG_FILE)"
echo "[$TIMESTAMP] $COMMAND" >> "$LOG_FILE"

exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/log-commands.sh"
          }
        ]
      }
    ]
  }
}

7. Block Write Vào File Nhạy Cảm (.env, credentials)

Chặn Claude Code ghi vào các file nhạy cảm như .env, credentials.json, hoặc SSH keys. An toàn là trên hết. Kết hợp hook này với Permission Modes để có lớp bảo mật kép, vừa kiểm soát quyền ở cấp độ session, vừa chặn file cụ thể bằng hook.

#!/bin/bash
# File: ~/.claude/hooks/protect-sensitive.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // .path // empty')

# Danh sách file/pattern bị bảo vệ
PROTECTED_PATTERNS=(
  "\.env$"
  "\.env\.local$"
  "credentials"
  "secret"
  "\.pem$"
  "id_rsa"
  "\.ssh/"
)

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if echo "$FILE_PATH" | grep -qiE "$pattern"; then
    echo "BLOCKED: Không được ghi vào file nhạy cảm '$FILE_PATH'" >&2
    exit 2
  fi
done

exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/protect-sensitive.sh"
          }
        ]
      }
    ]
  }
}

Exit Codes — Cách Hooks Giao Tiếp Với Claude Code?

Exit codes là “ngôn ngữ” mà hooks dùng để nói chuyện với Claude Code. Hệ thống này đơn giản nhưng cực kỳ quan trọng — hiểu sai là hooks sẽ không hoạt động đúng. Theo tài liệu Anthropic, chỉ có 3 loại exit code có ý nghĩa. Với DataCamp (2025), đây là khái niệm cơ bản nhất cần nắm trước khi viết hook.

Điểm then chốt: Exit code 2 chỉ có tác dụng với blocking events. Nếu bạn return exit 2 từ một non-blocking event như PostToolUse, nó sẽ bị bỏ qua — hành động đã xảy ra rồi, không thể “chữa” được nữa.

Và lưu ý: khi exit code là 0, nội dung stdout của hook được truyền lại cho Claude Code như context bổ sung. Điều này rất hữu ích — bạn có thể inject thông tin vào conversation từ hook.

Hooks Trong Skills — Frontmatter YAML

Ngoài cấu hình trong settings.json, hooks còn có thể được định nghĩa trong YAML frontmatter của Skills. Theo Anthropic Hooks Guide, đây là cách tạo portable hooks gắn liền với một skill cụ thể. Cách này đặc biệt hữu ích khi bạn muốn chia sẻ skill kèm hooks cho team.

Tại sao lại cần định nghĩa hooks trong skills? Vì đôi khi một hook chỉ có ý nghĩa trong context của một skill cụ thể. Ví dụ, skill “blog-write” cần hook auto-format HTML, nhưng skill “debug” thì không.

---
name: blog-write
description: Write a blog post following ongboit.com standards
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      type: command
      command: "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
  PreToolUse:
    - matcher: "Write"
      type: command
      command: "bash ~/.claude/hooks/protect-sensitive.sh"
---

## Blog Writing Instructions

Write Vietnamese blog posts following GEO rules...
(phần instructions còn lại)

Ưu điểm của hooks trong skills:

• Portable: Hook đi cùng với skill — chia sẻ skill thì chia sẻ luôn hooks
• Scoped: Hook chỉ chạy khi skill đang active, không ảnh hưởng global
• Override: Hooks từ skill có thể override hooks từ settings.json

Mình thích dùng hooks trong skills hơn settings.json cho các task cụ thể. Ví dụ, skill “blog-write” có hook auto-format HTML, còn skill “code-review” thì không cần. Cách này giữ settings.json sạch sẽ và dễ quản lý hơn.

Debugging Hooks — Khi Nào Hooks Không Chạy?

Hooks không chạy là một trong những vấn đề thường gặp nhất, theo kinh nghiệm của mình và cộng đồng trên GitHub. Với 24 events và nhiều cấp cấu hình, việc debug đôi khi khá khó. Theo DataCamp (2025), đa số lỗi hooks nằm ở 5 nguyên nhân phổ biến.

Lệnh /hooks — Kiểm Tra Nhanh

Cách nhanh nhất để kiểm tra hooks đã cấu hình đúng chưa: gõ /hooks trong Claude Code. Lệnh này hiển thị tất cả hooks đang active, bao gồm cả nguồn gốc (user, project, local, skill).

# Trong Claude Code terminal, gõ:
/hooks

# Output sẽ hiển thị:
# Active hooks:
#   PreToolUse (Bash): command - bash ~/.claude/hooks/block-dangerous.sh [user]
#   PostToolUse (Write|Edit): command - npx prettier --write ... [project]
#   Notification (): command - notify-send ... [local]

5 Nguyên Nhân Phổ Biến Và Cách Khắc Phục

Vô Hiệu Hóa Hooks Tạm Thời

Đôi khi bạn cần tắt hooks để debug. Thêm flag này vào settings.json:

{
  "disableAllHooks": true
}

Lưu ý: Nhớ tắt flag này sau khi debug xong. Dễ quên lắm — mình đã từng để nguyên cả tuần mà không biết.

Câu Hỏi Thường Gặp (FAQ)

Claude Code Hooks là gì?

Claude Code Hooks là shell commands, HTTP requests, prompt evaluations, hoặc agent handlers tự động chạy tại các điểm cụ thể trong lifecycle của Claude Code. Khác với CLAUDE.md chỉ là gợi ý, hooks được OS thực thi trực tiếp — đảm bảo 100% deterministic. Có 24 hook events và 4 handler types, cấu hình trong settings.json.

Hooks khác gì với CLAUDE.md?

CLAUDE.md là “gợi ý” — LLM đọc và có thể bỏ qua. Hooks là “bắt buộc” — OS chạy trực tiếp, không qua LLM. CLAUDE.md phù hợp cho coding conventions và style guides. Hooks phù hợp cho automation như auto-format, security gates, và logging. Cả hai bổ sung cho nhau, không thay thế nhau.

Hooks có làm chậm Claude Code không?

Blocking hooks (như PreToolUse) có thể làm chậm vì Claude Code phải đợi kết quả. Non-blocking hooks chạy song song nên không ảnh hưởng hiệu năng. Để giữ hooks nhanh, giữ script dưới 10 giây và tránh các operations nặng như network calls trong blocking hooks.

Exit code 2 hoạt động như thế nào?

Khi hook return exit code 2, hành động bị chặn và nội dung stderr được gửi lại cho Claude Code như feedback. Claude sẽ thấy message lỗi và có thể tìm cách khác. Exit code 2 chỉ có tác dụng với blocking events như PreToolUse, PermissionRequest, Stop. Với non-blocking events, exit code 2 bị bỏ qua.

Làm sao biết hooks đang chạy?

Gõ /hooks trong Claude Code để xem tất cả hooks đang active và nguồn gốc của chúng (user, project, local, skill). Ngoài ra, bạn có thể thêm hook logging — ghi log mỗi khi hook chạy để theo dõi. Nếu hooks không hiển thị trong /hooks, kiểm tra JSON syntax và đường dẫn file.

Có thể dùng Python thay cho Bash không?

Có. Command handler chạy bất kỳ lệnh shell nào, bao gồm python3 script.py. Python hữu ích cho logic phức tạp hơn — xử lý JSON, regex phức tạp, hoặc gọi API. Chỉ cần đảm bảo script return đúng exit code: 0 (ok), 2 (block), hoặc khác (error).

Hooks có hoạt động trên Windows không?

Có, nhưng cần lưu ý. Trên Windows, Claude Code chạy trong bash (Git Bash hoặc WSL). Các script .sh chạy bình thường qua bash. Với PowerShell commands, dùng powershell -Command "...". Một số Unix utilities như notify-send không có sẵn trên Windows — cần thay bằng PowerShell tương đương.

Nên bắt đầu với hook nào trước?

Bắt đầu với 2 hooks: (1) PreToolUse + Bash matcher để chặn lệnh nguy hiểm, và (2) PostToolUse + Write|Edit matcher để auto-format. Hai hooks này cover 80% use case và cho bạn làm quen với hệ thống. Sau đó mở rộng dần sang notification, logging, và các event khác.

Kết Luận

Claude Code Hooks là tính năng giúp bạn chuyển từ “hy vọng Claude Code làm đúng” sang “đảm bảo Claude Code làm đúng”. Với 24 hook events và 4 handler types, bạn có thể tự động hóa gần như mọi khía cạnh của workflow — từ format code, chặn lệnh nguy hiểm, đến notification khi task hoàn thành.

Sau 3 tháng sử dụng, mình không thể quay lại làm việc không có hooks. Nó giống như làm việc không có Git vậy — về lý thuyết thì được, nhưng thực tế thì không ai muốn.

Bắt đầu đơn giản: thêm một PreToolUse hook để chặn lệnh nguy hiểm, và một PostToolUse hook để auto-format. Hai hooks này mất chưa đến 5 phút để setup nhưng tiết kiệm hàng giờ mỗi tuần. Từ đó, mở rộng dần theo nhu cầu của bạn.

Nếu bạn chưa quen với Claude Code là gì, đọc bài giới thiệu trước. Nếu đã sẵn sàng, Skills là bước tiếp theo để xây dựng workflow hoàn chỉnh, kết hợp với hooks để có hệ thống automation đầy đủ. Tham khảo roadmap đầy đủ để chọn learning path phù hợp.