HarnessCommunity★ 500

claude-hooks (TypeScript)

Updated Jul 7, 2026

A TypeScript scaffolding tool for Claude Code hooks by johnlindquist. Run npx claude-hooks to generate .claude/hooks/index.ts with typed PreToolUse, PostToolUse, Notification, and Stop handlers — plus lib.ts type definitions and session.ts utilities. Write hook logic in TypeScript with full IntelliSense; hooks execute via Bun at runtime.

View on GitHub

What it does

npx claude-hooks
Scaffold the TypeScript hook system: generates .claude/settings.json, index.ts (handlers), lib.ts (types), and session.ts (tracking utilities).
PreToolUsePayload typed handler
TypeScript interface for the PreToolUse lifecycle event with typed tool_name and tool_input; return { action: "block" } to reject a tool call.
PostToolUsePayload typed handler
TypeScript interface for the PostToolUse lifecycle event with typed tool_name, success flag, tool_input, and tool_output.
npx claude-hooks init --force
Reinitialize the hook scaffolding, overwriting existing generated files.

Files (1)

OVERVIEW.mdprimary · markdown · 1.8 KB

## What it does

claude-hooks provides a TypeScript scaffolding system for Claude Code hooks by johnlindquist. Where the shell-script approach requires parsing raw JSON event payloads by hand, claude-hooks generates a complete typed development environment: strongly-typed payload interfaces for all four lifecycle events (PreToolUse, PostToolUse, Notification, Stop), auto-completion in any TypeScript editor, and access to the full npm ecosystem inside hook logic.

Hooks execute via Bun at runtime (required — curl -fsSL https://bun.sh/install | bash). Node.js 18+ is needed to run the CLI itself.

## Setup

npx claude-hooks

This generates:
- .claude/settings.json — hook configuration wiring
- .claude/hooks/index.ts — main handler file (edit this)
- .claude/hooks/lib.ts — type definitions and utilities
- .claude/hooks/session.ts — optional session tracking utilities

Session logs are saved to the system temp dir under claude-hooks-sessions/.

## Writing hooks (index.ts)

Four typed handler functions, one per lifecycle event:

async function preToolUse(payload: PreToolUsePayload): Promise<HookResponse>
- payload.tool_name, payload.tool_input (typed per tool)
- return { action: 'continue' } to allow, or { action: 'block', message: '...' } to reject

async function postToolUse(payload: PostToolUsePayload): Promise<void>
- payload.tool_name, payload.success, payload.tool_input, payload.tool_output

The typed WriteToolInput gives auto-completion for payload.tool_input.file_path and .content — no manual JSON parsing.

## When to use

Choose claude-hooks over shell scripts when you need npm packages in hook logic (e.g. calling an API, parsing structured data, sending Slack messages), or when you want TypeScript's type safety to catch mistakes in payload access at edit time rather than runtime.