claude-hooks
A TypeScript-based system for configuring and customizing Claude Code hooks with full type safety and auto-completion.
What is claude-hooks?
claude-hooks is a TypeScript-powered development environment and CLI tool for customizing Claude Code's behavior through hooks. It generates a structured project with full type safety, enabling developers to write hook handlers with strongly-typed payloads and auto-completion, eliminating guesswork with untyped data.
Developers using Claude Code who want to extend or customize its behavior with type-safe, maintainable code, particularly those familiar with TypeScript and Node.js/Bun environments.
Developers choose claude-hooks for its complete TypeScript support and strongly-typed payloads, which provide IntelliSense and reduce errors compared to working with untyped hook data. It offers a ready-to-customize setup with generated utilities, allowing focus on logic rather than configuration.
Overview
claude-hooks provides a powerful, TypeScript-based development environment for customizing Claude Code's behavior through hooks. It enables developers to write hook handlers with complete type safety, auto-completion, and access to strongly-typed payloads, eliminating the guesswork from working with untyped data.
Key Features
- Full TypeScript Support — Write hooks with complete type safety and IntelliSense in familiar TypeScript syntax.
- Typed Payloads — Access strongly-typed payload data for all hook types (PreToolUse, PostToolUse, Notification, Stop).
- Ready-to-Customize Setup — Generates clean TypeScript files and configuration for immediate customization.
- Generated Utilities — Includes type definitions, session tracking utilities, and a structured project layout.
- Flexible Integration — Use any npm packages, async/await, or development patterns within your hooks.
Philosophy
The project emphasizes developer experience by providing a strongly-typed, intuitive interface for hook customization, allowing users to focus on logic rather than data structure validation.
Use Cases
Best For
- Adding custom logging or notifications when Claude Code uses specific tools like 'Write' or 'Bash'.
- Integrating Claude Code with external services (e.g., webhooks, dashboards) via typed hook handlers.
- Enforcing coding standards or validations in Claude Code's output through pre- or post-tool use hooks.
- Tracking and analyzing Claude Code sessions for debugging or analytics purposes.
- Extending Claude Code with custom logic using familiar TypeScript patterns and npm packages.
- Setting up a type-safe development environment for Claude Code hooks quickly via a CLI generator.
Not Ideal For
- Environments where Bun runtime cannot be installed due to IT restrictions or infrastructure constraints.
- Projects using AI coding assistants other than Claude Code, as the hooks are ecosystem-specific.
- Developers who prefer lightweight, configuration-only setups without TypeScript compilation or type safety overhead.
- Teams needing real-time hook processing with minimal runtime footprint, as Bun and TypeScript add execution layers.
Pros & Cons
Pros
Provides complete type safety and IntelliSense for hook handlers, eliminating guesswork with payload structures and reducing errors.
Offers strongly-typed payloads for all hook types like PreToolUse and PostToolUse, ensuring accurate data handling with auto-completion.
Generates clean TypeScript files and configuration immediately via npx, allowing developers to start customizing hooks without manual setup.
Supports async/await, npm packages, and familiar TypeScript syntax, enabling integration with external services and complex logic.
Cons
Requires Bun for running hooks, adding installation complexity and limiting compatibility in environments where only Node.js is available.
Tightly coupled with Claude Code's hook system, making it unsuitable for projects using other AI assistants or needing portable hook solutions.
Currently supports only specific hooks (PreToolUse, PostToolUse, Notification, Stop), which may not cover all customization needs if Claude Code expands its API.
Frequently Asked Questions
Related Projects
SuperpowersAn agentic skills framework & software development methodology that works.
Everything Claude CodeThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Learn Claude CodeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1
Claude Code TemplatesCLI tool for configuring and monitoring Claude Code
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.