langfuse-observability

Langfuse Observability Plugin for Claude Code

Trace hook-backed Claude Code sessions to Langfuse — turns, generations, tool calls, and token usage — with zero code changes.

Install

claude plugin marketplace add langfuse/Claude-Observability-Plugin
claude plugin install langfuse-observability@langfuse-observability

The marketplace command registers the plugin marketplace and refreshes its local cache. The install command enables the plugin for your Claude Code user scope.

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. Run claude first, then type it at the session prompt:

$ claude
> /plugin configure langfuse-observability@langfuse-observability

Alternatively, pass configuration values during install:

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
LANGFUSE_SECRET_KEY	Your Langfuse secret key (sk-lf-...). Stored in your OS keychain.
LANGFUSE_PUBLIC_KEY	Your Langfuse public key (pk-lf-...).
LANGFUSE_BASE_URL	https://us.cloud.langfuse.com (default), https://cloud.langfuse.com for EU, or your self-hosted URL.
LANGFUSE_USER_ID	Optional. User identifier attached to every trace (shown as the user in Langfuse).
CC_LANGFUSE_DEBUG	Verbose logging to ~/.claude/state/langfuse_hook.log.
CC_LANGFUSE_MAX_CHARS	Truncate captured inputs/outputs to this many characters (default 20000).
CC_LANGFUSE_SKILL_TAGS	Tag traces with skill:<name> for every skill invoked in the turn (default true).
CC_LANGFUSE_CAPTURE_SKILL_CONTENT	Include injected skill instruction text in the Skill tool span output (default false).
CC_LANGFUSE_TRACE_SEED	Optional. Opt-in seed for deterministic trace IDs — see Deterministic trace IDs.
CC_LANGFUSE_TRACEPARENT	Optional, per run (env var, not plugin config). W3C traceparent of an existing trace to attach to — see Attach runs to an existing trace.
CC_LANGFUSE_PARENT_TRACE_ID / CC_LANGFUSE_PARENT_SPAN_ID	Optional, per run. Explicit alternative to CC_LANGFUSE_TRACEPARENT (32-hex trace id + 16-hex span id).

Get keys from your Langfuse project settings → API Keys.

Requirements

One of:

• 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.

On the first hook run, uv downloads the Langfuse SDK from PyPI (declared in the script header) and caches it. Offline or proxied machines fail this download and retry on every turn until the cache is warm; you can pre-warm it from a networked terminal:

echo '{}' | uv run --quiet --script <plugin-root>/hooks/langfuse_hook.py

If no usable runtime is set up, the hook exits without tracing, and Claude Code is never blocked or slowed. Failure reasons are written to ~/.claude/state/langfuse_hook.log (see Troubleshooting).

How it works

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.

Deterministic trace IDs