Type-Safe Cursor Hooks with the cursor-hooks Package

Writing hooks without type safety means you're guessing at property names, relying on documentation for payload structure, and hoping your response format is correct. Every hook becomes an exercise in trial and error, with no editor assistance to guide you.

This lesson introduces the cursor-hooks package, which provides complete TypeScript definitions for all hook payloads and responses. Combined with Bun's elegant Bun.stdin.json() method for reading input, you'll write hooks with full autocomplete support, compile-time error checking, and absolute confidence that your code is correct.

The Power of Types

• Autocomplete Everything: See available properties as you type, with no need to reference documentation.
• Catch Errors Early: TypeScript catches typos and invalid property access before you run your code.
• Self-Documenting Code: Type definitions serve as inline documentation, making hooks easier to understand and maintain.
• Elegant Input Handling: Bun's Bun.stdin.json() reads and parses hook input in a single, clean line of code.

Building a Type-Safe Hook

The workflow is simple and produces reliable, maintainable code:

1. Install Dependencies: Add the cursor-hooks package to your Bun project for complete type definitions.
2. Read Typed Input: Use await Bun.stdin.json() and apply the appropriate payload type (e.g., BeforeSubmitPromptPayload).
3. Build Typed Output: Create your response object with the correct response type (e.g., BeforeSubmitPromptResponse).
4. Implement Logic: Write conditional logic based on the typed input—your editor will guide you with autocomplete at every step.
5. Test Immediately: Test the hook directly in Cursor's chat interface to see your logic in action.

Commands

Install the package providing TypeScript types for Cursor hooks.

bun install cursor-hooks

Prompts

A test prompt that will be blocked by the hook's logic.

jump

A test prompt that includes the required keyword to be allowed by the hook.

allow jump

Example Implementation

This before-submit-prompt.ts script shows the elegance of type-safe hooks. Notice how the types guide the entire implementation—from reading the payload to building the response.

import type { BeforeSubmitPromptPayload, BeforeSubmitPromptResponse } from "cursor-hooks";

const input: BeforeSubmitPromptPayload = await Bun.stdin.json();

const output: BeforeSubmitPromptResponse = {
  continue: input.prompt.includes("allow"),
};

console.log(JSON.stringify(output, null, 2));

With types in place, your editor becomes a powerful assistant, showing you exactly what properties are available on the input and what shape your output must take. This transforms hook development from guesswork into a guided, confident process.