AgentCommunity★ 3k

Claude Code Hooks Mastery

Updated Jul 7, 2026

A teaching repository by disler (IndyDevDan) that implements every one of Claude Code's 13 hook events as standalone, single-file UV Python scripts. Covers all hook types — UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart/Stop, SessionStart/End, PermissionRequest, PreCompact, PostToolUseFailure, and Setup — plus 9 custom status line variants, 8 output styles, team-based builder/validator agents, and a meta-agent that generates new agents.

View on GitHub

What it does

UserPromptSubmit hook
Fires before Claude sees a prompt; can log, validate for dangerous patterns, block the prompt (exit 2), or inject project context.
PreToolUse hook
Intercepts every tool call before execution; blocks dangerous commands (rm -rf, .env access) via exit code 2 with a stderr message to Claude.
PostToolUse hook
Runs after a tool returns; captures output for logging, TTS alerts, and JSONL transcript conversion.
Stop hook
Intercepts when Claude finishes responding; can block stoppage (exit 2) to force task completion, or generate TTS completion messages.
meta-agent
Generates new properly-formatted Claude Code agent files from plain-English descriptions, pulling latest docs automatically.
status_line_v6.py
Displays a visual context window usage bar with percentage and tokens remaining in the terminal status line.
/plan_w_team
Meta-prompt command that generates a team plan, spawns builder and validator subagents in parallel, and self-validates output via embedded stop hooks.

Files (1)

OVERVIEW.mdprimary · markdown · 2.6 KB

## What it does

A teaching repository implementing all 13 Claude Code hook events as standalone single-file UV Python scripts, wired via .claude/settings.json. UV handles per-script dependencies with no virtual environment overhead.

Hook implementations:

- user_prompt_submit.py — logs prompts, optionally validates for dangerous patterns, and injects project context before Claude sees the prompt
- pre_tool_use.py — blocks dangerous commands (rm -rf, .env access) and logs all tool calls before execution
- post_tool_use.py — logs results, converts JSONL transcripts to readable JSON
- post_tool_use_failure.py — structured error logging with timestamps and full context
- notification.py — optional TTS alerts when Claude needs input (ElevenLabs > OpenAI > pyttsx3 priority)
- stop.py — AI-generated completion messages with TTS playback after Claude finishes
- subagent_start/stop.py — subagent spawn/completion logging and optional TTS
- session_start.py — loads git status, recent issues, and context files at session start
- session_end.py — session logging and optional temp file cleanup
- permission_request.py — audits permission dialogs; auto-approves read-only ops (Read, Glob, Grep, safe Bash)
- pre_compact.py — backs up transcripts before compaction
- setup.py — repository initialization and periodic maintenance hooks

Also includes: 9 status line variants (git info, cost tracking, context window usage bar, token/cache stats, session duration, powerline style), 8 output styles (genui HTML, tables, YAML, bullet points, ultra-concise, TTS summary), team-based builder+validator agents for parallel code quality enforcement, and a meta-agent that generates new agent files from descriptions.

## Install

Requires Astral UV and Claude Code. Optional: ElevenLabs or OpenAI API keys for TTS.

Copy the .claude/ directory to your project or clone the repo and symlink. Register hooks in .claude/settings.json using $CLAUDE_PROJECT_DIR prefix for reliable path resolution:

    "PreToolUse": [{"hooks": [{"type": "command", "command": "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/pre_tool_use.py"}]}]

UserPromptSubmit options: --log-only (default), --validate (enable security filtering), --context (inject project context).

## When to use

Use as a reference when building your own hooks — read the scripts, understand the exit code behavior (0 = success, 2 = block with stderr to Claude, other = non-blocking error), then copy the scripts you need. Good starting points: pre_tool_use.py for dangerous command blocking, user_prompt_submit.py for audit logging, and any status line variant for terminal context.