Capture Agent Context with Your First Cursor Hook

Debugging Cursor Hooks with Output Panels

Simplify Cursor Hooks Configuration with JSON Schema

Level Up Cursor Hooks with TypeScript and Bun

Type-Safe Cursor Hooks with the cursor-hooks Package

Enforce Cursor Tooling Standards with beforeShellExecution

Automate Cursor Code Quality with afterFileEdit

Logging and Debugging Cursor Hooks

Cursor

Learn the art of automating your AI-assisted development workflow by building custom hooks that intercept, modify, and enhance how Cursor's AI agent interacts with your codebase.

## Course Overview

Cursor hooks are a powerful automation framework that allows you to run custom scripts in response to AI agent actions. This course takes you from creating your first simple hook to building a production-ready, type-safe automation system using TypeScript and Bun.

You'll learn how to intercept file operations, control shell executions, automatically format AI-generated code, and implement robust logging all while building practical, real-world integrations that enforce your project's standards and streamline your development workflow.

## What You'll Learn

- Set up and configure Cursor hooks in your projects
- Debug hook execution using Cursor's built-in logging tools
- Enable intelligent autocomplete with JSON schemas
- Build powerful TypeScript hooks using Bun
- Implement type-safe hook logic with official type definitions
- Enforce project tooling standards (e.g., bun vs npm)
- Automate code formatting and linting on AI edits
- Create robust logging and debugging systems for your hooks

## Prerequisites

- Basic familiarity with TypeScript/JavaScript
- Cursor IDE installed
- Bun runtime (installed during the course)
- Understanding of command-line tools

## Key Technologies

- **Cursor IDE**: AI-powered code editor with hooks support
- **Bun**: Fast JavaScript runtime and toolkit
- **TypeScript**: Type-safe language for reliable automation
- **cursor-hooks**: Official type definitions package
- **JSON Schema**: Validation and autocomplete for configuration

## Learning Approach

Each lesson builds on the previous one, progressively enhancing your hook system from basic shell scripts to a sophisticated, type-safe automation framework. You'll write real code, see immediate results in your editor, and build a toolkit of reusable patterns for automating your AI-assisted development workflow.

By the end of this course, you'll have the skills to create custom hooks that make Cursor work exactly the way you want, enforcing standards, automating tedious tasks, and integrating seamlessly with your existing development tools.


cursor

Advanced Cursor Hooks

Cursor hooks provide a powerful way to run custom scripts in response to AI agent actions, giving you the ability to intercept workflows, inject context, or trigger automations. This lesson introduces the fundamental mechanics of hooks through the `beforeReadFile` event, which executes a command just before the AI agent accesses a file.

You'll configure the `.cursor/hooks.json` file, write a simple shell script to capture the JSON payload sent by the hook, and examine the rich contextual data it contains—details like file path, content, and conversation ID. This data opens up endless possibilities for automation and workflow enhancement.

A critical and often-missed step is making your script executable with `chmod`. Without this, your hooks will fail silently, and you'll wonder why nothing is working. By the end of this lesson, you'll have a working hook and understand the foundation for building more sophisticated automations.

### The Configuration: `hooks.json`

First, create a `.cursor` directory in your project root and add a `hooks.json` file. This file defines which scripts to run for specific events. For this example, we'll run a `debug.sh` script every time the `beforeReadFile` event is triggered.

~~~json
{
  "version": 1,
  "hooks": {
    "beforeReadFile": [
      {
        "command": "./debug.sh"
      }
    ]
  }
}
~~~

### The Script: `debug.sh`

Next, create the `debug.sh` script inside the `.cursor` directory. The hook will pass a JSON payload to this script via standard input. We can capture this payload by redirecting `stdin` to a file.

~~~bash
cat > stdin.json
~~~

### The Critical Step: Making it Executable

For the hook to successfully run the script, the script file must have execute permissions. This is a common point of failure. Open your terminal and run the following command:

~~~bash
chmod +x .cursor/debug.sh
~~~

### Triggering the Hook

Now, you can ask the agent to perform an action that reads a file.

~~~markdown
Please read the debug file.
~~~

After the agent attempts to read the file, the hook will execute, and you will find a new `stdin.json` file in your `.cursor` directory.

### The Result: The Captured Payload

The generated `stdin.json` file contains a wealth of information about the event, including the conversation context and details about the file being accessed. This data can be parsed and used in more complex scripts to build powerful automations.

~~~json
{
  "conversation_id": "b962916e-5236-47e9-a469-9b4ac8847737",
  "generation_id": "fbf381f2-40b6-4b4c-9642-4bdbfd618fc2",
  "content": "cat > stdin.json",
  "file_path": "/Users/johnlindquist/dev/cursor-hooks-lessons/.cursor/debug.sh",
  "attachments": [],
  "hook_event_name": "beforeReadFile",
  "workspace_roots": ["/Users/johnlindquist/dev/cursor-hooks-lessons"]
}
~~~

[00:00] To set up our first cursor hook we're going to create a cursor directory with a hooks.json file inside of it. And once we create that, this has a couple requirements. It needs a version, which we'll set to version 1, and then it needs a hooks property, which is an object, where we define what will trigger the hook. So for our simple example we'll use before read file which will trigger any time the agent is going to read a file. Then before read file will be an array of objects with commands in them and all of these commands can run each time a file is read.

[00:32] So that means we need to create this script of debug.sh which is going to live next to the hooks.json file because it's critical to remember that all of these scripts will be relative to the hooks.json file not the project root. So we'll create a debug.sh and all we're going to do here is essentially redirect standard in to a JSON file. By redirect I mean this script will receive an object. If you think of a hook or callback or event handler in JavaScript, they always receive a payload and that's being passed to the script and in Bash this just redirects it into this file. So you'll see that in action when we tell the agent please read the debug file.

[01:16] We'll hit enter and then you'll see nothing happens because we missed the critical step of making this file executable. So to make a file executable we use chmod plus X and then the path to the file which is .cursor slash debug. Hit enter and I can say please try that again. And you'll see now that the file was executable, the hook was able to run and create this object which has the payload. I'll go ahead and format it, which has the payload of the conversation ID, generation ID, the file path that it read, and the content of that file path so that you can take actions in your script based on this object.



https://app.egghead.io/api/v1/lessons/capture-agent-context-with-your-first-cursor-hook~uscfo/transcript

When hooks don't work as expected, debugging can be frustrating. The basic execution log in Cursor's settings confirms whether your script ran, but it doesn't show what data was sent or what your script returned. This lesson reveals where to find the comprehensive logs that expose the complete input and output of your hook scripts, making debugging straightforward and efficient.

## The First Check: Hooks Settings

Your first stop should be the Cursor settings to confirm your hook is configured correctly.

1.  Open Cursor Settings (Cmd/Ctrl + ,).
2.  Search for "hooks".
3.  This view will show your **Configured Hooks** and a basic **Execution Log**.

This log is useful for confirming that Cursor is *attempting* to run your script, but it doesn't show the data being passed or any errors from the script itself. If your hook appears here but isn't behaving correctly, you need to dig deeper.

## Deep Dive Debugging: The Output Panel

The key to effective debugging is the **Output** panel, which provides a detailed, real-time log of hook executions.

**To access the hooks log:**

1.  Open the bottom panel in Cursor (where the Terminal, Problems, etc., are located).
2.  Click on the **Output** tab.
3.  In the dropdown menu on the right side of the panel, select **Hooks**.

Here you will see a detailed log for each time a hook is triggered, including the full `INPUT` JSON payload sent to your script and the `OUTPUT` it returned. This is essential for understanding what data your script is receiving and how it's responding.

For example, when the instructor triggers a file read, the log shows the execution of the `debug.sh` script:

~~~bash
Command: ./debug.sh (8ms) exit code: 0
~~~

It also reveals the full JSON payload that was piped to the script as standard input:

~~~json
INPUT:
{
  "conversation_id": "b962916e-5236-47e9-a469-9b4ac8847737",
  "generation_id": "956dc636-6693-490a-a228-29226a0aadde",
  "content": "{\n  \"version\": 1,\n  \"hooks\": {\n    \"beforeReadFile\": {\n      \"command\": \"./debug.sh\"\n    }\n  }\n}\n",
  "file_path": "/Users/johnlindquist/dev/cursor-hooks-lessons/.cursor/hooks.json",
  "attachments": [],
  "hook_event_name": "beforeReadFile",
  "workspace_roots": [
    "/Users/johnlindquist/dev/cursor-hooks-lessons"
  ]
}
~~~

The `debug.sh` script in this lesson simply captures this input:
~~~bash
cat > stdin.json
~~~

By monitoring this output, you can debug your scripts by seeing exactly what Cursor is sending them, which is critical for fixing logic errors or handling different event payloads. The Hooks output panel becomes your debugging console, showing you everything you need to diagnose issues.

Test this by asking the AI to read a file:
~~~markdown
Please read my hooks.json file.
~~~

The hook triggers immediately, and a new entry appears in the Hooks output log, allowing you to inspect the data in real-time and verify your hook is receiving the correct information.

[00:00] Before diving any further, make sure and go into your cursor settings and then search for hooks. And once you hit enter, you'll be brought to a page which shows, let me collapse the UI here, which shows your configured hooks and the execution log. So if you don't see these showing up inside of your cursor hooks logs then your file is not being executed and something is misconfigured. If you click on this it'll just take you to the file it doesn't give you any more information. So to really dive into the information of the run, if you go down to where you normally open your terminal and go to output, you can go to the hooks in the drop-down menu and you can scroll back in here or even watch this live where it shows the input and the output.

[00:46] So you'll see if I run please read my hooks.json file and we watch this over here. We'll see if we scroll down we now see it ran the command and the input this time was the hooks.json file with its content and no output. So to really debug your scripts make sure that they are properly configured and they show up in your hook settings and then whenever you expect them to run make sure they're showing up in the output panel under the hooks drop-down and you can see when they're run, their input, and their output.



https://app.egghead.io/api/v1/lessons/debugging-cursor-hooks-with-output-panels~jpirn/transcript

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
{
  "json.schemaDownload.enable": true,
  "json.schemas": [
    {
      "fileMatch": [
        ".cursor/hooks.json"
      ],
      "url": "https://unpkg.com/cursor-hooks/schema/hooks.schema.json"
    }
  ]
}
~~~

vscode

[00:00] Now a major convenience to set up is a schema file for your Hooks.json so you can get autocomplete, IntelliSense, and warnings and such as you're configuring your hooks. Now we can do this by opening our user.json settings. So this will apply to every project. And then if you just scroll down to the bottom I'll give you this code which you can copy and paste where the keys are to enable schema download to true and then to file match any .cursor.hooks.json file to this schema. Now this schema when we open it is one I put together by referencing the cursor docs around hooks since they haven't published an official one yet.

[00:38] And I assume once they publish an official one you'll just want to delete this block here. But for now you can see how the schema marks version and hooks as required and lists all of the available hooks that can be called. And the hooks arrays all have items with hook definitions which have commands on them. So in our JSON file we'll be able to add a hook like before submit prompt. We'll be able to get auto-complete.

[01:04] You'll see missing property command because these objects require a command, and it just makes it infinitely easier to configure these files however you need.



https://app.egghead.io/api/v1/lessons/simplify-cursor-hooks-configuration-with-json-schema~cqtlr/transcript

Bash scripts work for basic hooks, but they quickly become unwieldy when you need to parse JSON, implement complex logic, or maintain the code over time. This lesson transforms your hook development workflow by introducing Bun—a fast JavaScript runtime that lets you write hooks in TypeScript.

You'll set up a dedicated Bun project for your hooks, learn how to handle the JSON payloads Cursor provides, and return properly formatted responses to control the AI's behavior. This approach gives you the full power of TypeScript and the Node.js ecosystem, making your hooks more maintainable, testable, and powerful.

### Key Benefits:

*   Write hooks in a familiar, strongly-typed language (TypeScript).
*   Avoid the complexities of shell scripting and JSON manipulation in Bash.
*   Leverage the entire Node.js/Bun ecosystem within your hooks.
*   Simplify setup, as `bun run` handles script execution without needing `chmod`.

### Building Your First TypeScript Hook

The workflow is straightforward. You'll create a dedicated directory for your hooks, initialize a Bun project, and write a TypeScript script that demonstrates controlling the AI.

1.  **Initialize a Bun Project:** Create a `.cursor/hooks` directory and initialize a new Bun project within it. This gives you a dedicated environment for your hook logic with TypeScript support out of the box.

    ~~~bash
    mkdir .cursor/hooks
    cd .cursor/hooks
    bun init
    ~~~

2.  **Configure `hooks.json`:** Update your `.cursor/hooks.json` to execute the TypeScript script using `bun run`. This command points to the entry file generated by Bun.

    ~~~json
    {
      "version": 1,
      "hooks": {
        "beforeSubmitPrompt": [
          {
            "command": "bun run hooks/index.ts"
          }
        ]
      }
    }
    ~~~

3.  **Handle Hook Output:** Each hook type expects a specific JSON response structure. For `beforeSubmitPrompt`, you return an object with a `continue` property. Setting it to `false` blocks the AI from processing the prompt—a powerful demonstration of controlling the AI's behavior.

    ~~~typescript
    const output = {
      continue: false,
    };

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

With this foundation in place, you can create sophisticated automations that integrate seamlessly with Cursor, all while working in a familiar TypeScript environment with full access to the Node.js ecosystem.

### Prompts Used

~~~markdown
Do anything
~~~

~~~markdown
Please say hello
~~~

[00:00] So now because nobody likes to write bash or manipulate JSON in bash, we're going to create a directory called .cursor/.hooks and in this directory we're going to bun and knit a project. And then instead of invoking this debug script we're going to use this before submit prompt, remove before read file, and tell this to run bun run. And remember that this is relative to the hooks.json file So it'll be hooks and then index.ts. So we'll say hooks and index.ts. And then if we simply run anything in the agent and we hop over to the output hooks output, I'm going to clear this for now.

[00:45] I'll say do anything, hit enter, and you'll see it at least tried to run this file. Now all the errors come from the fact that it's expecting JSON as the output, but you can see that it at least logged the input. Now if you take a quick peek at the cursor docs you'll see that the expected output for before submit prompt is an object with continue set to true or false. So I'm going to say in our script, and I'll reject these changes of whatever it tried to do when I asked it to do anything, I'm going to say that the output is an object with continue set to false. And instead of logging out this string we're going to log out the JSON version of the output.

[01:31] Meaning that if we attempt to run another prompt inside of our agent, I'll try please say hello, hit enter, you'll see that our hook successfully blocked any submission from running. Then if we look down in our output you can see the output was continue false and that we ran the hook with a valid response. Then the final thing to note here is that because we're now using bun run inside of our command, we no longer have to worry about making scripts executable since bun is executable by default.



https://app.egghead.io/api/v1/lessons/level-up-cursor-hooks-with-type-script-and-bun~sqo8a/transcript

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.
~~~bash
bun install cursor-hooks
~~~

### Prompts

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

A test prompt that includes the required keyword to be allowed by the hook.
~~~markdown
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.

~~~typescript
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.

[00:00] So back in our hooks directory where we initialized a blank bun project, I'll clear this out real quick, and I'm going to bun install a project I put together called cursor-hooks, which has typings for all of the hooks based on the documentation. And for a little bit more organization, let's rename index to before submit prompt. Then in our hooks, rename this to before submit prompt. Then in our before submit prompt script, we can now import some types like the before submit prompt response, and we can type our output to that, meaning that we'll get IntelliSense for continue, so we can be much more confident in the hooks we're building. Now the main reason we're using bun is because bun has something called bun.standardIn() with a JSON method on it, which converts the standard in to JSON in this single line.

[00:57] So the input can be this, and then we can type the input as a beforeSubmitPrompt payload. We'll let that automatically import. And now we can define continue as if the input prompt, and you'll see we get autocomplete for all this, includes allow, then continue will be true. If it doesn't include allow continue will be false. So open our agent we'll say jump, hit enter, it's blocked.

[01:24] We'll say allow jump, hit enter, and now you see it starts trying to do this action. We'll just reject this sample use case And you'll see we now have a typed version of the input and the output where we can easily add conditions around the prompt that's being submitted and whether or not to allow that prompt to actually continue.



https://app.egghead.io/api/v1/lessons/type-safe-cursor-hooks-with-the-cursor-hooks-package~6ba9w/transcript

Relying on documentation or repeated corrections to enforce project tooling standards is tedious and unreliable. The AI might default to common commands like `npm` instead of your preferred tool, and you find yourself constantly correcting it. There's a better way to enforce these standards automatically.

This lesson shows you how to build a `beforeShellExecution` hook that intercepts every shell command the AI attempts to run. You'll inspect the command, decide whether to allow or deny it, and send custom feedback that guides the AI to use the correct tools—all automatically, with zero manual intervention.

### The Goal: Automated Tooling Enforcement

The hook you'll build accomplishes three things:
1.  Detects when the AI attempts to run a command using `npm`
2.  Denies permission for that command to execute
3.  Sends a custom message back to the AI explaining that `bun` must be used instead

The AI receives this feedback instantly and retries the command using the correct tool. Your project standards are enforced automatically, with no manual corrections needed.

### Hook Implementation

The process involves creating a TypeScript file for our hook's logic and registering it in Cursor's `hooks.json` configuration.

First, we register the hook in `.cursor/hooks.json`:

~~~json
{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": "bun run hooks/before-shell-execution.ts"
      }
    ]
  }
}
~~~

The hook logic in `hooks/before-shell-execution.ts` receives a payload with the command to be executed and returns a response with `permission` (`"allow"` or `"deny"`) and an optional `agentMessage`.

A simple `startsWith` check isn't enough—commands can be chained like `cd /path/to/project && npm install`. The solution is to check both whether the command starts with `npm` and whether it contains ` npm ` (with spaces) anywhere in the string.

Here's the complete implementation:

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

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

const startsWithNpm = input.command.startsWith("npm") || input.command.includes(" npm ");

const output: BeforeShellExecutionResponse = {
  permission: startsWithNpm ? "deny" : "allow",
  agentMessage: startsWithNpm ? "npm is not allowed, always use bun instead" : undefined,
};

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

### Seeing it in Action

When you ask the AI to install a package, it might default to using `npm`:

~~~markdown
npm install lodash
~~~

The hook intercepts the command, denies execution, and sends back the custom message explaining that `bun` is required. The AI reads this feedback and immediately retries the command using `bun`—all automatically.

This demonstrates the power of intelligent guardrails: the AI learns your project's rules on the fly, adapting its behavior without any manual corrections. Your standards are enforced seamlessly, creating a smoother, more reliable development experience.

[00:00] Now with everything we've learned so far let's create a before shell execution hook here. So before shell execution and wire it up to our hooks. So drop it here before shell execution and the command will point to our script we're setting up. Then close this out, collapse this, and we'll bring in the proper types. So before shell execution payload and response, then type these.

[00:32] I'm just hitting tab now. So now we have this template we can use that's fully typed with an input and an output so we can customize what to do based on the payload. So the response is going to allow us to set the permission And our goal here is to deny anytime someone uses NPM and force the agent to use bun instead. So I'm going to say permission and we'll check the input.command and we'll say starts with NPM. So if it starts with npm we will deny, otherwise we will allow.

[01:05] And then similarly we'll hop over to the agent message. I'll just tab complete this. So we'll say npm is not allowed, always use bun instead. Then we'll quickly extract starts with npm, hit tab to replace that. And now if I attempt to run this, this would actually be blocked still because I'd always have to say allow.

[01:27] So I'm going to disable this hook real quick. So the only available hook is the shell execution hook. So hop over the agent. I'll just say npm install lodash. Hit enter.

[01:38] And we actually ran into a scenario where the command actually started with cd. So this is a good catch where I'll have to say or input command includes space npm space. Now if I jump over the agent and try it again, npm install lodash, hit enter, you'll see that we switched from lodash to bun because up here we get command execution was blocked by a hook. Behind the scenes it got this message that npm is not allowed, always use bun, so it switched, and then it automatically swapped over to bun. So Whereas in the past you might have included this inside of some sort of cursor rule, now you can inject rules just in time whenever specific text is detected.



https://app.egghead.io/api/v1/lessons/enforce-cursor-tooling-standards-with-before-shell-execution~8lpc4/transcript

AI-generated code often misses your project's formatting and linting standards. You find yourself running manual fixes after every AI edit, breaking your flow and risking inconsistent code. Instead of treating formatting as a manual cleanup step, you can make it automatic.

This lesson shows you how to use the `afterFileEdit` hook to automatically run your linter or formatter—like Biome, Prettier, or ESLint—every time the AI modifies a file. The hook detects which file was changed, checks if it matches your criteria (e.g., TypeScript files), and executes your formatting tool on it. Code quality standards are enforced instantly and automatically, with zero manual intervention.

### Hook Configuration

First, you need to tell Cursor which script to run after a file is edited. This is done in the `.cursor/hooks.json` file. Here, we define an `afterFileEdit` hook that executes our TypeScript script using Bun.

~~~json
{
  "version": 1,
  "hooks": {
    "afterFileEdit": [
      {
        "command": "bun run hooks/after-file-edit.ts"
      }
    ]
  }
}
~~~

### Implementing the Hook Logic

The hook receives a payload with information about the edited file. You parse this to get the file path, check if it matches your criteria (like a `.ts` extension), and if so, run your formatting tool on it.

Bun's `Bun.$` syntax makes running shell commands from TypeScript elegant and safe—perfect for executing your linter or formatter.

~~~typescript
import type { AfterFileEditPayload } from "cursor-hooks";

// Read the payload from standard input
const input: AfterFileEditPayload = await Bun.stdin.json();

// Check if the edited file is a TypeScript file
if (input.file_path.endsWith(".ts")) {
  // Run the Biome linter/formatter on the file
  const result = await Bun.$`bunx @biomejs/biome lint --fix --unsafe ${input.file_path}`;
  
  // Log the output for debugging purposes
  console.log(JSON.stringify(result.stdout, null, 2));
}
~~~

### Seeing it in Action

Ask the AI to make a code change:

~~~markdown
add a const foo = "bar"
~~~

The moment the AI applies the edit, your hook triggers automatically in the background. The formatter runs, applies your project's style rules, and the code is cleaned up—all without you doing anything. Your code stays consistent and follows your standards automatically.

#### Terminal Commands

Initialize a new Bun project in your workspace root.

~~~bash
bun init
~~~

This is the underlying command our hook script runs to format a specific file.

~~~bash
bunx @biomejs/biome lint --fix --unsafe index.ts
~~~

[00:00] Now we're going to bun init in the root of the project and set up a blank project so that we have an index.ts file. Then we'll set up a hook for after file edit. Let tab complete the command and then create our after file edit file. After file edit hook here. And bring in all of the proper types.

[00:25] After file edit payload and after file edit response. Hit tab to replace all of these. So now we have our template set up for what to run after any time a file is edited. So the scenario we're going to set up is if the input file path ends with TypeScript, then we're going to run a formatting command. And we're going to do that in bun with bun$ and then backticks here.

[00:51] And we'll just use a biome command of bunx at biome.js, biome, and lint, and fix, and unsafe. And we'll target that input file path. Then we'll await this and get back the result from this. And then according to the docs the after file edit is just void, so we really don't get a chance to say anything back to the agent. We just get to run this command, and I'm just going to console.log the JSON stringify result of the standard out, just so that at least shows up in my hooks log.

[01:32] So now if I look at my index.ts, open an agent and say add a const foo equals bar. Then we'll also watch the output to see this happen. Let's clear this out. Hit enter here. You'll see that it added const foo equals bar, and then our formatting tool for after file edit executed our hook.

[01:58] We got the original content and then the new content. And you'll see the new content we got did not have this underscore. But if you run biome on that file, let's try it again, we'll keep this, remove this, you'll see that if we run our after file edit command here, we'll just paste it down here, and point this to the index.ts, go back to our index, you'll see once we hit enter that it changed it from normal foo to underscore foo.



https://app.egghead.io/api/v1/lessons/automate-cursor-code-quality-with-after-file-edit~nczsu/transcript

Debugging hooks can be confusing at first. Using `console.log` doesn't work because stdout is reserved for communicating with the AI. You need a different approach for both quick debugging and production-ready logging.

This lesson takes you from quick debugging with `console.error` to building a robust, persistent logging system using JSONL files. You'll learn why certain outputs are silent, how to see immediate debug information, and how to create a production logging solution with automatic log rotation—all with the AI's help.

## The Immediate Fix: Use `console.error`

The simplest way to see debug output from your hooks is to use `console.error` instead of `console.log`. This directs your log messages to standard error (`stderr`), which Cursor displays in the "Hooks" output panel.

```typescript
// This will be silent in the output panel
console.log(JSON.stringify(output, null, 2));

// This will appear in the STDERR section of the output panel
console.error(JSON.stringify(output, null, 2));
```

While effective for quick checks, this method's output is transient and can be lost among other messages. For more reliable debugging, a persistent logging solution is necessary.

## Building a Persistent Log File

For production hooks, you need a complete history of what your hooks have done. Writing logs to a dedicated file gives you this history, making complex debugging much easier.

The JSON Lines (`.jsonl`) format is ideal for hook logging. Each line is a complete, valid JSON object, and you can append new entries indefinitely. This format is both human-readable and easy to process with tools.

The implementation is straightforward:
*   Create a `logs` directory in your project
*   Use Node.js's `fs/promises` and `path` modules to append data
*   Enrich each log entry with timestamps and the full input payload for context

```typescript
import { appendFile } from "node:fs/promises";
import { join } from "node:path";

// ... inside your hook logic
const output = {
    timestamp: new Date().toISOString(),
    ...input, // Include the full input payload for context
    stdout: result.stdout.toString(),
    stderr: result.stderr.toString(),
    exitCode: result.exitCode,
};

const logFilePath = join(input.workspace_roots[0]!, "logs", "after-file-edit.jsonl");
await appendFile(logFilePath, JSON.stringify(output) + '\n');
```

## Automating Log Management with AI

Log files grow forever if left unchecked, consuming disk space and becoming unwieldy. Instead of manually implementing log rotation, you can ask the AI to build it for you.

Give the AI your logging code and a clear instruction:

~~~markdown
Once there are over 500 JSON objects in this file, please remove the first 100 to keep this log rolling.
~~~

The AI will generate code to count entries, trim old ones when the threshold is reached, and keep your logs at a manageable size. You can iterate with the AI to refine the logic—like ensuring the counting method correctly handles only top-level objects, not nested ones.

This demonstrates a powerful workflow: using Cursor's AI to build the very automation that manages Cursor's hooks. The AI becomes your co-pilot for creating production-ready hook systems.

## Don't Forget: `.gitignore`

Always add your logs directory to `.gitignore` to prevent committing large or sensitive log files:

```
# .gitignore
logs/
```

With this complete logging strategy, you have both immediate debugging visibility and a persistent, manageable history. Your hooks become production-ready—reliable, observable, and easy to troubleshoot when issues arise.

---
### Prompts

~~~markdown
@index.ts Please add some comments.
~~~

~~~markdown
Add some more comments
~~~

~~~markdown
remove all the comments
~~~

~~~markdown
Add the comments back
~~~

~~~markdown
remove the comments again
~~~

~~~markdown
Once there are over 500 JSON objects in this file, please remove the first 100 to keep this log rolling.
~~~

~~~markdown
Make sure this is only checking an opening brace on a new line to avoid matching nested objects.
~~~

### Code Snippets

~~~typescript
// Use console.error for debugging output in hooks
console.error(JSON.stringify(output, null, 2));
~~~

~~~typescript
// Import Node.js modules for file operations
import { appendFile, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";
~~~

~~~typescript
// Setup for logging to a JSON Lines file
const output = {
    timestamp: new Date().toISOString(),
    ...input,
    stdout: result.stdout.toString(),
    stderr: result.stderr.toString(),
    exitCode: result.exitCode,
};

const logFilePath = join(input.workspace_roots[0]!, "logs", "after-file-edit.jsonl");
await appendFile(logFilePath, JSON.stringify(output) + '\n');
~~~

~~~typescript
// Refined regex to count top-level JSON objects at the start of a line
const entryCount = (logContent.match(/^s*{/gm) || []).length;
~~~

[00:00] Now you'll notice in the output if you use console.log and we're just going to log out essentially what the result gave us back. I'll open an agent, I'll point to our index and say please add some comments, hit enter. You'll notice that the output is empty and there's no log of what happened even though we are using console.log, since console.log is essentially reserved for standard out, which would typically be a way of pushing messages back to the agent, but that's not supported yet in after file edit hooks, even though I hope that someday it will be. So what you need to do is switch this over to console error and I'll say add some more comments. Now once this runs, now you'll see if we scroll down that we have standard error in the logs where we have the entirety of standard out.

[00:49] Standard error for this command was empty with an Xcode of 0 meaning it passed successfully. Now what I recommend doing is setting up a logs directory somewhere in your project or somewhere in your system. We're going to take the most basic approach and create a logs directory here. Now we're just going to use node's file system methods here. So we're going to import from nodefs promises and grab append file so that we can set up a log file path.

[01:19] And this can be the input workspace routes. And we'll grab the first route. And then to properly resolve this, let's also import some path utils. So we'll join from node path and refactor this. And since we know workspace roots, zero is always defined, we'll just go ahead and force it.

[01:39] And the format I'm gonna use here, instead of biome.log, we'll just call this after file edit. And instead of .log, we're gonna use a format called JSONL, which means it's simply lines of JSON objects. So instead of one large JSON file, every line in it is a separate JSON object. So when we append to this file we're just going to append JSON objects, which are the result of our formatter. So now if I say remove all the comments, hit enter, we can now check our logs.

[02:10] You'll see an after file edit JSONL file, and then every time this is run we get a new JSON object. I'll say add the comments back, and you see we get JSON objects every single time. Now I'm also going to add a timestamp here just so we can fully capture the history of these, and it certainly makes sense to grab the information off of the input as well. Then I'll say remove the comments again. And now we have a proper log of every time our after file edit runs we have these objects which if something goes wrong we could copy paste this into an agent and tell it to please fix or follow up or take care of whatever happened that went wrong and we have enough context and data to work with.

[02:53] Now I fully understand that logs are always much more complicated than you think because you have to worry about file size limits and retention like if you should keep old dogs and compress them and store them somewhere. There are a lot of popular logging libraries out there like Pino. It really depends on what your goals are for the log. For our simple scenario I'm going to select these lines, Ask the agent, once there are over 500 JSON objects in this file, please remove the first 100 to keep this log rolling. Hit enter.

[03:25] Let an agent do all the work for us. And I will check out the work myself. We need to import readfile. Looks like it imported the wrong Read file, so we need read file from promises Then back down. We'll fix the append file and then this looks pretty legit to me as far as counting the JSON objects, but I do think this needs to account for...

[03:53] Make sure this is only checking an opening brace on a new line to avoid matching nested objects. And then this looks much better than the last time, but I'm not going to worry about it too much. Just be aware that once you start adding logs and agents are going to be updating a lot of TypeScript files, your logs get long. So whether you roll your own log management or you use a library, whatever works best for you. And last thing, please make sure to add your logs directory to your gitignore.

[04:25] We haven't initialized this project yet, but once it's initialized, we do not want this being checked in and having a billion logging conflicts.



https://app.egghead.io/api/v1/lessons/logging-and-debugging-cursor-hooks~j0yh2/transcript

Advanced Cursor Hooks

John Lindquist

Course Overview

What You'll Learn

Prerequisites

Key Technologies

Learning Approach

Free Community Resource

Free Community Resource

Course Content