diff --git a/CLAUDE.md b/CLAUDE.md index f9954e7..450ff1b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -162,6 +162,14 @@ This is a Mintlify site. Pages are `.mdx`, navigation lives in `docs.json`, reus - **Signal/alert enable-disable** (LAM-1858, docs LAM-1927): the `disabled` flag lives in the JSONB `metadata` column of `signals` / `alerts` (absent = enabled, only persisted when true; migration 0102 moved `sample_rate` into `signals.metadata` — staging Postgres lagged this one, apply the committed SQL if `s.metadata` errors). UI surface is in the OSS repo, so screenshots come from the local `lmnr` prod stack. Docs vocabulary: the UI switch label is **Active**/**Inactive**, the signals-list badge and section header say **Disabled** — use "pause"/"paused" for the verb in prose, and never invent an "Enabled" badge. Disabled signals reject backfills (403) and skip trigger evaluation but keep events/clusters; disabled alerts only silence notifications. - Alert trigger labels in the UI come from `ALERT_TYPE_LABELS` in `frontend/lib/actions/alerts/types.ts`: `SIGNAL_EVENT` → **New event**, `NEW_CLUSTER` → **New cluster**. Docs should use these user-facing labels, not the raw enum names, when describing the trigger picker or alert rows. +## Claude Code and Codex plugin integrations + +- Pages: `tracing/integrations/claude-code.mdx` and `tracing/integrations/codex.mdx` (LAM-1968), listed FIRST in the Coding agents section of `docs.json` and `tracing/integrations/overview.mdx`, before Claude Agent SDK / OpenCode. Source repos: `github.com/lmnr-ai/lmnr-claude-code-plugin` and `lmnr-ai/lmnr-codex-plugin` (not under `/repos`; clone to inspect). CLI installer lives in `lmnr-ts/packages/lmnr-cli/src/commands/plugin/index.ts` (`AGENTS` registry is the source of truth for marketplace refs, install verbs, and config filenames). +- Canonical install is `npx lmnr-cli@latest plugin add claude-code|codex` (shipped in `lmnr-cli` 0.3.2). It is GLOBAL and directory-independent: never touches `.lmnr/project.json` or `.env`; the minted key goes to `~/.config/lmnr/-plugin.json` (0600) as `{ projectApiKey, baseUrl }`, which is the plugin's primary config source. `LMNR_PROJECT_API_KEY` / `LMNR_BASE_URL` env override the file. Don't document `--config` flags or the old Codex curl-bundle/launcher/config.toml flow — both were replaced by native marketplace installs. +- **The manual-install plugin ref is `lmnr@lmnr` for BOTH agents** (`claude plugin install lmnr@lmnr --scope user`; `codex plugin add lmnr@lmnr`). The Claude plugin repo's README still says `laminar@laminar` — that's stale; the `.claude-plugin/marketplace.json` manifest (marketplace `lmnr`, plugin `lmnr`) and the published CLI both use `lmnr@lmnr`. +- Activation differs per agent and must stay distinct in docs: Claude Code has `/reload-plugins` (or restart in a NEW terminal window — relaunching in the same terminal can reuse the previous session and skip the plugin); Codex has no in-session reload, so restart. +- Self-hoster wiring: `plugin add` takes `--frontend-url` (auth issuer, mints the key via `POST /api/cli/api-key`) and `--base-url` (written to the config file verbatim; the plugin POSTs OTLP/JSON to `/v1/traces`, so the URL must carry the API port, e.g. `http://localhost:8000`). Unlike the SDK's `base_url` + `http_port` split, the plugin config's `baseUrl` INCLUDES the port. + ## Claude Agent SDK integration - Public TS API is `Laminar.wrapClaudeAgentQuery(originalQuery)` (alias: module-level `instrumentClaudeAgentQuery`). Document the static-method form; it's the one in the TSDoc example. diff --git a/changelog.mdx b/changelog.mdx index 8dce7d4..18e1246 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -6,6 +6,7 @@ New releases and improvements. ## July 2026 +- **Claude Code and Codex plugins** - Trace [Claude Code](/tracing/integrations/claude-code) and [OpenAI Codex CLI](/tracing/integrations/codex) sessions in Laminar with a one-command install: `npx lmnr-cli@latest plugin add claude-code` (or `codex`) logs you in, picks a project, mints a key, and installs the plugin. Each turn becomes a trace with LLM calls, tool executions, and (for Claude Code) subagents, grouped into one session per conversation. - **Generate render templates in the editor** - The [render template](/platform/render-templates#generate-a-template) editor now generates the JSX for you: name the template, describe the view you want, click **Generate**, and iterate with **Request changes**. For trace templates, generation also writes the span filter from an outline of the trace's real spans and refreshes the sample data against it. No more copying a prompt to an external AI tool, though the **Copy prompt** fallback remains in the Code tab. - **Enable or disable Signals and alerts** - [Pause a Signal](/signals/quickstart#pause-and-resume-a-signal) with the **Active** switch in its settings: new traces stop being evaluated while existing events and clusters are kept, and paused Signals are grouped under a **Disabled** section on the Signals list. [Alerts](/signals/alerts#enable-or-disable-an-alert) get the same treatment, with an on/off switch directly on each alert card to silence notifications without losing the alert's configuration. - **Evaluations UI refresh** - The [evaluations page](/evaluations/comparing-runs) now has a groups sidebar with run counts, a combined progression chart with one line per score dimension (legend toggles, per-run eye icons to exclude runs), and an aggregation picker (Average, Sum, Min, Max, Median, p90/p95/p99). The run detail page is a split view with the datapoint table next to an always-open trace panel, and side-by-side comparison shows `old → new` deltas on the score card and on every row. diff --git a/docs.json b/docs.json index 95d0204..7a8eb2d 100644 --- a/docs.json +++ b/docs.json @@ -31,6 +31,8 @@ "tracing/integrations/anthropic", "tracing/integrations/openai", "tracing/integrations/gemini", + "tracing/integrations/claude-code", + "tracing/integrations/codex", "tracing/integrations/claude-agent-sdk", "tracing/integrations/openai-agents-sdk", "tracing/integrations/opencode", diff --git a/tracing/integrations/claude-code.mdx b/tracing/integrations/claude-code.mdx new file mode 100644 index 0000000..271b7be --- /dev/null +++ b/tracing/integrations/claude-code.mdx @@ -0,0 +1,73 @@ +--- +title: Claude Code Plugin +sidebarTitle: Claude Code +--- + +## Overview + +The Claude Code plugin traces every local [Claude Code](https://claude.com/claude-code) session: each turn becomes a full trace with its LLM calls, tool executions, and subagents, sent to Laminar. + +## Install + + + + +```bash +npx lmnr-cli@latest plugin add claude-code +``` + +The CLI logs you in (browser device flow), lets you pick the Laminar project that should receive your Claude Code traces, mints a project API key named after the plugin and your machine, writes it to `~/.config/lmnr/claude-code-plugin.json`, and installs the plugin through Claude Code's own plugin marketplace. + + +Pick a dedicated project for coding-agent traces so they don't mix with your application's traces. The setup is global and directory-independent: it never touches `.lmnr/project.json` or your `.env`. + + + + + +Run `/reload-plugins` in an open Claude Code session, or quit Claude Code and start it in a new terminal window. + + + + +Every turn becomes a trace in the project you picked. Open the Laminar dashboard to watch them land in realtime. + + + + + +**Self-hosting Laminar?** The same command works against your instance: pass your frontend URL (the auth issuer) and your API URL, including the API port: + +```bash +npx lmnr-cli@latest plugin add claude-code \ + --frontend-url https://laminar.example.com \ + --base-url https://api.laminar.example.com +``` + + +### Manual install + +If you'd rather not use `lmnr-cli`, install the plugin with Claude Code's plugin commands and create the config file yourself: + +```bash +claude plugin marketplace add lmnr-ai/lmnr-claude-code-plugin +claude plugin install lmnr@lmnr --scope user +``` + +Then create `~/.config/lmnr/claude-code-plugin.json` with a project API key. Get one from the Laminar dashboard under **Settings → Project API Keys** (create a dedicated key so it's clear it belongs to the plugin): + +```json ~/.config/lmnr/claude-code-plugin.json +{ "projectApiKey": "your-project-api-key", "baseUrl": "https://api.lmnr.ai" } +``` + +`projectApiKey` is required. `baseUrl` is optional and defaults to `https://api.lmnr.ai`; self-hosters set it to their instance's API URL (for example `http://localhost:8000`). + +## Configuration + +The plugin reads its config from `~/.config/lmnr/claude-code-plugin.json`, written by `lmnr-cli plugin add claude-code`: + +```json +{ "projectApiKey": "...", "baseUrl": "https://api.lmnr.ai" } +``` + +The environment variables `LMNR_PROJECT_API_KEY` and `LMNR_BASE_URL` override the file when set, which is handy for CI or a shell you already have configured. Traces are attributed to the identity from `lmnr-cli login` when present; set `LMNR_USER_ID` to override the user id attached to traces. diff --git a/tracing/integrations/codex.mdx b/tracing/integrations/codex.mdx new file mode 100644 index 0000000..fac4b88 --- /dev/null +++ b/tracing/integrations/codex.mdx @@ -0,0 +1,73 @@ +--- +title: Codex Plugin +sidebarTitle: Codex +--- + +## Overview + +The Codex plugin traces every local [OpenAI Codex CLI](https://github.com/openai/codex) session: each turn becomes a full trace with its LLM calls and tool executions, sent to Laminar. + +## Install + + + + +```bash +npx lmnr-cli@latest plugin add codex +``` + +The CLI logs you in (browser device flow), lets you pick the Laminar project that should receive your Codex traces, mints a project API key named after the plugin and your machine, writes it to `~/.config/lmnr/codex-plugin.json`, and installs the plugin through Codex's native plugin marketplace. + + +Pick a dedicated project for coding-agent traces so they don't mix with your application's traces. The setup is global and directory-independent: it never touches `.lmnr/project.json` or your `.env`. + + + + + +Codex loads plugins at startup, so restart it to activate the plugin. + + + + +Every turn becomes a trace in the project you picked. Open the Laminar dashboard to watch them land in realtime. + + + + + +**Self-hosting Laminar?** The same command works against your instance: pass your frontend URL (the auth issuer) and your API URL, including the API port: + +```bash +npx lmnr-cli@latest plugin add codex \ + --frontend-url https://laminar.example.com \ + --base-url https://api.laminar.example.com +``` + + +### Manual install + +If you'd rather not use `lmnr-cli`, install the plugin with Codex's plugin commands and create the config file yourself: + +```bash +codex plugin marketplace add lmnr-ai/lmnr-codex-plugin +codex plugin add lmnr@lmnr +``` + +Then create `~/.config/lmnr/codex-plugin.json` with a project API key. Get one from the Laminar dashboard under **Settings → Project API Keys** (create a dedicated key so it's clear it belongs to the plugin): + +```json ~/.config/lmnr/codex-plugin.json +{ "projectApiKey": "your-project-api-key", "baseUrl": "https://api.lmnr.ai" } +``` + +`projectApiKey` is required. `baseUrl` is optional and defaults to `https://api.lmnr.ai`; self-hosters set it to their instance's API URL (for example `http://localhost:8000`). + +## Configuration + +The plugin reads its config from `~/.config/lmnr/codex-plugin.json`, written by `lmnr-cli plugin add codex`: + +```json +{ "projectApiKey": "...", "baseUrl": "https://api.lmnr.ai" } +``` + +The environment variables `LMNR_PROJECT_API_KEY` and `LMNR_BASE_URL` override the file when set, which is handy for CI or a shell you already have configured. Traces are attributed to the identity from `lmnr-cli login` when present; set `LMNR_USER_ID` to override the user id attached to traces. diff --git a/tracing/integrations/overview.mdx b/tracing/integrations/overview.mdx index b302828..f74ccee 100644 --- a/tracing/integrations/overview.mdx +++ b/tracing/integrations/overview.mdx @@ -69,6 +69,12 @@ Multi-step agents, tool calls, and subagents render as a transcript instead of a ## Coding agents + + Trace Claude Code sessions with a one-command plugin install. + + + Trace OpenAI Codex CLI sessions with a one-command plugin install. + Trace Claude Agent SDK runs and subagents.