Claude Hook Kit

claude-hook-kit

TypeScript SDK for building [Claude Code](https://docs.anthropic.com/en/docs/claude-code) hooks — typed, testable, composable.

Claude Code's hook system lets you intercept tool calls, inject context, and react to session events. Without this package, hooks are raw shell scripts that read/write JSON with no type safety, no testing utilities, and no shared patterns. `claude-hook-kit` fixes that.

import { defineHook, block, allow } from 'claude-hook-kit'

defineHook<'PreToolUse'>(async (event) => {
  if (event.tool_name === 'Bash') {
    const { command } = event.tool_input
    if (command.includes('rm -rf /')) {
      return block('Refusing to delete the filesystem')
    }
  }
  return allow()
}).run()

Installation

npm install claude-hook-kit

Requires Node.js ≥ 18.

What are Claude Code hooks?

Hooks are shell commands that Claude Code runs at specific lifecycle points. They receive a JSON payload on stdin and write a JSON response to stdout. Claude Code uses the response to decide whether to allow, block, or augment the operation.

Event	When it fires	Can block?	Can inject context?
PreToolUse	Before any tool call	✅	✅
PostToolUse	After a tool call completes	❌	✅
SessionStart	On startup, resume, clear, compact	❌	✅
UserPromptSubmit	When the user submits a message	✅	✅
Stop	When Claude finishes a response	✅ (force continue)	❌

Register hooks in `~/.claude/settings.json`:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "node /path/to/my-hook.js"
      }]
    }]
  }
}

API

`defineHook(handler)`

The core function. Wraps your handler with stdin parsing, stdout serialization, and error handling.

import { defineHook, allow } from 'claude-hook-kit'

// Generic — no type parameter (untyped event)
defineHook(async (event) => allow())