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

# Fiddler Claude Code Plugin

> Install, upgrade, and configure the Fiddler Claude Code plugin to capture per-turn OpenTelemetry traces (including LLM responses and tool input/output) from Claude Code sessions and deliver them to Fiddler.

## Overview

The **Fiddler Claude Code Plugin** (`fiddler-coding-agent-plugin`) instruments [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) sessions and delivers per-turn OpenTelemetry traces to Fiddler. It runs as a set of Claude Code hooks (a small binary that fires on session events) and captures each turn as a nested trace with the **user prompt, LLM response content, tool input/output, and token usage**.

Plugin traces group into the same Fiddler session as [native Claude Code traces](/integrations/agentic-ai/claude-code-integration), so the two can be used together.

<Info>
  This capability is currently in [private preview](/reference/feature-maturity-definitions#private-preview) and is not yet available to all customers. Contact your Fiddler Customer Success Manager to request access.
</Info>

<Info>
  The plugin **fails open**: a hook error, a missing binary, or an unreachable endpoint never breaks or slows your Claude Code session. At worst, a turn's trace is skipped.
</Info>

***

## Prerequisites

* **Claude Code 2.1.120 or later.** Full trace capture depends on hooks and payload fields introduced across the 2.1.x line, the most recent being the `duration_ms` tool-timing field added in 2.1.119. On older versions the plugin fails open, capturing less rather than breaking your session.
* **`gh` CLI, authenticated** (`gh auth login`). During private preview the plugin repository is private, so the plugin downloads its binary from a private GitHub Release using your `gh` authentication. Each machine that runs the plugin needs `gh` installed and authenticated with access to `fiddler-labs/fiddler-coding-agent-plugin` **before the first session**. Request access through your Fiddler account team.
* A **Fiddler GenAI application**, with its application ID and an API key.

***

## Installation

<Steps>
  <Step title="Add the marketplace">
    ```text theme={null}
    /plugin marketplace add fiddler-labs/fiddler-coding-agent-plugin
    ```
  </Step>

  <Step title="Install the plugin">
    ```text theme={null}
    /plugin install fiddler-claude-code-plugin@fiddler-plugins
    ```
  </Step>

  <Step title="Configure and activate">
    Add the [configuration values](#configuration) below. The plugin activates on install; if Claude Code prompts you to, run `/reload-plugins` to apply it without restarting. The plugin downloads its binary on the first session.
  </Step>
</Steps>

The binary is downloaded once per version and cached, so the first session after installing (or upgrading) does the download and later sessions reuse it.

***

## Upgrading

New versions are published to the marketplace repository. Third-party marketplaces do **not** auto-update by default, so upgrades are manual. To move to a newer version, re-run the install command; it refreshes the marketplace and installs the latest version:

<Steps>
  <Step title="Update the plugin">
    ```text theme={null}
    /plugin install fiddler-claude-code-plugin@fiddler-plugins
    ```

    Optionally refresh the marketplace first with `/plugin marketplace update fiddler-plugins`, though the install command already does this.
  </Step>

  <Step title="Activate the new version">
    Run `/reload-plugins` if Claude Code prompts you; no restart is needed. On the next session the plugin downloads the binary matching the new version (again using your `gh` authentication) and caches it.
  </Step>
</Steps>

Check the installed version any time with `/plugin list`.

<Info>
  Because the versioned binary is fetched from a private GitHub Release, `gh` must still be authenticated with repository access when you upgrade, the same requirement as the first install.
</Info>

***

## Configuration

Set three values under `"env"` in your Claude Code settings, either `~/.claude/settings.json` (user-level) or `.claude/settings.local.json` (project-level):

```json theme={null}
{
  "env": {
    "CLAUDE_PLUGIN_OPTION_OTLP_URL": "https://<your-fiddler-url>",
    "CLAUDE_PLUGIN_OPTION_APP_ID": "<your-application-id>",
    "CLAUDE_PLUGIN_OPTION_AUTH_TOKEN": "<your-api-key>"
  }
}
```

Configuration values are read when a session starts, so start a new Claude Code session after changing any of them.

| Value          | Setting                           | Notes                                                                                              |
| -------------- | --------------------------------- | -------------------------------------------------------------------------------------------------- |
| OTLP endpoint  | `CLAUDE_PLUGIN_OPTION_OTLP_URL`   | Your Fiddler base URL. A trailing `/` is trimmed and the traces path is appended automatically.    |
| Application ID | `CLAUDE_PLUGIN_OPTION_APP_ID`     | The ID of your Fiddler GenAI application. Fiddler drops spans without a recognized application ID. |
| Auth token     | `CLAUDE_PLUGIN_OPTION_AUTH_TOKEN` | Your Fiddler API key, as the **bare token**. Do **not** add a `Bearer` prefix. The plugin adds it. |

All three values must be set for the plugin to send traces.

<Warning>
  **Do not commit your API key.** For project-level configuration use `.claude/settings.local.json` (git-ignored by default) rather than a committed `settings.json`.
</Warning>

### Optional Settings

These are read from the process environment (not from `"env"` in settings):

| Variable                 | Default | Effect                                                                                                                          |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `FIDDLER_OMIT_USER_INFO` | `false` | When `true`, omits the developer's email and account UUID from traces. A hashed user ID and the organization ID are still sent. |

***

## What You Get

Each user turn produces one trace in Fiddler, nested under a root agent span, with:

* The **user prompt** and the **assistant's response** for the turn.
* One **LLM span per model call**, with token usage (including cache tokens), model, and finish reason.
* One **tool span per tool call**, with the tool name, arguments, and result, plus the permission decision for the call.
* **Error, refusal, and interrupt** outcomes marked on the relevant spans.

Because the plugin stamps the Claude Code session ID on every span, a session's turns group into a **single Fiddler session** with no extra configuration.

Once traces arrive, you can score them with Fiddler evaluators. Because the plugin captures both input and output content, evaluators that need the response (such as faithfulness) can run on these traces.

***

## Data Capture and Privacy

<Warning>
  In the current preview build the plugin **always captures prompt, response, and tool input/output content**. Content-redaction controls are not yet enforced. Deploy the plugin only where capturing this content is acceptable, and scope the Fiddler application and API key accordingly. To limit the developer identity that accompanies traces, set `FIDDLER_OMIT_USER_INFO=true`.
</Warning>

The plugin makes only outbound OTLP/HTTP calls to your configured Fiddler endpoint. The auth token is delivered through Claude Code's plugin configuration (marked sensitive), is never logged, and is never written to plaintext project config.

***

## Troubleshooting

### No Plugin Traces Appearing in Fiddler

1. After installing or upgrading, make sure the plugin is active (run `/reload-plugins` if Claude Code prompts you), and confirm `gh auth status` shows an authenticated account with access to `fiddler-labs/fiddler-coding-agent-plugin` (needed to download the binary).
2. Confirm all three configuration values are set (`CLAUDE_PLUGIN_OPTION_OTLP_URL`, `CLAUDE_PLUGIN_OPTION_APP_ID`, `CLAUDE_PLUGIN_OPTION_AUTH_TOKEN`). If any is empty, the plugin sends nothing.
3. Confirm `CLAUDE_PLUGIN_OPTION_APP_ID` is a valid application ID; Fiddler drops spans without one.
4. Confirm the auth token is the **bare** token, with no `Bearer` prefix.

### Some Turns Are Missing Token Usage or the Response

Turns that were interrupted, or that were in flight when the session ended, are recovered with the prompt but without token usage or response text, which are available only when a turn completes normally.

***

## Related Documentation

* [Claude Code Integration](/integrations/agentic-ai/claude-code-integration): Native, no-plugin OTel trace ingestion for Claude Code (per-model-call timing; complements this plugin)
* [OpenTelemetry Integration](/integrations/agentic-ai/opentelemetry-integration): GenAI semantic conventions and manual OTel instrumentation
* [Fiddler OTel SDK](/integrations/agentic-ai/fiddler-otel-sdk): Foundation package for custom OTel instrumentation