Skip to main content
  1. Sign up — Create an account at platform.respan.ai
  2. Create an API key — Generate one on the API keys page
  3. Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page
Cursor agent tracing visualization
Cursor is an AI-powered code editor with built-in agent capabilities. With Respan integration, you get hierarchical traces of every agent interaction including thinking blocks, file edits, shell commands, and MCP tool calls.

​
How It Works

Cursor provides hooks that fire during agent execution. Our integration captures these events in real-time and sends them to Respan as hierarchical traces. The hook captures thinking blocks, file edits, shell commands, and MCP tool calls as child spans under a root agent span.
For details on trace structure and span types, see the Observability Data Model.

​
Prerequisites

​
Installation

​
1. Set Environment Variables

Add these to your shell profile (.bashrc, .zshrc, or PowerShell $PROFILE): 
export RESPAN_API_KEY="your-api-key"
export TRACE_TO_RESPAN="true"

# Optional: Enterprise endpoint (default: api.respan.ai)
# export RESPAN_BASE_URL="https://endpoint.respan.ai/api"

# Optional: Enable debug logging
# export CURSOR_RESPAN_DEBUG="true"

​
2. Download the Hook Script

Download the hook script to your Cursor hooks directory: 
mkdir -p ~/.cursor/hooks
curl -o ~/.cursor/hooks/respan_hook.py \
  https://raw.githubusercontent.com/Respan/respan-example-projects/main/example_scripts/python/cursor/respan_hook.py

​
3. Configure Cursor Hooks

Create ~/.cursor/hooks.json with the following configuration: 
{
  "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" }
    ]
  }
}

​
4. Restart Cursor

Restart Cursor IDE to apply the hooks configuration.

​
Hooks Reference

HookTriggerData Captured
beforeSubmitPromptUser sends promptUser input, start time
afterAgentThoughtAgent thinkingThinking text, duration
afterShellExecutionShell command completesCommand, output, duration
afterFileEditFile editedFile path, edits
afterMCPExecutionMCP tool completesTool name, input, output, duration
afterAgentResponseAgent respondsResponse text (creates root span)
stopAgent stopsCleanup

​
Span Types

Spanlog_typeDescription
RootagentThe complete agent turn
ThinkinggenerationAgent reasoning blocks
Shell/File/MCPtoolTool invocations

​
Trace Fields

FieldValueDescription
trace_unique_id{conversation_id}_{generation_id}Unique per turn
span_workflow_namecursor_{conversation_id}Groups all turns
thread_identifiercursor_{conversation_id}Links turns in Threads view

​
Debugging

Check the log file for issues: 
tail -f ~/.cursor/state/respan_hook.log

​
Common Issues

IssueSolution
No traces appearingCheck TRACE_TO_RESPAN=true is set
API errorsVerify RESPAN_API_KEY is correct
Only root spanEnsure all hooks are configured in hooks.json
Missing thinkingCheck afterAgentThought hook is active

​
Example Output

After setup, you’ll see traces in Respan with full hierarchy: 
cursor_abc123_xyz789 (38.9s)
├── Thinking 1 (0.5s) - "Let me analyze the code..."
├── Thinking 2 (0.3s) - "I should update the function..."
├── Edit: utils.py (0.1s)
├── Shell: npm test (4.1s)
└── Thinking 3 (0.2s) - "Tests passed, done."

​
Source Code

The full source code is available on GitHub: Respan/respan-example-projects/cursor

​
References