# @raindrop-ai/claude-code

Raindrop observability for [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code/overview). Automatic session, tool call, and prompt tracing via Claude Code's native [hooks system](https://docs.anthropic.com/en/docs/claude-code/hooks).

## Install

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

## Setup

```bash
raindrop-claude-code setup
```

This saves your write key and configures Claude Code hooks. Every session will now send telemetry to your [Raindrop dashboard](https://app.raindrop.ai).

Hooks are **synchronous by default** for headless/one-shot compatibility (`claude -p`). Use `--async` if you prefer non-blocking hooks in interactive mode.

## What gets tracked

- Every prompt turn as a separate event, grouped by session
- Tool calls with inputs, outputs, and real durations
- Token usage per turn and per session (input, output, cache read, cache creation)
- Model name, service tier, and stop reason
- CLAUDE.md and rules file contents
- `--append-system-prompt` / `--append-system-prompt-file` content (best-effort)
- Subagent spawns and completions
- Permission denials and context compaction
- Self-diagnostics — agent-reported issues via MCP tool, with customizable signal categories
- Nested trace view (tools under root, subagent tools under subagent)
- Claude's responses and errors

## Custom Properties

Tag events with product names or custom metadata via `.claude/settings.json`:

```json
{
  "env": {
    "RAINDROP_EVENT_NAME": "design-agent",
    "RAINDROP_PROPERTIES": "{\"product\":\"design\",\"team\":\"ai\"}"
  }
}
```

## Custom Self-Diagnostics Signals

Replace the built-in signal categories with your own via `~/.config/raindrop/config.json`:

```json
{
  "self_diagnostics": {
    "signals": {
      "billing_complaint": { "description": "User billing issue.", "sentiment": "NEGATIVE" },
      "feature_request": { "description": "User wants a feature.", "sentiment": "POSITIVE" }
    },
    "guidance": "Only report billing if explicitly mentioned."
  }
}
```

Or via env var: `RAINDROP_SELF_DIAGNOSTICS='{"signals":{...}}'`

## Projects

If your org has multiple projects, route telemetry to a specific one by setting its slug via the `RAINDROP_PROJECT_ID` env var or the `project_id` key in `~/.config/raindrop/config.json`:

```json
{
  "project_id": "support-prod"
}
```

This sets the `X-Raindrop-Project-Id` header on every outbound request. Leave it unset (or use `"default"`) to use your org's default **Production** project — the existing behavior. Single-project orgs need nothing new.

## Payload size limits & bounded hooks

Event input/output are capped at **1,000,000 characters per field** (span
attributes at 32 KB) and truncated with a `...[truncated by raindrop]` marker,
enforced before serialization so multi-MB prompts or tool results cost the cap
— not the payload — inside the hook process. Each hook invocation also runs
under a hard overall deadline (8s by default, covering the stdin read,
mapping, and network flush; `RAINDROP_HOOK_FLUSH_DEADLINE_MS` to override)
and exits explicitly, so a dead or slow network can never stall Claude Code's
hook machinery.

## Debugging

```bash
raindrop-claude-code debug-on    # logs hook output to /tmp/raindrop-hooks.log
raindrop-claude-code debug-off   # disables logging
```

## Docs

Full documentation: [docs.raindrop.ai/sdk/claude-code](https://docs.raindrop.ai/sdk/claude-code)