Cursor Hooks

cursor-hooks

TypeScript definitions and helpers for building [Cursor agent hooks](https://cursor.com/docs/agent/hooks).

Installation

1. Create a hooks directory in your project

mkdir -p .cursor/hooks
cd .cursor/hooks

2. Initialize a Bun project

Install [Bun](https://bun.sh/) if you haven't already, then initialize:

bun init -y

3. Install cursor-hooks

bun install cursor-hooks

4. Create a hooks.json configuration

In your `.cursor` directory (at the project root), create a `hooks.json` file.

**Important:** Hook command paths are relative to the `.cursor/hooks.json` file location.

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": "bun run hooks/before-shell-execution.ts"
      }
    ],
    "afterFileEdit": [
      {
        "command": "bun run hooks/after-file-edit.ts"
      }
    ]
  }
}

This configuration assumes your hooks are in `.cursor/hooks/` and the `hooks.json` is at `.cursor/hooks.json`.

5. Enable JSON Schema validation (optional)

You can enable schema validation in two ways:

**Option A:** Add `$schema` directly to your `hooks.json`:

{
  "$schema": "https://unpkg.com/cursor-hooks@latest/schema/hooks.schema.json",
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      { "command": "bun run hooks/after-file-edit.ts" }
    ]
  }
}

**Option B:** Configure it globally in your Cursor settings (`~/Library/Application Support/Cursor/User/settings.json` on macOS):

{
  "json.validate.enable": true,
  "json.format.enable": true,
  "json.schemaDownload.enable": true,
  "json.schemas": [
    {
      "fileMatch": [".cursor/hooks.json"],
      "url": "https://unpkg.com/cursor-hooks/schema/hooks.schema.json"
    }
  ]
}

Real-world Examples

Example 1: Block npm commands, enforce bun

`before-shell-execution.ts`:

import type { BeforeShellExecutionPayload, BeforeShellExecutionResponse } from "cursor-hooks";