HOOKS-README

contains all the details, scripts, and instructions for the hooks

Hook Events Overview - Official 15 Hooks

Claude Code provides several hook events that run at different points in the workflow:

SessionStart: Runs when Claude Code starts a new session or resumes one
SessionEnd: Runs when a Claude Code session ends
UserPromptSubmit: Runs when the user submits a prompt
PreToolUse: Runs before tool calls (can block them)
PostToolUse: Runs after tool calls complete
PostToolUseFailure: Runs after tool calls fail
PermissionRequest: Runs when Claude asks for a permission decision
Notification: Runs when Claude Code sends notifications
Stop: Runs when Claude Code finishes responding
SubagentStart: Runs when a subagent task begins
SubagentStop: Runs when a subagent task completes
PreCompact: Runs before Claude runs context compaction
Setup: Runs during setup/maintenance workflows
TeammateIdle: Runs when an Agent Team teammate goes idle
TaskCompleted: Runs when a tracked task reaches completion

Prerequisites

Before using hooks, ensure you have the following prerequisites installed for your operating system:

Windows

Python: python --version

macOS

Python 3: python3 --version
Audio Player: afplay (built-in, no installation needed)

Linux

Python 3: python3 --version
Audio Player: sudo apt install pulseaudio-utils

Configuring Hooks (Enable/Disable)

Hooks can be easily enabled or disabled at both the global and individual levels.

Disable All Hooks at Once

Edit .claude/settings.local.json and set:

{
  "disableAllHooks": true
}

Note: The .claude/settings.local.json file is git-ignored, so each user can configure their own hook preferences without affecting the team's shared settings in .claude/settings.json.

Disable Individual Hooks

For granular control, you can disable specific hooks by editing the hooks configuration files.

Configuration Files

There are two configuration files for managing individual hooks:

.claude/hooks/config/hooks-config.json - The shared/default configuration that is committed to git
.claude/hooks/config/hooks-config.local.json - Your personal overrides (git-ignored)

The local config file (.local.json) takes precedence over the shared config, allowing each developer to customize their hook behavior without affecting the team.

Shared Configuration

Edit .claude/hooks/config/hooks-config.json for team-wide defaults:

{
  "disableSessionStartHook": false,
  "disableSessionEndHook": false,
  "disableUserPromptSubmitHook": false,
  "disablePreToolUseHook": false,
  "disablePostToolUseHook": false,
  "disablePostToolUseFailureHook": false,
  "disablePermissionRequestHook": false,
  "disableNotificationHook": false,
  "disableSubagentStartHook": false,
  "disableStopHook": false,
  "disableSubagentStopHook": false,
  "disablePreCompactHook": false,
  "disableSetupHook": false,
  "disableTeammateIdleHook": false,
  "disableTaskCompletedHook": false,
  "disableLogging": true
}

Local Configuration (Personal Overrides)

Create or edit .claude/hooks/config/hooks-config.local.json for personal preferences:

{
  "disablePostToolUseHook": true,
  "disableSessionStartHook": true
}

In this example, only the PostToolUse and SessionStart hooks are overridden locally. All other hooks will use the shared configuration values.

Note: Individual hook toggles are checked by the hook script (.claude/hooks/scripts/hooks.py). Local settings override shared settings, and if a hook is disabled, the script exits silently without playing sounds or executing hook logic.

Text to Speech (TTS)

website used to generate sounds: https://elevenlabs.io/ voice used: Samara X

3.8 KiB Raw Blame History