> ## Documentation Index
> Fetch the complete documentation index at: https://raindrop.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode (Beta)

> Integrate Raindrop with OpenCode to automatically capture coding sessions, messages, tool calls, and LLM responses in your dashboard.

The **Raindrop OpenCode plugin** (`@raindrop-ai/opencode-plugin`) instruments OpenCode so that every LLM response and tool call is sent to Raindrop. You don't need to add any per-call instrumentation.

## Installation

Add the plugin to your OpenCode config.

**Config file locations:** `opencode.json` in your project, or `~/.config/opencode/opencode.json` for a global config.

Add this to the config file:

```json theme={null}
{
  "plugin": ["@raindrop-ai/opencode-plugin"]
}
```

## Quick Start

1. **Add the plugin** to your OpenCode config (see above).

2. **Set your write key** in the environment where OpenCode runs:

   ```bash theme={null}
   export RAINDROP_WRITE_KEY="your-write-key"
   ```

3. **Start OpenCode.** Sessions are automatically traced to Raindrop.

After that, each session appears in your Raindrop dashboard with turn-by-turn input/output, tool spans, and LLM metadata.

## Configuration

**Required:** set your Raindrop write key in the environment where OpenCode runs:

```bash theme={null}
export RAINDROP_WRITE_KEY="your-write-key"
```

**Optional:** provide additional metadata to be included with every event

```bash theme={null}
export RAINDROP_EVENT_METADATA='{"userId":"user_456","eventName":"support-chat","properties":{"source":"web"}}'                                                         
```

### System Prompt Capture

To include the system prompt in trace spans (visible in the Trace tab when you click an LLM span), enable the `captureSystemPrompt` option:

```bash theme={null}
export RAINDROP_CAPTURE_SYSTEM_PROMPT="true"
```

Or via config file (`~/.config/opencode/raindrop.json` or `.opencode/raindrop.json`):

```json theme={null}
{
  "capture_system_prompt": true
}
```

When enabled, the assembled system prompt is stored as a `gen_ai.prompt.0.*` span attribute and rendered as a **"system"** labeled section in the span detail view. This is useful for tracking which system prompt version was used in a given conversation.

**Defaults to `false`** — no system prompt data is captured unless explicitly enabled. System prompts longer than 32KB are automatically truncated.

### Projects

If your org has multiple [projects](/platform/projects), route this plugin's events to a specific one by setting its slug via `RAINDROP_PROJECT_ID` or the `project_id` config-file key:

```bash theme={null}
export RAINDROP_PROJECT_ID="support-prod"
```

Or via config file (`~/.config/opencode/raindrop.json` or `.opencode/raindrop.json`):

```json theme={null}
{
  "project_id": "support-prod"
}
```

This sets the `X-Raindrop-Project-Id` header on every event. Omit it (or pass `default`) to use your org's default **Production** project, which is the existing behavior. Single-project orgs need nothing new.

## Context & Metadata

### Per-Call Context Override

You can override the environment-set metadata on a per-prompt basis by passing a
`metadata` field on any text part when calling
`session.prompt()`:

```typescript theme={null}
await client.session.prompt({
  path: { id: sessionID },
  body: {
    parts: [
      {
        type: "text",
        text: userMessage,
        metadata: {
          userId: "user_456",
          eventName: "support-chat",
          properties: { source: "web" },
        },
      },
    ],
  },
});
```

Supported fields:

| Field        | Type     | Description                                 |
| ------------ | -------- | ------------------------------------------- |
| `userId`     | `string` | User to attribute this turn's event to      |
| `eventName`  | `string` | Event name for this turn                    |
| `properties` | `object` | Additional properties for this turn's event |

**Merge behavior:**

* Prompt-level values override `RAINDROP_EVENT_METADATA` for that turn
* `properties` are shallow-merged (prompt-level wins on conflicts)
* `convoId` is always the OpenCode session ID

## Identifying Users

To associate traits with a user, use our [TypeScript SDK](/sdk/typescript):

```typescript theme={null}
import { Raindrop } from "raindrop-ai";

const raindrop = new Raindrop({ writeKey: RAINDROP_API_KEY });

raindrop.setUserDetails({
  userId: "user_456",
  traits: {
    name: "Jane",
    email: "jane@example.com",
    plan: "paid", // we recommend 'free', 'paid', 'trial'
    os: "macOS",
  },
});
```

## Troubleshooting

### Events not appearing in the dashboard

1. **Check your write key** — Make sure `RAINDROP_WRITE_KEY` is set in the environment where OpenCode runs.
   Use the Raindrop dashboard to confirm events and traces after your first session.