Otomatisasi alur kerja dengan hooks

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

Siapkan hook pertama Anda

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

​

Apa yang dapat Anda otomatisasi

• Dapatkan notifikasi ketika Claude memerlukan input
• Auto-format kode setelah edit
• Blokir edit ke file yang dilindungi
• Re-inject konteks setelah compaction
• Audit perubahan konfigurasi
• Muat ulang lingkungan ketika direktori atau file berubah
• Auto-approve prompt izin tertentu

​

Dapatkan notifikasi ketika Claude memerlukan input

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

Auto-format kode setelah edit

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

​

Blokir edit ke file yang dilindungi

#!/bin/bash
# protect-files.sh

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

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

​

Re-inject konteks setelah compaction

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

Audit perubahan konfigurasi

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

Muat ulang lingkungan ketika direktori atau file berubah

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

Auto-approve prompt izin tertentu

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

​

Cara kerja hooks

• "type": "http": POST data acara ke URL. Lihat HTTP hooks.
• "type": "mcp_tool": panggil alat pada server MCP yang sudah terhubung. Lihat MCP tool hooks.
• "type": "prompt": evaluasi LLM single-turn. Lihat Prompt-based hooks.
• "type": "agent": verifikasi multi-turn dengan akses alat. Agent hooks bersifat eksperimental dan mungkin berubah. Lihat Agent-based hooks.

​

Gabungkan hasil dari beberapa hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

Baca input dan kembalikan output

​

Hook input

{
  "session_id": "abc123",          // unique ID for this session
  "cwd": "/Users/sarah/myproject", // working directory when the event fired
  "hook_event_name": "PreToolUse", // which event triggered this hook
  "tool_name": "Bash",             // the tool Claude is about to use
  "tool_input": {                  // the arguments Claude passed to the tool
    "command": "npm test"          // for Bash, this is the shell command
  }
}

​

Hook output

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

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2 # exit 2 = block the action
fi

exit 0  # exit 0 = let it proceed

• Exit 0: tindakan berlanjut. Untuk hook UserPromptSubmit, UserPromptExpansion, dan SessionStart, apa pun yang Anda tulis ke stdout ditambahkan ke konteks Claude.
• Exit 2: tindakan diblokir. Tulis alasan ke stderr, dan Claude menerimanya sebagai umpan balik sehingga dapat menyesuaikan. Beberapa acara tidak dapat diblokir: untuk SessionStart, Setup, Notification, dan lainnya, exit 2 menampilkan stderr kepada pengguna dan eksekusi berlanjut. Lihat exit code 2 behavior per event untuk daftar lengkap.
• Kode keluar lainnya: tindakan berlanjut. Transkrip menunjukkan pemberitahuan <hook name> hook error diikuti oleh baris pertama stderr; stderr lengkap masuk ke debug log.

​

Structured JSON output

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• "allow": lewati prompt izin interaktif. Aturan deny dan ask, termasuk daftar deny yang dikelola perusahaan, masih berlaku
• "deny": batalkan panggilan alat dan kirim alasan ke Claude
• "ask": tampilkan prompt izin kepada pengguna seperti biasa

​

Filter hooks dengan matchers

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

Filter berdasarkan nama alat dan argumen dengan bidang if

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

​

Konfigurasi lokasi hook

​

Prompt-based hooks

• "ok": true: tindakan berlanjut
• "ok": false: apa yang terjadi tergantung pada peristiwa:
  • Stop dan SubagentStop: reason diberi makan kembali ke Claude sehingga terus bekerja
  • PreToolUse: panggilan alat ditolak dan reason dikembalikan ke Claude sebagai kesalahan alat, sehingga dapat menyesuaikan dan melanjutkan
  • PostToolUse, PostToolBatch, UserPromptSubmit, dan UserPromptExpansion: giliran berakhir dan reason muncul dalam obrolan sebagai baris peringatan

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

Agent-based hooks

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Keterbatasan dan troubleshooting

​

Keterbatasan

• Hook perintah berkomunikasi melalui stdout, stderr, dan kode keluar saja. Mereka tidak dapat memicu perintah / atau panggilan alat. Teks yang dikembalikan melalui additionalContext disuntikkan sebagai pengingat sistem yang Claude baca sebagai teks biasa. HTTP hooks berkomunikasi melalui badan respons sebagai gantinya.
• Timeout hook bervariasi menurut jenis. Timpa per hook dengan bidang timeout dalam detik.
  • command, http, mcp_tool: 10 menit. UserPromptSubmit menurunkan ini menjadi 30 detik.
  • prompt: 30 detik.
  • agent: 60 detik.
• Hook PostToolUse tidak dapat membatalkan tindakan karena alat sudah dieksekusi.
• Hook PermissionRequest tidak aktif dalam mode non-interaktif (-p). Gunakan hook PreToolUse untuk keputusan izin otomatis.
• Hook Stop aktif kapan pun Claude selesai merespons, bukan hanya pada penyelesaian tugas. Mereka tidak aktif pada interupsi pengguna. Kesalahan API menjalankan StopFailure sebagai gantinya.
• Ketika beberapa hook PreToolUse mengembalikan updatedInput untuk menulis ulang argumen alat, yang terakhir selesai menang. Karena hooks berjalan secara paralel, urutannya tidak deterministik. Hindari memiliki lebih dari satu hook memodifikasi input alat yang sama.

​

Hooks dan mode izin

​

Hook tidak aktif

• Jalankan /hooks dan konfirmasi hook muncul di bawah acara yang benar
• Periksa bahwa pola matcher cocok dengan nama alat dengan tepat (matcher peka huruf besar-kecil)
• Verifikasi Anda memicu jenis acara yang benar (misalnya, PreToolUse aktif sebelum eksekusi alat, PostToolUse aktif setelah)
• Jika menggunakan hook PermissionRequest dalam mode non-interaktif (-p), beralih ke PreToolUse sebagai gantinya

​

Hook error dalam output

• Skrip Anda keluar dengan kode non-nol secara tidak terduga. Uji secara manual dengan menyalurkan JSON sampel:
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• Jika Anda melihat “command not found”, gunakan jalur absolut atau ${CLAUDE_PROJECT_DIR} untuk mereferensikan skrip. Untuk menghindari quoting shell sepenuhnya, tambahkan "args": [] untuk beralih ke exec form, yang menelurkan skrip secara langsung tanpa shell
• Jika Anda melihat “jq: command not found”, instal jq atau gunakan Python/Node.js untuk parsing JSON
• Jika skrip tidak berjalan sama sekali, buat dapat dieksekusi: chmod +x ./my-hook.sh

​

/hooks menunjukkan tidak ada hooks yang dikonfigurasi

• Edit file biasanya diambil secara otomatis. Jika belum muncul setelah beberapa detik, file watcher mungkin melewatkan perubahan: mulai ulang sesi Anda untuk memaksa reload.
• Verifikasi JSON Anda valid (trailing commas dan comments tidak diizinkan)
• Konfirmkan file pengaturan berada di lokasi yang benar: .claude/settings.json untuk hook proyek, ~/.claude/settings.json untuk hook global

​

Stop hook berjalan selamanya

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

​

JSON validation failed

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

Teknik debug

​

Pelajari lebih lanjut

• Hooks reference: skema acara lengkap, format output JSON, async hooks, dan MCP tool hooks
• Security considerations: tinjau sebelum menerapkan hooks dalam lingkungan bersama atau produksi
• Bash command validator example: implementasi referensi lengkap