> ## Documentation Index
> Fetch the complete documentation index at: https://raindrop.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor (Beta)

> Automatic observability for Cursor IDE, cursor-agent CLI, and Cloud Agents. Install once, then every generation, tool call, and prompt is tracked in Raindrop.

The `@raindrop-ai/cursor` package instruments
[Cursor](https://cursor.com) using its native
[hooks system](https://cursor.com/docs/hooks). No wrapper or proxy
needed; your workflow stays exactly the same.

**What gets tracked:**

* Every generation as a separate `ai_generation` event, grouped by conversation
* Tool calls with inputs, outputs, and real durations
* Thinking spans
* One model span per turn with token usage (input, output, cache read, cache write)
* Session usage totals, compaction events, and session metadata
* Agent-reported issues via the self-diagnostics MCP tool
* Permission denials (tool calls blocked by auto-mode)
* Errors and failures

## Installation

Requires Node.js 20 or later. Install the package globally and run setup:

```bash theme={null}
npm install -g @raindrop-ai/cursor
raindrop-cursor setup
```

Setup asks for your Raindrop write key and an optional project slug (blank uses the
default **Production** project). It merges hooks into `~/.cursor/hooks.json` and adds
a self-diagnostics MCP server to `~/.cursor/mcp.json`. Existing hooks and other MCP
servers are preserved.

You can also set the write key via environment variable:

```bash theme={null}
export RAINDROP_WRITE_KEY=your-write-key
```

### Per-project setup (and Cloud Agents)

By default hooks install globally. To scope them to a single repository, including
its [Cloud Agents](https://cursor.com/docs/cloud-agent), run setup in the repo root:

```bash theme={null}
npx -y @raindrop-ai/cursor setup --scope project
```

| Scope | Settings file | Applies to |
| - | - | - |
| `user` (default) | `~/.cursor/hooks.json` | All projects |
| `project` | `.cursor/hooks.json` in cwd | This project and its Cloud Agents |

Commit `.cursor/hooks.json` and `.cursor/mcp.json`. Cloud Agent VMs need Node.js, npm,
and registry access, plus `RAINDROP_WRITE_KEY` and `RAINDROP_LOCAL_DEBUGGER=false` in
the agent's runtime secrets. For a named project, also set `RAINDROP_PROJECT_ID` there.
The project slug saved during local setup does not travel to Cloud Agent VMs.

<Info>
  Install in one scope per conversation to avoid duplicate hook deliveries.
</Info>

That's it. Open Cursor and events will appear in your Raindrop dashboard.

***

## How It Works

Cursor's [hooks system](https://cursor.com/docs/hooks) fires shell commands at lifecycle
points. Setup registers `raindrop-cursor hook` for each event type; Cursor pipes a JSON
payload to stdin, the handler maps it to Raindrop's event and trace format, and POSTs
to the Raindrop API. Hook commands always exit zero, so telemetry never blocks your work.

### Events Captured

| Cursor Event | What's Tracked |
| - | - |
| `sessionStart` | Session metadata (model, workspace roots, version) |
| `beforeSubmitPrompt` | User's prompt text (each generation is a separate event) |
| `postToolUse` | Tool call span with name, input, output, and duration |
| `postToolUseFailure` | Failed tool call span with error details |
| `subagentStart` / `subagentStop` | Observation spans on the parent turn (see below) |
| `afterAgentThought` | `ai.thinking` span |
| `afterAgentResponse` | Agent's response text |
| `stop` | Finalizes the event with token usage, model, and status |
| `preCompact` | Context compaction metadata |
| `sessionEnd` | Session end; unfinished turns are closed out |

All events within a conversation share the same `convoId`, so they appear grouped in
the Raindrop dashboard.

### Subagent support

Full subagent tracking isn't available because Cursor's hooks lack the linkage needed
to attribute child activity; `subagentStart`/`subagentStop` only add `cursor.subagent*`
observation spans and counts to the parent turn.

***

## Configuration

Configuration is shared with the Claude Code integration at `~/.config/raindrop/config.json`.

| Variable | Description |
| - | - |
| `RAINDROP_WRITE_KEY` | API write key (overrides config file) |
| `RAINDROP_USER_ID` | User identifier (Cursor's `user_email` takes precedence when present) |
| `RAINDROP_CONVO_ID` | Override conversation ID (groups events across sessions) |
| `RAINDROP_PROJECT_ID` | Route events to a specific [project](/docs/platform/projects) (slug); omit for the default **Production** project |
| `RAINDROP_EVENT_NAME` | Custom event name (default: `ai_generation`) |
| `RAINDROP_PROPERTIES` | JSON object merged into every event's properties |
| `RAINDROP_ENABLED` | Set to `"false"` or `"0"` to disable all telemetry |
| `RAINDROP_API_URL` | Custom API endpoint |
| `RAINDROP_LOCAL_DEBUGGER` | Local debugger URL (auto-detected on `:5899` if not set; set `false` to disable) |
| `RAINDROP_DEBUG` | Set to `"true"` for verbose logging |
| `RAINDROP_SELF_DIAGNOSTICS` | JSON object to customize self-diagnostics signal categories |
| `RAINDROP_HOOK_FLUSH_DEADLINE_MS` | Whole-hook delivery deadline (default: `8000`) |

## Tool catalog capture (`ai.prompt.tools`)

**Override only.** Cursor hooks never expose the request Cursor sends to the model, so this integration cannot observe the tool catalog and records nothing by default. Set `tools` (an array of tool declarations) in `~/.config/raindrop/config.json` or as JSON in `RAINDROP_TOOLS` (the variable wins). The override is recorded verbatim on every per-turn LLM span, never on the turn root, tool-call or thinking spans; `tools: []` records an explicitly empty catalog. See [Tool catalog capture](/docs/sdk/tool-catalog) for the attribute format, the absent / `[]` semantics and the override shapes accepted.

## Self Diagnostics

Setup registers a `raindrop-diagnostics` MCP server. Cursor's agent can call the
`__raindrop_report` tool to flag issues such as capability gaps, missing context,
broken tools, and task failures. They appear as signals on the current event in Raindrop.

Default categories: `missing_context`, `repeatedly_broken_tool`, `capability_gap`,
`complete_task_failure`, `noteworthy`. Customize them via `RAINDROP_SELF_DIAGNOSTICS`
or the `self_diagnostics` config key, same format as the
[Claude Code integration](/docs/integrations/claude-code#custom-self-diagnostics-signals).

<Info>
  Signals attach to the most recently updated event on the machine. With several
  conversations open at once, a signal can attach to a different conversation's event.
</Info>

***

## Managing the integration

```bash theme={null}
raindrop-cursor status        # show current setup
raindrop-cursor disable       # stop sending events
raindrop-cursor enable        # resume sending events
raindrop-cursor debug-on      # log hook activity
raindrop-cursor debug-off     # stop logging
raindrop-cursor uninstall     # remove hooks + MCP server
```

`enable`, `disable`, and the debug commands update shared Raindrop configuration,
including its use by the Claude Code integration.

## Troubleshooting

### Events not appearing

1. **Check your write key** by running `raindrop-cursor setup` again or verifying `~/.config/raindrop/config.json`
2. **Verify hooks are installed** in `~/.cursor/hooks.json` (look for `raindrop-cursor hook` entries)
3. **Enable debug logging** with `raindrop-cursor debug-on` and check the debug output
4. **Check the binary is in PATH** with `which raindrop-cursor`
5. **After upgrading**, rerun `raindrop-cursor setup` so hooks pick up the new version

***

That's it! Ping us on Slack or [email us](mailto:support@raindrop.ai) if you need help.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.