Simplify Cursor Hooks Configuration with JSON Schema

Editing raw JSON for your hooks configuration is tedious and error-prone. You have to remember exact hook names, required properties, and valid values—all without any guidance from your editor. There's a simple solution that transforms this experience completely.

This lesson shows you how to add a single configuration block to your user settings that enables IntelliSense for all your hooks.json files. You'll get autocomplete suggestions, inline documentation, validation warnings, and hover hints—making hook configuration fast, reliable, and pleasant.

The Solution: json.schemas

By adding the following snippet to your user settings.json, you instruct Cursor (and VS Code) to download and apply a schema to any file named hooks.json within a .cursor directory.

This configuration enables several key features:

• Autocomplete: Get suggestions for valid hook names like beforeReadFile or beforeSubmitPrompt.
• Validation: See warnings for missing required properties (like command) or incorrect data types.
• IntelliSense: Hover over properties to see descriptions and expected values.

This small setup transforms hook configuration from tedious and error-prone to fast and reliable across all your projects.

How it Works

1. Open User Settings (JSON): Use the command palette to open your global settings.json file.
2. Add the Schema Configuration: Paste the provided JSON block into your settings. This enables schema downloading and creates the file association.
3. Start Using IntelliSense: Open any .cursor/hooks.json file and start typing—autocomplete suggestions will appear immediately.

The schema used here is based on Cursor's documentation and hosted on unpkg. If Cursor releases an official schema in the future, you can simply update the URL.

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