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

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

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 |

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

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.

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.