Log Claude Code sessions to Opik for LLM observability, plus skills and agents for building observable AI applications.

• Session Tracing: Automatically log Claude Code sessions as Opik traces
• Span Tracking: Each tool call becomes a span within the trace
• Subagent Support: Nested agent calls are tracked with parent-child relationships
• Skills: Built-in knowledge for LLM observability, tracing, and evaluation
• Agents: Code review agent for agent architecture best practices

We trigger tracing for everything done in Claude Code, but don't slow you down.

Each conversation turn becomes an Opik trace. Tool calls, thoughts, and responses become spans. Subagent invocations are nested under their parent Task span.

From within Claude Code:

/plugin marketplace add comet-ml/opik-claude-code-plugin

Then install the plugin:

/plugin install opik

If you've cloned the repo locally, add it as a marketplace and install from there:

/plugin marketplace add /path/to/opik-claude-code-plugin
/plugin install opik

Important: Restart any running Claude Code sessions after installation. Hooks only load when a session starts.

For org-wide deployment, push configuration through Claude Code's server-managed settings — Anthropic's admin console delivers the JSON to every authenticated user, no file distribution or MDM required. (Requires Claude for Teams or Enterprise.)

Where to set it up: in Claude.ai, go to Admin Settings → Claude Code → Managed settings and paste the JSON below. Clients pick it up at next startup or within the hourly poll.

Example managed settings JSON:

{
  "extraKnownMarketplaces": {
    "opik": {
      "source": {"source": "github", "repo": "comet-ml/opik-claude-code-plugin"},
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "opik@opik": true
  },
  "env": {
    "OPIK_CC_TRACING_ENABLED": "true",
    "OPIK_BASE_URL": "https://www.comet.com/opik/api",
    "OPIK_CC_WORKSPACE": "your-org-cc-workspace",
    "OPIK_API_KEY": "<workspace-scoped API key>",
    "OPIK_CC_PROJECT": "cc-{username}"
  },
  "forceRemoteSettingsRefresh": true,
  "showThinkingSummaries": true
}

What each piece does:

• extraKnownMarketplaces + enabledPlugins — registers the marketplace and force-enables the plugin for every user. Users see it as managed and can't disable it.
• OPIK_CC_TRACING_ENABLED=true — turns tracing on for every session without users dropping per-project files. Individual projects can still opt out by writing off to .claude/.opik-tracing-enabled.
• OPIK_CC_WORKSPACE — sends Claude Code traces to a dedicated workspace, isolated from any user's personal Opik work in ~/.opik.config.
• OPIK_API_KEY — the workspace-scoped key the hook uses to write traces. Treat this file as sensitive; the API key is shared with every machine it's deployed to. Provision a key with the minimum write scope on the CC workspace.
• OPIK_CC_PROJECT — supports {field} tokens that expand from the user's Claude Code OAuth identity (read from ~/.claude.json). So one config string routes every user to their own project.
• forceRemoteSettingsRefresh: true — fail-closed startup: blocks the CLI at launch until fresh managed settings are fetched from Anthropic, so the brief unenforced window on first launch can't leak unmonitored sessions. Requires connectivity to api.anthropic.com.
• showThinkingSummaries: true — surfaces extended-thinking summaries in the user's transcript so the same reasoning that gets traced to Opik is visible to the user locally. Optional but useful when you want what's logged to match what users see.

Available {field} tokens:

Unknown tokens pass through literally so misconfigurations are visible in Opik rather than silently producing empty project names.

Per-trace identity (cc.identity.user_email, cc.identity.user_uuid, cc.identity.org_uuid, etc.) is also attached to every trace's metadata regardless of project name, plus a user:<email> tag, so admins can filter/group across users in a shared project too.

Run the Opik CLI to configure your connection:

pip install opik
opik configure

This creates ~/.opik.config with your API URL, key, and workspace.

export OPIK_CC_TRACING_ENABLED="true"       # Org-wide enable, useful from managed settings
export OPIK_CC_PROJECT="my-project"         # Project name (default: claude-code); supports {field} tokens — see Enterprise Install
export OPIK_CC_WORKSPACE="my-workspace"     # Workspace override (default: OPIK_WORKSPACE / ~/.opik.config)
export OPIK_CC_TRUNCATE_FIELDS="false"      # Don't truncate large fields

All plugin env vars use the OPIK_CC_ prefix to avoid conflicts with standard Opik SDK variables.

OPIK_CC_WORKSPACE and OPIK_CC_PROJECT let you send Claude Code traces to a different workspace/project than the rest of your Opik setup, without touching the global OPIK_WORKSPACE in your environment. You can also keep the plugin's settings in a dedicated [opik_cc] section of ~/.opik.config:

[opik]
url_override = https://www.comet.com/opik/api/
api_key = your-api-key
workspace = my-sdk-workspace      # used by the Opik SDK
project_name = my-sdk-project     # used by the Opik SDK

[opik_cc]
workspace = comet-all             # used by the Claude Code plugin
project_name = claude-code        # used by the Claude Code plugin

Place [opik_cc] below [opik]. The plugin reads the keys it recognizes (workspace, project_name, url_override, api_key) from the whole file, with later values overriding earlier ones — so the [opik_cc] values win only when that section comes last. The environment variables (OPIK_CC_WORKSPACE, OPIK_CC_PROJECT) always take precedence over the file.

You can also override url_override and api_key in [opik_cc] to point Claude Code traces at a different Opik instance than the SDK:

[opik_cc]
url_override = https://my-other-opik/api/   # different Opik instance for the plugin
api_key = other-instance-api-key            # must match that instance
workspace = comet-all
project_name = claude-code

Set url_override and api_key together — a URL pointing at one instance with the other instance's key will fail auth. OPIK_BASE_URL (env) is the simpler way to point only the plugin at a different URL, and always wins over the file.

Link Claude Code sessions to existing Opik traces (useful for embedding Claude Code in larger workflows):

export OPIK_CC_PARENT_TRACE_ID="your-trace-id"  # Attach to existing trace
export OPIK_CC_ROOT_SPAN_ID="your-span-id"      # Set parent span for all Claude Code spans

The Opik MCP server provides Claude with tools to interact with your Opik data - query traces, analyze experiments, and access evaluation results directly in conversation.

Add to your ~/.claude.json:

{
  "mcpServers": {
    "opik": {
      "command": "npx",
      "args": ["-y", "opik-mcp", "--apiKey", "YOUR_OPIK_API_KEY"]
    }
  }
}

Replace YOUR_OPIK_API_KEY with your API key from comet.com.

{
  "mcpServers": {
    "opik": {
      "command": "npx",
      "args": ["-y", "opik-mcp", "--apiBaseUrl", "http://localhost:5173/api"]
    }
  }
}

Adjust the apiBaseUrl to match your Opik instance.

Copy-ready configurations are available in mcp-configs/mcp-servers.json.

Enable/disable automatic tracing of your Claude Code sessions to Opik.

/opik:trace-claude-code start                 # Enable tracing for this project
/opik:trace-claude-code start --debug         # Enable tracing + debug logging
/opik:trace-claude-code stop                  # Disable tracing for this project
/opik:trace-claude-code status                # Check project + global + effective state

/opik:trace-claude-code start --global        # Enable tracing for all projects
/opik:trace-claude-code stop --global         # Disable tracing globally

Tracing state is stored in .claude/.opik-tracing-enabled (project) or ~/.claude/.opik-tracing-enabled (global). Resolution order (first match wins):

1. Project file containing off/disabled → disabled (opt a single project out of a global enable)
2. Project file present → enabled (debug content also enables debug logging)
3. Global file present → enabled (same content rules)
4. Neither → disabled

So the project setting always takes precedence over the global one. Running stop in a project while global tracing is on writes the off opt-out for that project rather than removing the global enable.

Note: Changes take effect immediately for new conversation turns (no restart needed).

Automatically detect frameworks in your code and add the correct Opik integration.

/opik:instrument my_agent.py        # Add tracing to a specific file
/opik:instrument                    # Analyze current context and add tracing

Supports automatic detection and integration for:

• Python: OpenAI, Anthropic, LangChain, LlamaIndex, CrewAI, Bedrock, Groq, LiteLLM
• TypeScript: OpenAI, LangChain, Vercel AI SDK
• Custom code: Adds @opik.track decorators or Opik client usage

The command ensures tracing starts at your entry point (critical for replay capability) and uses the correct span types.

Comprehensive guidance on:

• Opik setup and configuration
• Tracing with Python/TypeScript SDKs
• 80+ framework integrations (LangChain, CrewAI, OpenAI, Anthropic, etc.)
• Evaluation with 41 built-in metrics
• Production monitoring, guardrails, and debugging

Reviews agent code for:

• Idempotence and retry safety
• Security vulnerabilities
• Architecture patterns
• State management
• Observability hooks

opik-claude-code-plugin/
├── .claude-plugin/
│   ├── plugin.json         # Plugin manifest
│   └── marketplace.json    # Marketplace definition
├── hooks/
│   └── hooks.json          # Hook configuration
├── scripts/
│   └── opik-logger         # Platform selector script
├── bin/
│   └── opik-logger-*       # Compiled binaries (darwin/linux, amd64/arm64)
├── src/
│   └── *.go                # Go source code
├── skills/
│   └── agent-ops/          # Observability skill + references
├── agents/
│   └── agent-reviewer.md   # Agent review agent
├── commands/
│   ├── trace-claude-code.md  # /opik:trace-claude-code command
│   └── instrument.md         # /opik:instrument command
└── mcp-configs/
    └── mcp-servers.json    # MCP server configurations

make build        # Build for all platforms
make build-local  # Build for current platform only