CC Hooks TS

https://github.com/sushichan044/cc-hooks-ts
Admin
CC Hooks TS is a TypeScript library for defining Claude Code hooks with full type safety and support...
Tokens:7,818
Snippets:55
Trust Score:9.1
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install cc-hooks-ts using npm, yarn, pnpm, Bun, or Deno

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/README.md

This snippet shows how to install the cc-hooks-ts library using various package managers. It covers npm, yarn, pnpm, Bun, and Deno for easy integration into different project setups.

```bash
# npm
npm i cc-hooks-ts

# yarn
yarn add cc-hooks-ts

# pnpm
pnpm add cc-hooks-ts

# Bun
bun add cc-hooks-ts

# Deno
denp add npm:cc-hooks-ts
```

--------------------------------

### Handle Non-Blocking Errors with TypeScript

Source: https://context7.com/sushichan044/cc-hooks-ts/llms.txt

Utilize non-blocking errors to display messages to the user without stopping Claude Code processing. The hook exits with code 1. This example shows how to warn about deprecated commands and handle silent errors for optional features like desktop notifications. Requires 'cc-hooks-ts'.

```typescript
import { defineHook } from "cc-hooks-ts";

const warningHook = defineHook({
  trigger: { PostToolUse: { Bash: true } },
  run: (context) => {
    const { command } = context.input.tool_input;

    // Warn about deprecated patterns but don't block
    if (command.includes("npm install")) {
      return context.nonBlockingError(
        "Warning: Consider using pnpm instead of npm for faster installs"
      );
    }

    return context.success();
  }
});

// Silent non-blocking error (no message shown)
const silentHook = defineHook({
  trigger: { Notification: true },
  run: (context) => {
    try {
      sendDesktopNotification(context.input.message);
      return context.success();
    } catch {
      // Fail silently - notifications are optional
      return context.nonBlockingError();
    }
  }
});
```

--------------------------------

### Configure cc-hooks-ts in Claude Code settings.json

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/README.md

This JSON configuration shows how to integrate a defined hook into Claude Code's settings. It specifies the `SessionStart` event and points to a command that executes the TypeScript hook script.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bun run -i --silent path/to/your/sessionHook.ts"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Configure Claude Code Hooks in settings.json

Source: https://context7.com/sushichan044/cc-hooks-ts/llms.txt

Illustrates how to configure Claude Code to load custom hooks by defining them in the `settings.json` file located at `~/.claude/settings.json`. This configuration maps event types to specific commands or scripts that should be executed when those events occur.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bun run --silent /path/to/hooks/session-start.ts"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "bun run --silent /path/to/hooks/pre-read.ts"
          }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "node /path/to/hooks/pre-write.js"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "deno run --allow-all /path/to/hooks/pre-bash.ts"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Grep",
        "hooks": [
          {
            "type": "command",
            "command": "bun run --silent /path/to/hooks/post-grep.ts"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bun run --silent /path/to/hooks/notification.ts"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bun run --silent /path/to/hooks/stop.ts"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Advanced JSON Output Control with TypeScript

Source: https://context7.com/sushichan044/cc-hooks-ts/llms.txt

Leverage context.json for fine-grained control over hook behavior, including permission decisions, input modifications, and additional context. This allows for detailed responses to various triggers like PreToolUse, PostToolUse, UserPromptSubmit, and Stop events. Requires 'cc-hooks-ts'.

```typescript
import { defineHook } from "cc-hooks-ts";

// PreToolUse: Deny access with detailed reason
const denyHook = defineHook({
  trigger: { PreToolUse: { Read: true } },
  run: (context) => {
    const { file_path } = context.input.tool_input;

    if (file_path.endsWith(".env")) {
      return context.json({
        event: "PreToolUse",
        output: {
          hookSpecificOutput: {
            hookEventName: "PreToolUse",
            permissionDecision: "deny",
            permissionDecisionReason: "Reading .env files is restricted for security."
          }
        }
      });
    }

    return context.success();
  }
});

// PreToolUse: Modify tool input before execution
const modifyInputHook = defineHook({
  trigger: { PreToolUse: { Bash: true } },
  run: (context) => {
    const { command } = context.input.tool_input;

    // Add timeout to long-running commands
    if (command.startsWith("npm test") || command.startsWith("pnpm test")) {
      return context.json({
        event: "PreToolUse",
        output: {
          hookSpecificOutput: {
            hookEventName: "PreToolUse",
            permissionDecision: "allow",
            updatedInput: {
              command: command,
              timeout: 300000 // 5 minutes
            }
          }
        }
      });
    }

    return context.success();
  }
});

// PostToolUse: Add context based on tool response
const postToolHook = defineHook({
  trigger: { PostToolUse: { Grep: true } },
  run: (context) => {
    const response = context.input.tool_response;

    return context.json({
      event: "PostToolUse",
      output: {
        hookSpecificOutput: {
          hookEventName: "PostToolUse",
          additionalContext: `Search returned results. Consider filtering further if needed.`
        }
      }
    });
  }
});

// UserPromptSubmit: Block certain prompts
const promptFilterHook = defineHook({
  trigger: { UserPromptSubmit: true },
  run: (context) => {
    const prompt = context.input.prompt;

    if (prompt.toLowerCase().includes("delete all")) {
      return context.json({
        event: "UserPromptSubmit",
        output: {
          decision: "block",
          reason: "Prompts containing 'delete all' require manual confirmation."
        }
      });
    }

    return context.success();
  }
});

// Stop: Prevent Claude from stopping prematurely
const preventStopHook = defineHook({
  trigger: { Stop: true },
  run: (context) => {
    const stopReason = context.input.stop_hook_reason;

    if (stopReason === "end_turn" && !context.input.stop_sequence) {
      return context.json({
        event: "Stop",
        output: {
          decision: "block",
          reason: "Please verify all tests pass before stopping."
        }
      });
    }

    return context.success();
  }
});
```

--------------------------------

### Project Development and Maintenance Commands

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/README.md

Standardized shell commands for managing the project lifecycle, including testing, building, linting, and formatting. Also includes commands for tracking upstream SDK type changes.

```bash
# Run tests
pnpm test

# Build
pnpm build

# Lint
pnpm lint

# Format
pnpm format

# Type check
pnpm typecheck
```

```bash
# Get diff of types between two versions
npm diff --diff=@anthropic-ai/claude-agent-sdk@0.1.69 --diff=@anthropic-ai/claude-agent-sdk@0.1.70 '**/*.d.ts'

# Get side-by-side diff visualization
npm diff --diff=@anthropic-ai/claude-agent-sdk@0.1.69 --diff=@anthropic-ai/claude-agent-sdk@0.1.70 '**/*.d.ts' | delta --side-by-side
```

--------------------------------

### Configure a tool-specific hook in Claude Code settings.json

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/README.md

This JSON configuration demonstrates how to set up a tool-specific hook in Claude Code. It targets the `PreToolUse` event and uses a `matcher` to specify that the hook should only apply to the `Read` tool, executing a command to run the hook script.

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "bun run -i --silent path/to/your/preReadHook.ts"
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Execute Hooks with runHook

Source: https://context7.com/sushichan044/cc-hooks-ts/llms.txt

Executes a defined hook by reading input from stdin, validating it against schemas, and managing the hook lifecycle. It handles outputting results and exit codes (0, 1, or 2) to the Claude Code environment.

```typescript
import { defineHook, runHook } from "cc-hooks-ts";

const validationHook = defineHook({
  trigger: { PreToolUse: { Bash: true } },
  run: (context) => {
    const { command } = context.input.tool_input;
    if (command.includes("rm -rf /")) {
      return context.blockingError("Dangerous command blocked");
    }
    return context.success();
  }
});

await runHook(validationHook);
```

--------------------------------

### Manage Hook Success Responses

Source: https://context7.com/sushichan044/cc-hooks-ts/llms.txt

Utilizes context.success to return successful hook outcomes. Allows for optional payloads including messages for the user or additional context for the Claude model.

```typescript
import { defineHook } from "cc-hooks-ts";

const messageHook = defineHook({
  trigger: { PostToolUse: { Write: true } },
  run: (context) => {
    const { file_path } = context.input.tool_input;
    return context.success({
      messageForUser: `File ${file_path} was written successfully`
    });
  }
});

const contextHook = defineHook({
  trigger: { SessionStart: true },
  run: (context) => {
    return context.success({
      additionalClaudeContext: "Project uses pnpm and TypeScript strict mode."
    });
  }
});
```

--------------------------------

### Define a basic TypeScript hook for SessionStart event

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/README.md

This TypeScript code defines a simple hook using `defineHook` from `cc-hooks-ts`. The hook is triggered by the `SessionStart` event and executes a function that returns a success message for the user. It also includes logic to run the hook when the script is executed directly.

```typescript
import { defineHook } from "cc-hooks-ts";

const hook = defineHook({
  // Specify the event(s) that trigger this hook.
  trigger: {
    SessionStart: true,
  },
  // Implement what you want to do.
  run: (context) => {
    // Do something great here
    return context.success({
      messageForUser: "Welcome to your coding session!",
    });
  },
});

// import.meta.main is available in Node.js 24.2+ and Bun and Deno
if (import.meta.main) {
  const { runHook } = await import("cc-hooks-ts");
  await runHook(hook);
}
```

--------------------------------

### Define Claude Code Hooks in TypeScript

Source: https://context7.com/sushichan044/cc-hooks-ts/llms.txt

Demonstrates how to define different types of Claude Code hooks using the `cc-hooks-ts` library. These hooks allow for custom logic execution at various stages of the Claude Code lifecycle, such as pre-tool validation, post-tool reaction, session management, and prompt handling.

```typescript
import { defineHook } from "cc-hooks-ts";

// PreToolUse - Validate/modify tool inputs before execution
const preToolHook = defineHook({
  trigger: { PreToolUse: { Bash: true, Write: true, Edit: true } },
  run: (context) => {
    console.log(`Pre-execution: ${context.input.tool_name}`);
    return context.success();
  }
});

// PostToolUse - React to tool results
const postToolHook = defineHook({
  trigger: { PostToolUse: { Grep: true, Glob: true } },
  run: (context) => {
    console.log(`Post-execution: ${context.input.tool_name}`);
    return context.success();
  }
});

// PostToolUseFailure - Handle tool failures
const failureHook = defineHook({
  trigger: { PostToolUseFailure: { Bash: true } },
  run: (context) => {
    return context.success({
      messageForUser: `Tool ${context.input.tool_name} failed`
    });
  }
});

// SessionStart - Initialize session
const sessionStartHook = defineHook({
  trigger: { SessionStart: true },
  run: (context) => {
    return context.success({
      additionalClaudeContext: "Session initialized with custom configuration."
    });
  }
});

// SessionEnd - Cleanup on session end
const sessionEndHook = defineHook({
  trigger: { SessionEnd: true },
  run: (context) => context.success()
});

// UserPromptSubmit - Filter/modify user prompts
const promptHook = defineHook({
  trigger: { UserPromptSubmit: true },
  run: (context) => {
    console.log(`User prompt: ${context.input.prompt}`);
    return context.success();
  }
});

// Stop - Control when Claude stops
const stopHook = defineHook({
  trigger: { Stop: true },
  run: (context) => context.success()
});

// SubagentStart/SubagentStop - Monitor subagent lifecycle
const subagentHook = defineHook({
  trigger: { SubagentStart: true, SubagentStop: true },
  run: (context) => context.success()
});

// Notification - Handle Claude notifications
const notificationHook = defineHook({
  trigger: { Notification: true },
  run: (context) => {
    console.log(`Notification: ${context.input.message}`);
    return context.success();
  }
});

// PermissionRequest - Custom permission handling
const permissionHook = defineHook({
  trigger: { PermissionRequest: true },
  run: (context) => {
    return context.json({
      event: "PermissionRequest",
      output: {
        hookSpecificOutput: {
          hookEventName: "PermissionRequest",
          decision: { behavior: "allow" }
        }
      }
    });
  }
});

// Setup - One-time setup tasks
const setupHook = defineHook({
  trigger: { Setup: true },
  run: (context) => context.success()
});

// PreCompact/PostCompact - Context compaction hooks
const compactHook = defineHook({
  trigger: { PreCompact: true, PostCompact: true },
  run: (context) => context.success()
});
```

--------------------------------

### Asserting Types with expectTypeOf

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/docs/ai/vitest-typechecking-api-reference.md

The expectTypeOf function provides a fluent interface for validating types. It supports various matchers like toBeFunction, toEqualTypeOf, and toMatchTypeOf to verify function signatures and object structures.

```typescript
import { expectTypeOf } from "vitest";
import { someFunction } from "./my-code";

test("my types work correctly", () => {
  // Assert that a value is a specific type
  expectTypeOf(someFunction).toBeFunction();

  // Assert function parameter types
  expectTypeOf(someFunction).parameter(0).toMatchTypeOf<{ id: string }>();

  // Assert a value's type against another type
  expectTypeOf<{ a: number }>().toEqualTypeOf<{ a: number }>();
});
```

--------------------------------

### Perform background tasks with context.defer in TypeScript

Source: https://context7.com/sushichan044/cc-hooks-ts/llms.txt

The context.defer method allows for non-blocking execution of long-running tasks within Claude Code hooks. It accepts an async function and an optional configuration object for timeouts, returning an immediate acknowledgment to the TUI.

```typescript
import { defineHook } from "cc-hooks-ts";

const asyncHook = defineHook({
  trigger: { PostToolUse: { Read: true } },
  run: (context) => {
    return context.defer(
      async () => {
        await new Promise(resolve => setTimeout(resolve, 2000));
        const { file_path } = context.input.tool_input;
        const analysis = await analyzeFileComplexity(file_path);
        return {
          event: "PostToolUse",
          output: {
            systemMessage: `File analysis complete: ${analysis.summary}`,
            hookSpecificOutput: {
              hookEventName: "PostToolUse",
              additionalContext: `Complexity score: ${analysis.score}/100`
            }
          }
        };
      },
      { timeoutMs: 10000 }
    );
  }
});
```

--------------------------------

### Implement Asynchronous Hook Processing in TypeScript

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/README.md

Demonstrates using context.defer to perform background computations within a Claude Code hook without blocking the TUI. It includes a simulated delay and an optional timeout configuration.

```typescript
import { defineHook } from "cc-hooks-ts";

const hook = defineHook({
  trigger: { PostToolUse: { Read: true } },
  run: (context) =>
    context.defer(
      async () => {
        // Simulate long-running computation
        await new Promise((resolve) => setTimeout(resolve, 2000));

        return {
          event: "PostToolUse",
          output: {
            systemMessage: "Read tool used successfully after async processing!",
          },
        };
      },
      {
        timeoutMs: 5000, // Optional timeout for the async operation.
      },
    ),
});
```

--------------------------------

### Define a tool-specific hook for PreToolUse event

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/README.md

This TypeScript code defines a hook that triggers specifically before the `Read` tool is used. It checks if the file to be read is an environment file and returns a blocking error if it is, ensuring sensitive files are not read. It also includes logic to run the hook when executed directly.

```typescript
const preReadHook = defineHook({
  trigger: { PreToolUse: { Read: true } },
  run: (context) => {
    // context.input.tool_input is typed as { file_path: string; limit?: number; offset?: number; }
    const { file_path } = context.input.tool_input;

    if (file_path.includes(".env")) {
      return context.blockingError("Cannot read environment files");
    }

    return context.success();
  },
});

if (import.meta.main) {
  const { runHook } = await import("cc-hooks-ts");
  await runHook(preReadHook);
}
```

--------------------------------

### Define a hook with conditional execution based on platform

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/README.md

This TypeScript code defines a hook that only runs on macOS. The `shouldRun` function checks the `process.platform` property, ensuring the hook's logic is executed exclusively in the specified environment. The hook is triggered by the `Notification` event.

```typescript
import { defineHook } from "cc-hooks-ts";

const hook = defineHook({
  trigger: {
    Notification: true,
  },
  // Only run this hook on macOS
  shouldRun: () => process.platform === "darwin",
  run: (context) => {
    // Some macOS-specific logic like sending a notification using AppleScript
    return context.success();
  },
});
```

--------------------------------

### Define Claude Code Hooks with defineHook

Source: https://context7.com/sushichan044/cc-hooks-ts/llms.txt

Creates type-safe hook definitions by specifying triggers and handler functions. Supports conditional execution via shouldRun and handles various event types including tool usage and session lifecycle events.

```typescript
import { defineHook } from "cc-hooks-ts";

// Basic session start hook
const sessionHook = defineHook({
  trigger: { SessionStart: true },
  run: (context) => {
    console.log(`Session started: ${context.input.session_id}`);
    return context.success({
      messageForUser: "Welcome to your coding session!"
    });
  }
});

// Tool-specific PreToolUse hook
const readFileHook = defineHook({
  trigger: { PreToolUse: { Read: true } },
  run: (context) => {
    const { file_path } = context.input.tool_input;
    if (file_path.includes(".env")) {
      return context.blockingError("Access to sensitive files is not allowed");
    }
    return context.success();
  }
});

// Conditional execution
const macOnlyHook = defineHook({
  trigger: { Notification: true },
  shouldRun: () => process.platform === "darwin",
  run: (context) => context.success()
});
```

--------------------------------

### Define a hook for custom tool with type-safe inputs

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/README.md

This TypeScript code defines a hook for the custom tool `mcp__deepwiki__ask_question`. It leverages the extended `ToolSchema` to ensure `context.input.tool_input` is correctly typed. The hook checks if the question length exceeds a limit and returns a blocking error if it does.

```typescript
const deepWikiHook = defineHook({
  trigger: { PreToolUse: { mcp__deepwiki__ask_question: true } },
  run: (context) => {
    // context.input.tool_input is typed as { question: string; repoName: string; }
    const { question, repoName } = context.input.tool_input;

    if (question.length > 500) {
      return context.blockingError("Question is too long");
    }

    return context.success();
  },
});
```

--------------------------------

### Extend ToolSchema for type-safe custom tools in TypeScript

Source: https://context7.com/sushichan044/cc-hooks-ts/llms.txt

Developers can extend the ToolSchema interface to provide TypeScript inference for custom or MCP-defined tools. This ensures that tool inputs and responses are strictly typed within hook logic.

```typescript
import { defineHook } from "cc-hooks-ts";

declare module "cc-hooks-ts" {
  interface ToolSchema {
    mcp__deepwiki__ask_question: {
      input: { question: string; repoName: string; maxTokens?: number; };
      response: { answer: string; sources: string[]; };
    };
  }
}

const deepWikiHook = defineHook({
  trigger: { PreToolUse: { mcp__deepwiki__ask_question: true } },
  run: (context) => {
    const { question, repoName } = context.input.tool_input;
    if (question.length > 500) return context.blockingError("Limit exceeded");
    return context.success();
  }
});
```

--------------------------------

### Handle Blocking Errors with TypeScript

Source: https://context7.com/sushichan044/cc-hooks-ts/llms.txt

Implement blocking errors to halt Claude Code processing when security violations occur. This hook exits with code 2, providing an error message for Claude to handle. It requires the 'cc-hooks-ts' library.

```typescript
import { defineHook } from "cc-hooks-ts";

const securityHook = defineHook({
  trigger: { PreToolUse: { Read: true, Write: true, Edit: true } },
  run: (context) => {
    const toolInput = context.input.tool_input;
    const filePath = "file_path" in toolInput ? toolInput.file_path : "";

    // Block access to sensitive directories
    const blockedPaths = [".git/config", ".ssh/", "node_modules/.cache/"];
    for (const blocked of blockedPaths) {
      if (filePath.includes(blocked)) {
        return context.blockingError(
          `Security violation: Access to ${blocked} is prohibited. ` +
          `Please use a different approach.`
        );
      }
    }

    return context.success();
  }
});
```

--------------------------------

### Verifying Type Errors with assertType

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/docs/ai/vitest-typechecking-api-reference.md

The assertType function allows for direct type validation. When combined with the // @ts-expect-error directive, it can be used to confirm that specific type errors occur as expected, ensuring strict type safety.

```typescript
import { assertType } from "vitest";
import { createUser } from "./user-service";

test("type assertions", () => {
  const user = { name: "test" };

  // This passes because the type is correct.
  assertType<{ name: string }>(user);

  // Use with @ts-expect-error to assert that a type error *should* happen.
  // This test will pass because `name: 123` is not assignable to `{ name: string }`.
  // @ts-expect-error
  assertType<{ name: string }>({ name: 123 });
});
```

--------------------------------

### Extend ToolSchema for custom tool type safety

Source: https://github.com/sushichan044/cc-hooks-ts/blob/main/README.md

This TypeScript code extends the `ToolSchema` interface from `cc-hooks-ts` to provide type safety for custom tool inputs, specifically for MCP-defined tools like `mcp__deepwiki__ask_question`. It defines the expected input and response types for the custom tool.

```typescript
import { defineHook } from "cc-hooks-ts";

// Example: type-safe hooks for DeepWiki MCP Server tools
declare module "cc-hooks-ts" {
  interface ToolSchema {
    mcp__deepwiki__ask_question: {
      input: {
        question: string;
        repoName: string;
      };
      response: unknown;
    };
  }
}
```
Tokens:
Raw