# Add to your Claude Code skills
git clone https://github.com/GowayLee/cchooks
README.md
<div align="center">
<h1>cchooks</h1>
<h3>Claude Code Hook SDK for Python</h3>
</div>
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 for the big picture.
Need the full API? See the API Reference 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()
assert isinstance(c, PreToolUseContext)
# Block rm -rf commands with user warning
if c.tool_name == "Bash" and "rm -rf" in c.tool_input.get("command", ""):
c.output.deny(
reason="You should not execute this command: System protection: rm -rf blocked",
system_message="⚠️ This command could permanently delete files. Please use caution."
)
else:
c.output.allow()
