Claude PyHooks

A lightweight framework for implementing Claude Code hooks in Python.

Overview

Claude PyHooks makes it easy to build and register custom hooks for Claude Code.
The following hook types are supported:

Installation

pip install claude-pyhooks
# or, if you use uv
uv add claude-pyhooks

Development version (recommended with uv)

git clone <this-repository>
cd claude-pyhooks
uv sync
uv pip install -e .

Quick start

PreToolUse — block a dangerous command

#!/usr/bin/env python3
from claude_pyhooks import (
    PreToolUseInput,
    PreToolUseOutput,
    BashInput,
)

def main() -> None:
    hook_input = PreToolUseInput.from_stdin()

    if hook_input.tool_name == "Bash":
        assert isinstance(hook_input.tool_input, BashInput)
        command = (hook_input.tool_input.command or "").strip()

        if "rm -rf /" in command:
            PreToolUseOutput.block(
                f"Dangerous command blocked: {command}"
            ).execute()

if __name__ == "__main__":
    main()

PostToolUse — log every Bash run

#!/usr/bin/env python3
from claude_pyhooks import (
    PreToolUseInput,
    PreToolUseOutput,
    BashInput,
)

def main() -> None:
    hook_input = PreToolUseInput.from_stdin()

    if hook_input.tool_name == "Bash":
        assert isinstance(hook_input.tool_input, BashInput)
        command = (hook_input.tool_input.command or "").strip()

        if "rm -rf /" in command:
            PreToolUseOutput.block(
                f"Dangerous command blocked: {command}"
            ).execute()

if __name__ == "__main__":
    main()

Notification — play a beep

#!/usr/bin/env python3
from pathlib import Path
from claude_pyhooks import (
    PostToolUseInput,
    BashInput,
    BashResponse,
)

log_file = Path(__file__).with_name("bash_command_log.txt")

def main() -> None:
    hook_input = PostToolUseInput.from_stdin()

    if hook_input.tool_name == "Bash":
        assert isinstance(hook_input.tool_input, BashInput)
        assert isinstance(hook_input.tool_response, BashResponse)

        command = hook_input.tool_input.command
        success = not hook_input.tool_response.stderr
        status = "success" if success else "failure"

        with log_file.open("a") as f:
            f.write(f"{status}: {command}\n")

if __name__ == "__main__":
    main()

Registering hooks with Claude Code

Add the hooks to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "uv run /path/to/pre_hook.py"
          }
        ]
      }
    ]
  }
}

API highlights

Input classes

tool_input and tool_response are automatically parsed into strongly-typed objects such as BashInput or BashResponse.

Output classes

Calling .execute() dispatches the command queue.
If the output blocks execution, the process exits with code 2 automatically.

Beep utilities

Pre-defined constants:

• DEFAULT_BEEP
• SUCCESS_BEEP
• ERROR_BEEP
• WARNING_BEEP

Each constant is an instance of BeepCommand and can be part of a BeepSequence.

Examples

See the examples/ directory for practical scripts:

License

MIT License