cchooks

cchooks
Claude Code Hook SDK for Python

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

Quick Start

Build a PreToolUse hook that blocks dangerous file writes:

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

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:

PostToolUse (Auto-formatter)

Format Python files after writing:

Notification (Desktop Alerts)

Send desktop notifications:

Stop (Task Manager)

Keep Claude working on long tasks:
Since hooks are executed in parallel in Claude Code, it is necessary to check stop_hook_active to determine if Claude has already been activated by another parallel Stop Hook.

SubagentStop (Workflow Control)

Same as Stop, but for subagents:

UserPromptSubmit (Prompt Filter)

Filter and enrich user prompts before processing:

SessionStart (Context Loader)

Load development context when Claude Code starts or…