> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Cursor (tracing)

> Trace Cursor AI agent conversations with Respan — hook-based tracing and full observability.

[Cursor](https://cursor.com) 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](https://cursor.com/docs/agent/hooks).

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

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

#### Use Respan Gateway

See [Cursor gateway setup](/docs/gateway/cursor) to route Cursor's chat and agent requests through the Respan gateway.

#### Example projects

* [Cursor hook source](https://github.com/respanai/respan-example-projects/tree/main/python/dev-tools/cursor)

#### Tracing

## Setup

> **Note**
>
> **Prerequisite:** Cursor IDE installed, plus Python 3.8+ with `requests`.

#### Set environment variables

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

**`Bash/Zsh`**

```bash Bash/Zsh
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export TRACE_TO_RESPAN="true"
```

**`PowerShell`**

```powershell PowerShell
$env:RESPAN_API_KEY = "YOUR_RESPAN_API_KEY"
$env:TRACE_TO_RESPAN = "true"
```

#### Download the hook script

**`Bash/Zsh`**

```bash Bash/Zsh
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
```

**`PowerShell`**

```powershell PowerShell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.cursor\hooks"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/respanai/respan-example-projects/main/python/dev-tools/cursor/respan_hook.py" -OutFile "$env:USERPROFILE\.cursor\hooks\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](https://platform.respan.ai/platform/traces) 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.

```bash
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.        |