Skip to main content
Cursor agent tracing visualization
Cursor is an AI-powered code editor with built-in agent capabilities. With Keywords AI 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 Keywords AI 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 KEYWORDSAI_API_KEY="your-api-key"
export TRACE_TO_KEYWORDSAI="true"

# Optional: Enterprise endpoint (default: api.keywordsai.co)
# export KEYWORDSAI_BASE_URL="https://endpoint.keywordsai.co/api"

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

​
2. Download the Hook Script

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

​
3. Configure Cursor Hooks

Create ~/.cursor/hooks.json with the following configuration: 
{
  "version": 1,
  "hooks": {
    "beforeSubmitPrompt": [
      { "command": "python ~/.cursor/hooks/keywordsai_hook.py" }
    ],
    "afterAgentThought": [
      { "command": "python ~/.cursor/hooks/keywordsai_hook.py" }
    ],
    "afterAgentResponse": [
      { "command": "python ~/.cursor/hooks/keywordsai_hook.py" }
    ],
    "afterShellExecution": [
      { "command": "python ~/.cursor/hooks/keywordsai_hook.py" }
    ],
    "afterFileEdit": [
      { "command": "python ~/.cursor/hooks/keywordsai_hook.py" }
    ],
    "afterMCPExecution": [
      { "command": "python ~/.cursor/hooks/keywordsai_hook.py" }
    ],
    "stop": [
      { "command": "python ~/.cursor/hooks/keywordsai_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/keywordsai_hook.log

​
Common Issues

IssueSolution
No traces appearingCheck TRACE_TO_KEYWORDSAI=true is set
API errorsVerify KEYWORDSAI_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 Keywords AI 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: Keywords-AI/keywordsai-example-projects/cursor

​
References