Skip to main content
The @raindrop-ai/claude-code package instruments Claude Code CLI using its native hooks system. No wrapper or proxy needed — your workflow stays exactly the same. What gets tracked:
  • Every prompt turn as a separate event, grouped by session
  • Tool calls (Bash, Edit, Write, Read, etc.) with inputs, outputs, and real durations
  • Subagent spawns and completions with duration
  • Permission denials (tool calls blocked by auto-mode)
  • Context compaction events
  • Claude’s final responses
  • Errors and failures
  • Nested trace view — tool calls appear under the root span, subagent tools nest under the subagent

​
Installation

npm install -g @raindrop-ai/claude-code

​
Setup

Run the setup command to configure Claude Code hooks and store your write key: 
raindrop-claude-code setup
This does two things:
  1. Saves your Raindrop write key to ~/.config/raindrop/config.json
  2. Adds hook entries to ~/.claude/settings.json so every Claude Code session reports telemetry
You can also pass flags directly: 
raindrop-claude-code setup --write-key=YOUR_KEY --user-id=your-username

​
Per-Project Setup

By default, hooks are installed globally (~/.claude/settings.json). To scope hooks to a single project instead, use --scope=project — this writes to .claude/settings.json in the current directory: 
raindrop-claude-code setup --scope=project
ScopeSettings fileApplies to
user (default)~/.claude/settings.jsonAll projects
project.claude/settings.json in cwdThis project only
The setup merges hooks into your existing settings file — it won’t overwrite your other hooks or settings.
That’s it. Start a Claude Code session and events will appear in your Raindrop dashboard.

​
How It Works

Claude Code’s hooks system fires shell commands at lifecycle points (session start, prompt submit, tool use, etc.). The setup command registers raindrop-claude-code hook as an async command hook for each event type. When a hook fires, Claude Code pipes a JSON payload to stdin. The handler parses it, maps it to Raindrop’s event and trace format, and POSTs to the Raindrop API. All hooks run with async: true, so they never block Claude Code. 
Claude Code CLI
  → fires hook (e.g. PostToolUse)
  → pipes JSON to raindrop-claude-code hook (async, non-blocking)
  → maps to Raindrop event/trace format
  → POST to api.raindrop.ai

​
Events Captured

Claude Code EventWhat’s Tracked
SessionStartSession metadata (model, source, working directory)
UserPromptSubmitUser’s prompt text (each turn is a separate event)
PreToolUseTool start timestamp (used to compute duration)
PostToolUseTool call span with name, input, output, and duration
PostToolUseFailureFailed tool call span with error details
SubagentStartSubagent spawn with type and ID
SubagentStopSubagent completion with duration and result
PermissionDeniedBlocked tool call with denial reason
PostCompactContext compaction trigger and summary
StopClaude’s final response text
StopFailureResponse with error information
SessionEndSession end reason
All events within a session share the same convoId (derived from Claude Code’s session_id), so they appear grouped in the Raindrop dashboard.

​
Configuration

​
Environment Variables

VariableDescription
RAINDROP_WRITE_KEYAPI write key (overrides config file)
RAINDROP_USER_IDUser identifier (overrides config file, defaults to OS username)
RAINDROP_API_URLCustom API endpoint
RAINDROP_DEBUGSet to "true" for verbose logging

​
Config File

The setup command creates ~/.config/raindrop/config.json: 
{
  "write_key": "your-write-key",
  "user_id": "your-username"
}
Precedence (low to high): config file → environment variables.

​
Uninstalling

To remove the hooks, edit ~/.claude/settings.json and remove the hook entries that reference raindrop-claude-code. Then uninstall the package: 
npm uninstall -g @raindrop-ai/claude-code

​
Troubleshooting

​
Events not appearing

  1. Check your write key — run raindrop-claude-code setup again or verify ~/.config/raindrop/config.json
  2. Verify hooks are installed — run /hooks inside Claude Code to list active hooks
  3. Enable debug logging — set RAINDROP_DEBUG=true in your environment
  4. Check binary is in PATH — run which raindrop-claude-code

​
Hook errors

Hooks run with async: true, so errors won’t interrupt Claude Code. Check debug logs for details: 
RAINDROP_DEBUG=true claude
That’s it! Ping us on Slack or email us if you need help.