Cursor | Respan Docs

Cursor is an AI-powered code editor with built-in agent capabilities. Respan gives you hierarchical traces of every agent interaction including thinking blocks, file edits, shell commands, and MCP tool calls — captured in real-time via Cursor’s hook system.

Set up Respan

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

Example projects

Cursor hook source

Tracing

Setup

Prerequisite: Cursor IDE installed, plus Python 3.8+ with requests.

Set environment variables

Add to your shell profile (.bashrc, .zshrc, or PowerShell $PROFILE):

$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
$ export TRACE_TO_RESPAN="true"

Download the hook script

$ mkdir -p ~/.cursor/hooks
$ curl -o ~/.cursor/hooks/respan_hook.py \
>   https://raw.githubusercontent.com/respanai/respan-example-projects/main/python/dev-tools/cursor/respan_hook.py

Configure Cursor hooks

Create ~/.cursor/hooks.json:

1 {
2   "version": 1,
3   "hooks": {
4     "beforeSubmitPrompt": [{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
5     "afterAgentThought":  [{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
6     "afterAgentResponse": [{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
7     "afterShellExecution":[{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
8     "afterFileEdit":      [{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
9     "afterMCPExecution":  [{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
10     "stop":               [{ "command": "python ~/.cursor/hooks/respan_hook.py" }]
11   }
12 }

Restart Cursor

Restart Cursor IDE to apply the hooks configuration.

View your trace

Open the Traces page to see hierarchical agent traces with thinking, file edits, shell commands, and MCP tool calls.

Hooks reference

Hook	Trigger	Data captured
`beforeSubmitPrompt`	User sends prompt	User input, start time.
`afterAgentThought`	Agent thinking	Thinking text, duration.
`afterShellExecution`	Shell command completes	Command, output, duration.
`afterFileEdit`	File edited	File path, edits.
`afterMCPExecution`	MCP tool completes	Tool name, input, output, duration.
`afterAgentResponse`	Agent responds	Response text (creates root span).
`stop`	Agent stops	Cleanup.

Span types

Span	`log_type`	Description
Root	`agent`	The complete agent turn.
Thinking	`generation`	Agent reasoning blocks.
Shell / File / MCP	`tool`	Tool invocations.

Debugging

Check the log file for issues.

$ tail -f ~/.cursor/state/respan_hook.log

Issue	Solution
No traces appearing	Check `TRACE_TO_RESPAN=true` is set.
API errors	Verify `RESPAN_API_KEY` is correct.
Only root span	Ensure all hooks are configured in `hooks.json`.
Missing thinking	Check `afterAgentThought` hook is active.