How do I create a custom security hook with cchooks?

Use the PreToolUseContext to block dangerous operations; the README shows an example for blocking .env file writes by checking tool_name and tool_input, with automatic JSON handling.

What's the difference between exit_success and output.allow in cchooks?

exit_success uses simple exit codes for basic control, while output.allow provides advanced JSON output with optional system messages for precise behavior; choose based on your need for user feedback.

Can cchooks work with other AI tools like GitHub Copilot?

No, cchooks is specifically built for Claude Code's hook system and relies on its JSON schema, so it won't function with other assistants without significant modification.

How to handle errors when setting up a hook context?

Use safe_create_context() for automatic error handling or wrap create_context() in try-except with handle_context_error(), as detailed in the error handling section for graceful exits.

Is cchooks production-ready for large teams?

It offers type safety and error handling, but being a new project, it has a limited ecosystem and might face breaking changes if Claude Code updates its hook API.

cchooks vs writing hooks manually in Python: which is better?

cchooks saves time on JSON parsing and validation, but manual writing gives more control; choose cchooks for rapid development in Claude Code-specific projects, but manual for cross-platform needs.

Open-Awesome

cchooks

MITPythonv0.1.5

A lightweight Python SDK for building Claude Code hooks with automatic JSON parsing and type-safe context handling.

Visit Website GitHub

131 stars10 forks0 contributors

What is cchooks?

cchooks is a Python SDK that simplifies creating hooks for Claude Code, an AI coding assistant. It eliminates the boilerplate of JSON parsing and validation, allowing developers to focus on implementing hook logic for security, automation, and workflow control.

Target Audience

Python developers building custom hooks for Claude Code to add security, automation, logging, or workflow control to their AI-assisted coding sessions.

Value Proposition

Developers choose cchooks because it provides a one-liner setup with automatic JSON parsing and hook type detection, full type hints for IDE autocompletion, and support for both simple exit codes and advanced JSON output modes, significantly reducing implementation complexity.

Overview

A Python SDK for claude-code hooks

Use Cases

Best For

Building security hooks to block dangerous commands or file writes in Claude Code sessions.
Creating automation hooks to format code, run linters, or auto-commit changes after file writes.
Implementing workflow control hooks to manage when Claude or subagents should stop working.
Adding custom logging or notification systems for Claude Code activities.
Filtering or enriching user prompts before they are processed by Claude.
Loading project-specific context or performing cleanup tasks at the start or end of coding sessions.

Not Ideal For

Developers using AI coding assistants other than Claude Code (e.g., GitHub Copilot or Codeium)
Teams building hooks in non-Python languages like JavaScript or Bash
Projects requiring a visual interface or GUI for hook configuration and management

Pros & Cons

Pros

One-liner Setup

The create_context() function automatically handles JSON parsing and validation from stdin, eliminating boilerplate code as shown in the quick start example for building a PreToolUse hook.

Smart Hook Detection

Automatically identifies the hook type from nine supported events like SessionStart and SessionEnd, reducing manual configuration and errors.

Type-Safe Development

Provides full type hints and IDE autocompletion for each hook context, improving code reliability and developer experience, evident in the PreToolUseContext assertions.

Dual Output Modes

Supports simple exit codes for basic control and advanced JSON output with system messages, offering flexibility as demonstrated in the system message support section.

Cons

Claude Code Lock-in

Designed exclusively for Claude Code hooks, making it unsuitable for other AI assistants or general-purpose automation, with no built-in adapters for different platforms.

Python Dependency Overhead

Requires Python and the cchooks package installation, adding complexity for teams preferring lightweight shell scripts or zero-dependency solutions.

Parallel Execution Complexity

For Stop hooks, developers must manually check stop_hook_active to handle parallel execution, a nuance the README admits can lead to errors if overlooked.

Frequently Asked Questions

Related Projects

Superpowers

An agentic skills framework & software development methodology that works.

Stars303,225

Forks27,024

Last commit1 day ago

Everything Claude Code

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

Stars285,823

Forks42,397

Last commit2 days ago

Learn Claude Code

Bash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1

Stars78,969

Forks12,629

Last commit24 days ago

Claude Scientific Skills

Turn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 250,000+ scientists worldwide. 177 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.

Stars53,642

Forks4,732

Last commit4 days ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub