CC Hooks Ts

cc-hooks-ts

Define Claude Code hooks with full type safety using TypeScript.

See examples for more usage examples.

- cc-hooks-ts
  - Installation
  - Basic Usage
    - Define a Hook
    - Configure Claude Code
  - Tool Specific Hooks
    - Custom Tool Types Support
  - Advanced Usage
    - Conditional Hook Execution
    - Advanced JSON Output
    - Async JSON Output (Experimental)
  - Documentation
  - Development
    - How to follow the upstream changes
      - If a Dependabot PR already exists
      - If no Dependabot PR exists
  - License
  - Contributing

Starting with versions 2.0.42, we will raise our version number to match Claude Code whenever Hook-related changes occur.
This ensures we can adopt newer type definitions while maintaining compatibility.

Installation

Basic Usage

Define a Hook

Configure Claude Code

Then, load defined hooks in your Claude Code settings at ~/.claude/settings.json.

Tool Specific Hooks

In PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, and PermissionDenied events, you can define hooks specific to tools by specifying tool names in the trigger configuration.

For example, you can create a hook that only runs before the Read tool is used:

Then configure it in Claude Code settings:

The same trigger shape also works for permission hooks:

Custom Tool Types Support

You can add support for custom tools by extending the tool type definitions.

This is useful when you want to your MCP-defined tools to have type-safe hook inputs.

Advanced Usage

Conditional Hook Execution

You can conditionally execute hooks based on runtime logic using the shouldRun function.
If shouldRun returns false, the hook will be skipped.

Advanced JSON Output

Use context.json() to return structured JSON output with advanced control over…