Cursor (tracing)

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 .

Paste this into your coding agent:


Help me set up Respan tracing with the Cursor integration.
Follow https://www.respan.ai/docs/integrations/cursor.md

Setup

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

Set environment variables

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

Terminal


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

Download the hook script

Terminal


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:

JSON


{
  "version": 1,
  "hooks": {
    "beforeSubmitPrompt": [{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
    "afterAgentThought":  [{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
    "afterAgentResponse": [{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
    "afterShellExecution":[{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
    "afterFileEdit":      [{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
    "afterMCPExecution":  [{ "command": "python ~/.cursor/hooks/respan_hook.py" }],
    "stop":               [{ "command": "python ~/.cursor/hooks/respan_hook.py" }]
  }
}

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.

Terminal


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.

Gateway

See Cursor gateway setup to route Cursor’s chat and agent requests through the Respan gateway.