This repository demonstrates how to leverage Claude Code hooks for deterministic control over AI agent behavior, targeting developers and power users of Anthropic's Claude Code CLI. It provides a comprehensive framework for intercepting and modifying agent interactions, enhancing security, and enabling custom workflows through a structured hook system.

How It Works

The project utilizes Claude Code's hook lifecycle, which allows custom Python scripts to intercept 8 distinct events: UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop, SubagentStop, PreCompact, and SessionStart. Each hook can log events, validate inputs/outputs, inject context, or block execution using specific exit codes and JSON payloads. The architecture relies on UV single-file scripts for isolated, portable hook logic with self-declared dependencies, simplifying environment management and execution.

Quick Start & Requirements

• Install using pip install astral-uv.
• Requires Claude Code CLI.
• Optional: ElevenLabs, Firecrawl, OpenAI, Anthropic for enhanced functionality.
• See official documentation for detailed hook usage.

Highlighted Details

• Full coverage of all 8 Claude Code hook lifecycle events with detailed JSON payloads.
• UserPromptSubmit hook allows prompt validation, security filtering, and context injection.
• PreToolUse hook enables blocking of dangerous commands like rm -rf.
• Intelligent TTS system with priority for audio feedback (ElevenLabs > OpenAI).
• Sub-agent and Meta-Agent capabilities for task specialization and automated agent creation.

Maintenance & Community

• Developed by IndyDevDan.
• YouTube channel for AI coding tips and tricks.

Licensing & Compatibility

• The repository does not explicitly state a license. Users should verify compatibility for commercial or closed-source use.

Limitations & Caveats

The chat.json file only contains the most recent conversation transcript and is overwritten with each new session, unlike other logs which are appended. Some hooks, like PostToolUse and Notification, cannot block execution.