Debugging Cursor Hooks with Output Panels

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:

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

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

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:

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:

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.