You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CLAUDE.md
+85-30Lines changed: 85 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,61 +4,72 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
4
4
5
5
## Project Overview
6
6
7
-
This is a TypeScript library that provides type-safe hook definitions for Claude Code with automatic settings management. It allows users to define hooks that run at various points in Claude Code's lifecycle without manually editing settings.json files. Hook files are automatically compiled from TypeScript to JavaScript for execution.
7
+
This is a TypeScript library that provides type-safe hook definitions for Claude Code with automatic settings management. It allows users to define hooks that run at various points in Claude Code's lifecycle without manually editing settings.json files. Hook files are executed directly using ts-node without compilation.
8
8
9
-
## Build Commands
9
+
## Development Commands
10
10
11
11
```bash
12
+
# Install dependencies
13
+
bun install
14
+
12
15
# Build the TypeScript project
13
16
bun run build
14
17
15
18
# Watch mode for development
16
19
bun run dev
17
20
18
-
# Install dependencies
19
-
bun install
21
+
# Run tests
22
+
bun run test:run
23
+
24
+
# Run tests with coverage
25
+
bun run test:coverage
26
+
27
+
# Type checking / linting
28
+
bun run typecheck
20
29
```
21
30
22
31
## Architecture
23
32
24
33
### Key Concepts
25
34
26
35
1.**Self-Executing Hooks**: Hook files act as both the hook definition and the runner. When `defineHooks` is called, it checks if it's being run as a CLI and handles two modes:
27
-
28
36
-`__generate_settings`: Outputs JSON information about defined hooks
29
37
-`__run_hook`: Executes the appropriate hook handler
30
38
31
-
2.**No Separate Runner**: Unlike traditional approaches, there's no separate runner.js. The compiled hooks file itself is executed directly by the generated commands in settings.json.
39
+
2.**No Separate Runner**: Unlike traditional approaches, there's no separate runner.js. The hooks file itself is executed directly by the generated commands in settings.json using ts-node.
32
40
33
-
3.**Automatic Compilation**: The CLI compiles TypeScript hook files to JavaScript in the `.hooks` directory:
34
-
-TypeScript hooks are compiled on-the-fly when running the CLI
35
-
-Compiled JavaScript files are placed in `.hooks/` (gitignored)
36
-
- No need for ts-node at runtime - hooks run as pure JavaScript
41
+
3.**Direct TypeScript Execution**: The CLI generates commands that use ts-node to execute TypeScript hooks directly:
42
+
-No compilation step needed
43
+
-TypeScript hooks are executed directly using ts-node
44
+
- No intermediate JavaScript files are generated
37
45
38
46
4.**Smart Settings Generation**: The CLI only creates settings entries for hooks that are actually defined:
39
47
- For PreToolUse/PostToolUse: One entry per matcher
40
48
- For other hooks (Stop, Notification, SubagentStop): One entry only if handlers exist
49
+
- Commands use `npx ts-node` to execute the TypeScript hooks directly
41
50
42
51
5.**Multiple Hook Files**: The system supports two different hook files, all located in `.claude/hooks/`:
43
-
-`hooks.ts` - Project hooks (compiles to `.hooks/hooks.js`, updates `.claude/settings.json`)
44
-
-`hooks.local.ts` - Local hooks (compiles to `.hooks/hooks.local.js`, updates `.claude/settings.local.json`)
45
-
46
-
The CLI automatically detects which files exist, compiles them, and updates the corresponding settings files.
-`hooks.local.ts` - Local hooks (updates `.claude/settings.local.json`)
47
54
48
55
### Core Components
49
56
50
57
-**src/index.ts**: Exports `defineHooks` and `defineHook` functions. Contains the self-execution logic that makes hooks files act as their own runners.
51
58
52
-
-**src/cli.ts**: The CLI that compiles TypeScript hooks to JavaScript and updates settings.json files. It automatically detects which hook files exist (hooks.ts, hooks.local.ts), compiles them to `.hooks/`, and updates the corresponding settings files.
59
+
-**src/cli.ts**: The CLI that updates settings.json files to execute TypeScript hooks using ts-node. Includes an interactive `--init` command for project setup.
53
60
54
61
-**src/types.ts**: TypeScript type definitions for all hook types, inputs, and outputs. Key distinction between tool hooks (PreToolUse/PostToolUse) that have matchers and non-tool hooks.
55
62
56
-
-**src/hooks/**: Predefined hook utilities for common logging scenarios (logToolUseEvents, logStopEvents, logNotificationEvents)
63
+
-**src/hooks/**: Predefined hook utilities:
64
+
-`logToolUseEvents.ts`: Logs PreToolUse and PostToolUse events to JSON files
65
+
-`logStopEvents.ts`: Logs Stop and SubagentStop events
Note that commands reference the compiled JavaScript files in `.hooks/`, not the original TypeScript files.
97
+
Commands use `npx ts-node` to execute the TypeScript files directly.
98
+
99
+
## Testing
100
+
101
+
The project uses Vitest for testing with comprehensive coverage:
102
+
103
+
```bash
104
+
# Run a single test file
105
+
bun run test src/hooks/__tests__/logToolUseEvents.test.ts
106
+
107
+
# Run tests in watch mode
108
+
bun run test
109
+
110
+
# Run tests with coverage report
111
+
bun run test:coverage
112
+
```
113
+
114
+
Test structure:
115
+
- Each hook has corresponding tests in `src/hooks/__tests__/`
116
+
- Test utilities in `src/__tests__/` (fixtures, mockFs, testUtils)
117
+
- Global test setup in `src/__tests__/setup.ts`
118
+
- Coverage configuration in `vitest.config.mjs`
88
119
89
120
## Development Notes
90
121
@@ -93,17 +124,10 @@ Note that commands reference the compiled JavaScript files in `.hooks/`, not the
93
124
- Hook source files are all located in `.claude/hooks/`:
94
125
-`hooks.ts` (project-wide hooks)
95
126
-`hooks.local.ts` (local-only hooks, not committed to git)
96
-
- Compiled JavaScript files are generated in `.hooks/`:
97
-
-`.hooks/hooks.js`
98
-
-`.hooks/hooks.local.js`
99
-
- The `.hooks/` directory is gitignored
100
127
- Compatible with npm, yarn, pnpm, and bun package managers
101
-
- The CLI no longer requires flags - it automatically detects which hook files exist, compiles them, and updates the appropriate settings files
102
-
- No runtime dependency on ts-node - hooks execute as pure JavaScript
103
-
104
-
### Testing
105
-
106
-
When testing the package, create test repositories in the `tmp/` folder in the project root. This folder is already in `.gitignore` so test projects won't be committed.
128
+
- The CLI automatically detects which hook files exist and updates the appropriate settings files
129
+
- Requires ts-node as a dependency for executing TypeScript hooks
130
+
- When testing the package, create test repositories in the `tmp/` folder (already in `.gitignore`)
107
131
108
132
## Release Process
109
133
@@ -153,3 +177,34 @@ For testing new features before a stable release:
153
177
The package is published under the `@timoaus` scope as `@timoaus/define-claude-code-hooks`.
154
178
155
179
Note: The repository must have the `NPM_TOKEN` secret configured for publishing.
180
+
181
+
## CLI Features
182
+
183
+
### Interactive Initialization
184
+
185
+
The CLI provides an `--init` command for easy project setup:
186
+
187
+
```bash
188
+
define-claude-code-hooks --init
189
+
```
190
+
191
+
This command:
192
+
- Uses interactive prompts to select predefined hooks
193
+
- Automatically installs the package if needed (including ts-node)
194
+
- Detects the package manager (npm/yarn/pnpm/bun)
195
+
- Adds a `claude:hooks` script to package.json
196
+
- Creates initial hook files with selected hooks
197
+
198
+
### Automatic Hook Detection
199
+
200
+
The CLI automatically:
201
+
- Scans for hook files in `.claude/hooks/`
202
+
- Generates commands that use ts-node to execute the TypeScript files
203
+
- Updates corresponding settings files
204
+
- Preserves user-defined hooks while managing its own
205
+
206
+
# important-instruction-reminders
207
+
Do what has been asked; nothing more, nothing less.
208
+
NEVER create files unless they're absolutely necessary for achieving your goal.
209
+
ALWAYS prefer editing an existing file to creating a new one.
210
+
NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
0 commit comments