# claude-code-hooks-mastery: A Reference for All 13 Claude Code Hook Events > claude-code-hooks-mastery is a Python repository that demonstrates all 13 Claude Code hook lifecycle events, from UserPromptSubmit through SessionEnd, using UV single-file scripts and a team-based builder/validator pattern. It is a practical reference for engineers who want to add deterministic control, security filtering, or audio alerts to their Claude Code sessions, not a library to install. **disler/claude-code-hooks-mastery** — Master Claude Code Hooks - Repository: https://github.com/disler/claude-code-hooks-mastery - Stars: 3,929 · Forks: 632 - Language: Python - License: not declared - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/disler-claude-code-hooks-mastery ## What the Repository Covers and Who Should Read It Claude Code supports a hook system that lets developers intercept specific events in the agent's lifecycle and run their own scripts in response. The claude-code-hooks-mastery repository implements all 13 of these hook events with working Python scripts, logging each event's payload to a `logs/` directory as JSON. The README states that 11 of the 13 hooks have been validated through automated testing. The audience is engineers who have already started using Claude Code and want to go beyond the default behavior. The repository demonstrates how to validate and modify prompts before Claude processes them, block dangerous shell commands before they run, auto-allow safe read-only operations, play audio alerts when Claude finishes or needs input, and back up session transcripts before compaction. None of this requires modifying Claude Code itself; it all runs through the official hooks mechanism. This is not a package to install with pip. It is a reference implementation. The primary workflow is cloning the repository, reading the hook scripts, and copying or adapting the specific behaviors you want into your own project's `.claude/hooks/` directory. ## The 13 Hook Events and Their Trigger Points The README documents each hook in order. UserPromptSubmit fires the moment a user submits a prompt, before Claude processes it, and receives the prompt text, session ID, and timestamp. This is where the repository implements prompt validation, context injection, and security filtering. PreToolUse fires before any tool execution and receives the tool name and input parameters; the repository uses this hook to block `rm -rf` and access to `.env` files. PostToolUse fires after a successful tool execution and includes the tool's response. PostToolUseFailure fires when a tool fails, carrying the error object; the repository logs these with timestamps. Notification fires when Claude Code sends a notification, such as when it is waiting for input; the repository uses this to play a text-to-speech alert with a 30% chance of including the engineer's name from an environment variable. Stop fires when Claude Code finishes a response. The repository uses this hook to generate an AI-composed completion message and play it through text-to-speech, with the LLM priority order being ElevenLabs, then OpenAI, then Anthropic, then Ollama, then a random message. SubagentStop fires when a subagent Task tool finishes. PreCompact fires before Claude Code compacts the conversation and receives a trigger value of either `manual` or `auto`. The repository backs up the session transcript on this event. SessionStart fires on new sessions, resumes, and clears, and the repository loads development context such as git status and recent issues at this point. SessionEnd fires when the session exits and receives the transcript path and the reason for ending. PermissionRequest fires when a permission dialog appears; the repository auto-approves Read, Glob, Grep, and safe Bash operations. SubagentStart fires when a subagent spawns. Setup fires when Claude enters a repository or periodically during maintenance. ## UV Single-File Scripts and How Hooks Are Organized The repository uses UV single-file scripts, a pattern from the Astral UV tool, to keep hook logic isolated from any main codebase. All hook scripts live under `.claude/hooks/` as standalone Python files with their dependencies declared inline in the script header. This means each hook carries its own dependency list and UV can resolve and run it without a shared virtual environment. The README describes the benefit of this pattern as isolation: you can drop a hook script into any project's `.claude/hooks/` directory and it will run without requiring that project to manage Python dependencies for your hooks. The repository requires two prerequisites. UV itself must be installed; the README links to `docs.astral.sh/uv/getting-started/installation/` for this. Claude Code must also be installed. The optional integrations listed in the README are ElevenLabs for TTS via its MCP server, Firecrawl for web scraping, and OpenAI, Anthropic, or Ollama as LLM providers for the AI-generated completion messages in the Stop hook. Configuration for these providers goes into a `.env` file based on the `.env.sample` at the repository root: ```bash ANTHROPIC_API_KEY= DEEPSEEK_API_KEY= ELEVENLABS_API_KEY= ENGINEER_NAME=Dan FIRECRAWL_API_KEY= GEMINI_API_KEY= GROQ_API_KEY= OLLAMA_HOST= OPENAI_API_KEY= ``` The `ENGINEER_NAME` variable is used by the Notification hook when personalizing audio alerts. ## The Meta-Agent and Team-Based Validation Pattern Beyond individual hook scripts, the repository demonstrates two higher-level patterns. The first is the meta-agent, a Claude Code sub-agent that can orchestrate other sub-agents. The README covers this in a dedicated section that explains how one agent can spawn and direct others through the Task tool. The second pattern is team-based validation, a builder/validator approach where one agent generates code and a second agent independently checks it. The hooks support this workflow by adding quality controls at the PreToolUse and PostToolUse events, allowing the validator role to inspect outputs before they are committed. The repository also extracts chat transcripts from the JSONL format that Claude Code writes to a readable JSON format via a PostToolUse hook. The README warns that the `chat.json` output contains only the most recent conversation and is overwritten by each new session; it does not accumulate across sessions the way the other log files in `logs/` do. Teams relying on this for audit purposes should use the session transcript backup from the PreCompact hook instead. ## Hook Error Codes and Flow Control The README documents a table of hook error codes and flow control signals, though the specific codes are listed in a table that the repository prompt materials do not fully expose. The general mechanism is that hooks can return a non-zero exit code or write structured JSON to stdout to influence what Claude Code does next. The UserPromptSubmit hook, for instance, can modify the prompt before Claude sees it or block it entirely, and the PreToolUse hook can allow or deny a tool call. This flow control is the core value of the hook system. A prompt-validation hook can refuse a prompt that matches a pattern, log it, and return a message to the user without Claude processing it at all. A PreToolUse hook can block `rm -rf` calls regardless of what Claude intends to do, providing a hard stop that does not depend on Claude's own judgment. The PermissionRequest hook in the repository implements an auto-allow pattern for known-safe operations: Read, Glob, Grep, and safe Bash commands are approved without prompting, reducing interruptions in automated workflows while preserving the approval requirement for destructive operations. ## Limitations and Maintenance Status The repository has no published license. The README and top-level files do not include a LICENSE file, which means the terms under which you may use or adapt the code are not stated. Before incorporating any of the scripts into a project, verify whether the author has stated usage terms elsewhere. The last push to the repository was on 2026-03-04. There are no GitHub releases. The README references Claude Code's hook documentation at `docs.anthropic.com/en/docs/claude-code/hooks`; Claude Code's hook system may have changed since the repository was last updated, so check the official documentation for any hook event names or payload shapes that differ from what the repository demonstrates. A practical alternative to this repository is building hook scripts directly from Claude Code's official documentation without a reference implementation. The documentation covers the same hook events and provides the payload schemas. The difference is that this repository gives working, runnable examples with logging, TTS, and transcript handling already wired up, which is faster than building from scratch when you want more than a single hook. ## Conclusion claude-code-hooks-mastery is useful as a working reference for engineers who want to understand the full Claude Code hook lifecycle before writing their own hooks. Its value is in reading the hook scripts under `.claude/hooks/` and adapting the patterns, not in running the repository as-is in a production session. Teams that do not need TTS feedback or a multi-agent builder/validator pattern can strip the repository down to the specific hook implementations they need. The license is not documented in the repository, so review your organization's policy before incorporating the code. The last push was on 2026-03-04. ## FAQ ### How do I define hooks in Claude Code? Hooks are Python or shell scripts placed in your project's `.claude/hooks/` directory, named after the hook event they handle. The claude-code-hooks-mastery repository uses UV single-file scripts with inline dependency declarations so each hook script runs without a shared virtual environment. ### What are the best hooks in Claude Code? The most practically useful hooks demonstrated in this repository are PreToolUse for blocking dangerous commands, UserPromptSubmit for prompt validation, and PermissionRequest for auto-approving safe read-only operations. The Stop hook is useful for audio notifications when a long-running task finishes. ### Are Claude Code hooks useful? Hooks add deterministic control that Claude's own judgment cannot guarantee. A PreToolUse hook that blocks `rm -rf` will fire regardless of what Claude intends, and a UserPromptSubmit hook can log or filter prompts before Claude ever sees them. The claude-code-hooks-mastery repository demonstrates 13 such event points. ## Sources - [disler/claude-code-hooks-mastery on GitHub](https://github.com/disler/claude-code-hooks-mastery) - [Issues](https://github.com/disler/claude-code-hooks-mastery/issues) - [README](https://github.com/disler/claude-code-hooks-mastery/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/disler-claude-code-hooks-mastery