cchooks

Claude Code Hook SDK for Python

[](https://github.com/hesreallyhim/awesome-claude-code)

---

A lightweight Python Toolkit that makes building Claude Code hooks as simple as writing a few lines of code. Stop worrying about JSON parsing and focus on what your hook should actually do.

**New to Claude Code hooks?** Check the [official docs](https://docs.anthropic.com/en/docs/claude-code/hooks) for the big picture.

**Need the full API?** See the [API Reference](docs/api-reference.md) for complete documentation.

Features

• One-liner setup: create_context() handles all the boilerplate
• Zero config: Automatic JSON parsing and validation from stdin
• Smart detection: Automatically figures out which hook you're building
• 9 hook types: Support for all Claude Code hook events including SessionStart and SessionEnd
• Two modes: Simple exit codes OR advanced JSON control
• Type-safe: Full type hints and IDE autocompletion
• System Message Support: Provide optional warning messages to users for all decision-making hooks

Installation

pip install cchooks
# or
uv add cchooks

Quick Start

Build a PreToolUse hook that blocks dangerous file writes:

#!/usr/bin/env python3
from cchooks import create_context, PreToolUseContext

c = create_context()

# Determine hook type
assert isinstance(c, PreToolUseContext)

# Block writes to .env files
if c.tool_name == "Write" and ".env" in c.tool_input.get("file_path", ""):
    c.output.exit_deny("Nope! .env files are protected")
else:
    c.output.exit_success()

Save as `hooks/env-guard.py`, make executable:

chmod +x hooks/env-guard.py

That's it. No JSON parsing, no validation headaches.

Brief Tutorial

Build each hook type with real examples:

PreToolUse (Security Guard)

Block dangerous commands before they run:

#!/usr/bin/env python3
from cchooks import create_context, PreToolUseContext

c = create_context()

...