# @raindrop-ai/cursor

Raindrop observability for Cursor IDE, `cursor-agent`, and Cloud Agents. Hooks capture each turn. You do not change application code.

## Install

Requires Node.js 20 or later.

```bash
npm install -g @raindrop-ai/cursor
raindrop-cursor setup
```

Setup writes hooks into `~/.cursor/hooks.json` and a self-diagnostics MCP server into `~/.cursor/mcp.json`. Existing hooks and other MCP servers stay. Setup asks for a Raindrop write key and an optional project slug. A blank project uses Production.

## Cloud Agents

```bash
npx -y @raindrop-ai/cursor setup --scope project
```

Commit `.cursor/hooks.json` and `.cursor/mcp.json`. Project hooks pin `npx -y @raindrop-ai/cursor@<version> hook` to the CLI that ran setup. Rerun setup to refresh the pin.

Set `RAINDROP_WRITE_KEY` and `RAINDROP_LOCAL_DEBUGGER=false` in the Cloud Agent runtime secrets. For a named project, also set `RAINDROP_PROJECT_ID`.

Install in one scope per conversation.

## What gets tracked

- One `ai_generation` event per Cursor generation
- Tool success and failure spans, including permission denials
- Thinking spans
- One model span per turn, with input, output, cache-read, and cache-write usage when Cursor provides it
- Session usage totals and compaction metadata

## Configuration

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

| Environment variable | Purpose |
|---|---|
| `RAINDROP_WRITE_KEY` | Raindrop write key |
| `RAINDROP_API_URL` | Ingest base URL; defaults to `https://api.raindrop.ai/v1` |
| `RAINDROP_PROJECT_ID` | Project override |
| `RAINDROP_USER_ID` | User ID fallback; Cursor's `user_email` takes precedence |
| `RAINDROP_CONVO_ID` | Conversation ID override |
| `RAINDROP_EVENT_NAME` | Event name; defaults to `ai_generation` |
| `RAINDROP_PROPERTIES` | JSON object merged with configured custom properties |
| `RAINDROP_ENABLED` | `false` or `0` disables telemetry |
| `RAINDROP_DEBUG` | `true` enables debug logging |
| `RAINDROP_HOOK_FLUSH_DEADLINE_MS` | Whole hook deadline; defaults to 8000 ms |
| `RAINDROP_LOCAL_DEBUGGER` | Local debugger URL, or `false` to disable discovery |
| `RAINDROP_SELF_DIAGNOSTICS` | JSON object with optional `signals`, `guidance`, and `toolName` |
| `RAINDROP_TOOLS` | JSON array overriding the tool catalog recorded as `ai.prompt.tools` on every LLM span (see below) |

Application Git identity is reported on Cursor events and traces when it can be tied to the
agent-under-test. Set `app_git` in `~/.config/raindrop/config.json` to override `commit_sha`,
`commit_dirty`, and optional `branch`, or set `app_git: false` to opt out. Cursor may observe a
remote coding workspace, so the observer process's checkout and ambient CI/deployment metadata are
ignored by default. Use an explicit `source_directory` (or `RAINDROP_GIT_SOURCE_DIRECTORY`) for
bounded local discovery, or set `RAINDROP_COMMIT_SHA` directly. Branch discovery from that source
directory is opt-in with `detect_branch: true` (or `RAINDROP_GIT_DETECT_BRANCH=true`).

```bash
raindrop-cursor status
raindrop-cursor disable
raindrop-cursor enable
raindrop-cursor debug-on
raindrop-cursor debug-off
raindrop-cursor uninstall
raindrop-cursor uninstall --scope project
```

Enable, disable, and debug commands update the shared Raindrop config that Claude Code also reads.

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

Cursor hooks never expose the request Cursor sends to the model, so this integration cannot observe
the tool catalog and records nothing by default (the attribute stays absent, meaning "unknown").
`tools` overrides that: set an array of tool declarations in `~/.config/raindrop/config.json`
(`tools`) or as JSON in `RAINDROP_TOOLS` (the variable wins). Any shape `@raindrop-ai/core`
recognizes works (`{ name, description?, parameters }`, `{ type: "function", name, inputSchema }`,
OpenAI/Anthropic wrappers, ...). The override is recorded verbatim on every per-turn LLM span
(`gen_ai.request.model` spans), never on the turn root, tool-call, or thinking spans; `tools: []`
records an explicitly empty catalog. Implicit capture is not possible here.

## Local debugger

Start the Raindrop local debugger on port 5899, or set `RAINDROP_LOCAL_DEBUGGER` to its URL. Event patches and OTLP spans appear without a cloud write key.

`setup --local-only` skips requiring a write key. On Cloud Agent VMs and other shared hosts, set `RAINDROP_LOCAL_DEBUGGER=false`.

## Self-diagnostics

`raindrop-cursor mcp-serve` exposes `__raindrop_report`. Default categories are missing context, repeated tool failures, capability gaps, complete task failure, and noteworthy observations.

## Model spans and token usage

LLM spans carry the raw counters from the hook payload under the canonical `gen_ai.usage.*` names. `gen_ai.provider.name` is recorded only when the model names a known provider family; Cursor's own models get none.
