From ba26d523d732465a45055be690b69aebef9cdb4e Mon Sep 17 00:00:00 2001 From: Milana Gurbanova Date: Fri, 3 Jul 2026 13:50:30 +0200 Subject: [PATCH 1/4] docs: clarify plugin configuration after install --- README.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 39c416f..b41a254 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,22 @@ claude plugin install langfuse-observability@langfuse-observability Restart Claude Code after install. -On enable, you'll be prompted for: +Then configure the plugin from within Claude Code: + +```text +/plugin configure langfuse-observability@langfuse-observability +``` + +Alternatively, pass configuration values during install: + +```bash +claude plugin install langfuse-observability@langfuse-observability \ + --config LANGFUSE_PUBLIC_KEY=pk-lf-... \ + --config LANGFUSE_SECRET_KEY=sk-lf-... \ + --config LANGFUSE_BASE_URL=https://cloud.langfuse.com +``` + +The plugin requires or accepts: | Field | Description | | --------------------- | ---------------------------------------------------------------------------------------------------- | @@ -57,9 +72,10 @@ stays within your own infrastructure. ## Reconfigure -```bash -claude plugin disable langfuse-observability -claude plugin enable langfuse-observability +In Claude Code, run: + +```text +/plugin configure langfuse-observability@langfuse-observability ``` ## Uninstall From d6a51f14ea41f0b203223eb9d9aff347b3aaa946 Mon Sep 17 00:00:00 2001 From: Milana Gurbanova Date: Fri, 3 Jul 2026 15:26:13 +0200 Subject: [PATCH 2/4] docs: clarify Claude Code plugin setup --- README.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index b41a254..8f6f4f0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Langfuse Observability Plugin for Claude Code -Trace every Claude Code session to [Langfuse](https://langfuse.com) — turns, generations, tool calls, and token usage — with zero code changes. +Trace hook-backed Claude Code sessions to [Langfuse](https://langfuse.com) — turns, generations, tool calls, and token usage — with zero code changes. ## Install @@ -9,9 +9,11 @@ claude plugin marketplace add langfuse/Claude-Observability-Plugin claude plugin install langfuse-observability@langfuse-observability ``` -Restart Claude Code after install. +The marketplace command registers the plugin marketplace and refreshes its local cache. The install command enables the plugin for your Claude Code user scope. -Then configure the plugin from within Claude Code: +Restart Claude Code after install so the hook configuration is loaded. + +Then configure the plugin from within a Claude Code session. This is a Claude Code slash command, not a shell command: ```text /plugin configure langfuse-observability@langfuse-observability @@ -54,6 +56,19 @@ If neither is set up, the hook exits silently — no impact on Claude Code. A hook reads the session transcript incrementally on every turn (Stop) and at session end (SessionEnd), and emits a Langfuse trace with one span per turn, nested generations per assistant message, and child tool spans for every tool call. Token usage is captured when present. +The plugin observes only data that Claude Code exposes through hooks and transcript files. + +Captured: + +- Claude Code CLI sessions +- Claude Code GUI Code mode sessions + +Not captured: + +- Regular Claude Desktop Chat mode conversations + +If you use the desktop app, switch to Code mode for hook-backed tracing. Regular Chat mode does not invoke Claude Code Stop or SessionEnd hooks and does not write the transcript file this plugin reads. + State is kept in `~/.claude/state/langfuse_state.json` so re-runs only emit new turns. ## Privacy @@ -87,6 +102,7 @@ claude plugin uninstall langfuse-observability ## Troubleshooting - Nothing in Langfuse: check `~/.claude/state/langfuse_hook.log` (enable `CC_LANGFUSE_DEBUG`). +- Desktop chat has no traces: regular Claude Desktop Chat mode is not hook-backed. Use the `claude` CLI or Claude Code GUI Code mode. - Hook not firing: confirm with `claude plugin list` that langfuse-observability is enabled; restart Claude Code. - langfuse import errors (no uv): ensure the `python3` on your PATH has the SDK installed, or install uv. From 761330c5b29e38df83b94f5c65985295917f1e12 Mon Sep 17 00:00:00 2001 From: Milana Gurbanova Date: Fri, 3 Jul 2026 15:54:09 +0200 Subject: [PATCH 3/4] docs: clarify disabling Langfuse tracing --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index 8f6f4f0..bbec2ae 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,25 @@ In Claude Code, run: /plugin configure langfuse-observability@langfuse-observability ``` +## Disable tracing + +To stop tracing for new Claude Code CLI sessions and new Claude Code GUI Code mode sessions, disable the plugin: + +```bash +claude plugin disable langfuse-observability@langfuse-observability --scope user +claude plugin list +``` + +`claude plugin list` should show the plugin as disabled. This keeps the plugin installed and does not delete your configuration. + +To enable tracing again: + +```bash +claude plugin enable langfuse-observability@langfuse-observability --scope user +``` + +If a Claude Code session is already running, restart it after disabling the plugin. Running sessions may have loaded their hooks at startup, so disabling the plugin is intended for new sessions. + ## Uninstall ```bash From 722305494a36a7ae09f28c79387ca54068ede4f2 Mon Sep 17 00:00:00 2001 From: Milana Gurbanova Date: Fri, 3 Jul 2026 17:09:14 +0200 Subject: [PATCH 4/4] docs: clarify plugin runtime requirements --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index bbec2ae..254f0d1 100644 --- a/README.md +++ b/README.md @@ -47,8 +47,8 @@ Get keys from your Langfuse project settings → API Keys. One of: -- [uv](https://docs.astral.sh/uv/) (recommended) — installs the langfuse SDK automatically, no setup needed. -- Python 3.10+ as `python3` with `pip install "langfuse>=4.0,<5"` (fallback when uv is not on PATH). +- [uv](https://docs.astral.sh/uv/) (recommended) on `PATH`. The hook uses `uv run --script` and installs the Langfuse SDK from the script metadata automatically. +- Python 3.10+ as `python3` with `langfuse>=4.0,<5` installed in that Python environment. This is only used as a fallback when `uv` is not on `PATH`. If neither is set up, the hook exits silently — no impact on Claude Code. @@ -123,7 +123,7 @@ claude plugin uninstall langfuse-observability - Nothing in Langfuse: check `~/.claude/state/langfuse_hook.log` (enable `CC_LANGFUSE_DEBUG`). - Desktop chat has no traces: regular Claude Desktop Chat mode is not hook-backed. Use the `claude` CLI or Claude Code GUI Code mode. - Hook not firing: confirm with `claude plugin list` that langfuse-observability is enabled; restart Claude Code. -- langfuse import errors (no uv): ensure the `python3` on your PATH has the SDK installed, or install uv. +- langfuse import errors (no uv): install uv, or ensure the `python3` on your PATH is Python 3.10+ and has `langfuse>=4.0,<5` installed. ## License