Agent file_read log

Support Help
1

Is it possible to get a file read log from Cursor IDE, or do I need to create my own spy script?

I want to create a read heatmap.

6

You don’t need a custom spy script - Cursor’s hooks system can do this natively.

The best fit for a read heatmap is postToolUse with a "Read" matcher. It fires after every agent file read and gives you the file path, duration, and output as JSON on stdin. Here’s a minimal setup:

.cursor/hooks.json (project-level) or ~/.cursor/hooks.json (global):

{
"version": 1,
"hooks": {
"postToolUse": [
{
"matcher": "Read",
"command": ".cursor/hooks/log-read.sh"
}
]
}
}

.cursor/hooks/log-read.sh:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.path // .tool_input.file_path // "unknown"')
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
DURATION=$(echo "$INPUT" | jq -r '.duration // "n/a"')
echo "$TIMESTAMP|$FILE_PATH|${DURATION}ms" >> .cursor/read-heatmap.log

Make it executable with chmod +x .cursor/hooks/log-read.sh, and you’ll get a timestamped log of every agent file read.

A couple of things to keep in mind:

  • This covers agent reads only. For Tab completion reads, add a separate beforeTabFileRead hook.

  • Manual file opens (Cmd+P, clicking in the sidebar) are not covered by hooks — they only fire for agent and Tab tool invocations.