{"id":50506609,"url":"https://github.com/comet-ml/opik-claude-code-plugin","last_synced_at":"2026-06-02T17:00:27.230Z","repository":{"id":341309233,"uuid":"1155404928","full_name":"comet-ml/opik-claude-code-plugin","owner":"comet-ml","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-03T16:18:58.000Z","size":41584,"stargazers_count":14,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T17:29:19.294Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/comet-ml.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T13:30:46.000Z","updated_at":"2026-04-03T16:19:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/comet-ml/opik-claude-code-plugin","commit_stats":null,"previous_names":["comet-ml/opik-claude-code-plugin"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/comet-ml/opik-claude-code-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-claude-code-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-claude-code-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-claude-code-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-claude-code-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/comet-ml","download_url":"https://codeload.github.com/comet-ml/opik-claude-code-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comet-ml%2Fopik-claude-code-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33831629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-02T17:00:17.335Z","updated_at":"2026-06-02T17:00:27.220Z","avatar_url":"https://github.com/comet-ml.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Opik Claude Code Plugin\n\nLog Claude Code sessions to [Opik](https://github.com/comet-ml/opik) for LLM observability, plus skills and agents for building observable AI applications.\n\n## Features\n\n- **Session Tracing**: Automatically log Claude Code sessions as Opik traces\n- **Span Tracking**: Each tool call becomes a span within the trace\n- **Subagent Support**: Nested agent calls are tracked with parent-child relationships\n- **Skills**: Built-in knowledge for LLM observability, tracing, and evaluation\n- **Agents**: Code review agent for agent architecture best practices\n\n## How Tracing Works\nWe trigger tracing for everything done in Claude Code, but don't slow you down.\n\n\u003cimg src=\"assets/readme_diagram.svg\" alt=\"How Tracing Works\" width=\"600\"\u003e\n\nEach conversation turn becomes an Opik trace. Tool calls, thoughts, and responses become spans. Subagent invocations are nested under their parent Task span.\n\n## Installation\n\nFrom within Claude Code:\n\n```\n/plugin marketplace add comet-ml/opik-claude-code-plugin\n```\n\nThen install the plugin:\n\n```\n/plugin install opik\n```\n\n### Local Install (for contributors)\n\nIf you've cloned the repo locally, add it as a marketplace and install from there:\n\n```\n/plugin marketplace add /path/to/opik-claude-code-plugin\n/plugin install opik\n```\n\n**Important:** Restart any running Claude Code sessions after installation. Hooks only load when a session starts.\n\n## Configuration\n\nRun the Opik CLI to configure your connection:\n\n```bash\npip install opik\nopik configure\n```\n\nThis creates `~/.opik.config` with your API URL, key, and workspace.\n\n### Optional Environment Variables\n\n```bash\nexport OPIK_CC_PROJECT=\"my-project\"         # Project name (default: claude-code)\nexport OPIK_CC_WORKSPACE=\"my-workspace\"     # Workspace override (default: OPIK_WORKSPACE / ~/.opik.config)\nexport OPIK_CC_TRUNCATE_FIELDS=\"false\"      # Don't truncate large fields\n```\n\nAll plugin env vars use the `OPIK_CC_` prefix to avoid conflicts with standard Opik SDK variables.\n\n`OPIK_CC_WORKSPACE` and `OPIK_CC_PROJECT` let you send Claude Code traces to a different\nworkspace/project than the rest of your Opik setup, without touching the global\n`OPIK_WORKSPACE` / `project_name` in `~/.opik.config` used by the Opik SDK. Both can also be\nset in `~/.opik.config` via the plugin-scoped `cc_workspace` and `cc_project` keys:\n\n```ini\n[opik]\nworkspace = my-sdk-workspace      # used by the Opik SDK\nproject_name = my-sdk-project     # used by the Opik SDK\ncc_workspace = my-cc-workspace        # used only by the Claude Code plugin\ncc_project_name = my-cc-project       # used only by the Claude Code plugin\n```\n\n\u003e Note: for backward compatibility, if `cc_project_name` is not set the plugin still falls back\n\u003e to the shared `project_name` key.\n\n### External Trace Linking\n\nLink Claude Code sessions to existing Opik traces (useful for embedding Claude Code in larger workflows):\n\n```bash\nexport OPIK_CC_PARENT_TRACE_ID=\"your-trace-id\"  # Attach to existing trace\nexport OPIK_CC_ROOT_SPAN_ID=\"your-span-id\"      # Set parent span for all Claude Code spans\n```\n\n## MCP Server Setup\n\nThe [Opik MCP server](https://github.com/comet-ml/opik-mcp) provides Claude with tools to interact with your Opik data - query traces, analyze experiments, and access evaluation results directly in conversation.\n\n### For Opik Cloud\n\nAdd to your `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"opik\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"opik-mcp\", \"--apiKey\", \"YOUR_OPIK_API_KEY\"]\n    }\n  }\n}\n```\n\nReplace `YOUR_OPIK_API_KEY` with your API key from [comet.com](https://www.comet.com).\n\n### For Self-Hosted Opik\n\n```json\n{\n  \"mcpServers\": {\n    \"opik\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"opik-mcp\", \"--apiBaseUrl\", \"http://localhost:5173/api\"]\n    }\n  }\n}\n```\n\nAdjust the `apiBaseUrl` to match your Opik instance.\n\n### Pre-configured Templates\n\nCopy-ready configurations are available in `mcp-configs/mcp-servers.json`.\n\n## Commands\n\n### `/opik:trace-claude-code` - Claude Code Session Tracing\n\nEnable/disable automatic tracing of your Claude Code sessions to Opik.\n\n```\n/opik:trace-claude-code start                 # Enable tracing for this project\n/opik:trace-claude-code start --debug         # Enable tracing + debug logging\n/opik:trace-claude-code stop                  # Disable tracing for this project\n/opik:trace-claude-code status                # Check project + global + effective state\n\n/opik:trace-claude-code start --global        # Enable tracing for all projects\n/opik:trace-claude-code stop --global         # Disable tracing globally\n```\n\nTracing state is stored in `.claude/.opik-tracing-enabled` (project) or `~/.claude/.opik-tracing-enabled` (global). Resolution order (first match wins):\n\n1. Project file containing `off`/`disabled` → **disabled** (opt a single project out of a global enable)\n2. Project file present → **enabled** (`debug` content also enables debug logging)\n3. Global file present → **enabled** (same content rules)\n4. Neither → **disabled**\n\nSo 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.\n\n**Note:** Changes take effect immediately for new conversation turns (no restart needed).\n\n### `/opik:instrument` - Add Observability to Your Code\n\nAutomatically detect frameworks in your code and add the correct Opik integration.\n\n```\n/opik:instrument my_agent.py        # Add tracing to a specific file\n/opik:instrument                    # Analyze current context and add tracing\n```\n\nSupports automatic detection and integration for:\n- **Python:** OpenAI, Anthropic, LangChain, LlamaIndex, CrewAI, Bedrock, Groq, LiteLLM\n- **TypeScript:** OpenAI, LangChain, Vercel AI SDK\n- **Custom code:** Adds `@opik.track` decorators or `Opik` client usage\n\nThe command ensures tracing starts at your entry point (critical for replay capability) and uses the correct span types.\n\n## Skills\n\n### `/opik:agent-ops` - LLM Observability Knowledge\n\nComprehensive guidance on:\n- Opik setup and configuration\n- Tracing with Python/TypeScript SDKs\n- 80+ framework integrations (LangChain, CrewAI, OpenAI, Anthropic, etc.)\n- Evaluation with 41 built-in metrics\n- Production monitoring, guardrails, and debugging\n\n## Agents\n\n### `agent-reviewer`\n\nReviews agent code for:\n- Idempotence and retry safety\n- Security vulnerabilities\n- Architecture patterns\n- State management\n- Observability hooks\n\n## Directory Structure\n\n```\nopik-claude-code-plugin/\n├── .claude-plugin/\n│   ├── plugin.json         # Plugin manifest\n│   └── marketplace.json    # Marketplace definition\n├── hooks/\n│   └── hooks.json          # Hook configuration\n├── scripts/\n│   └── opik-logger         # Platform selector script\n├── bin/\n│   └── opik-logger-*       # Compiled binaries (darwin/linux, amd64/arm64)\n├── src/\n│   └── *.go                # Go source code\n├── skills/\n│   └── agent-ops/          # Observability skill + references\n├── agents/\n│   └── agent-reviewer.md   # Agent review agent\n├── commands/\n│   ├── trace-claude-code.md  # /opik:trace-claude-code command\n│   └── instrument.md         # /opik:instrument command\n└── mcp-configs/\n    └── mcp-servers.json    # MCP server configurations\n```\n\n## Building from Source\n\n```bash\nmake build        # Build for all platforms\nmake build-local  # Build for current platform only\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomet-ml%2Fopik-claude-code-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcomet-ml%2Fopik-claude-code-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomet-ml%2Fopik-claude-code-plugin/lists"}