Skip to main content
The @raindrop-ai/cursor package instruments Cursor using its native hooks system. 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:
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:

​
Per-project setup (and Cloud Agents)

By default hooks install globally. To scope them to a single repository, including its Cloud Agents, run setup in the repo root:
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.
Install in one scope per conversation to avoid duplicate hook deliveries.
That’s it. Open Cursor and events will appear in your Raindrop dashboard.

​
How It Works

Cursor’s hooks system 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

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.

​
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 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.
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.

​
Managing the integration

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 if you need help.