Langfuse Observability Plugin for Claude Code
Trace every Claude Code session 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
Restart Claude Code after install.
On enable, you'll be prompted for:
| 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). |
Get keys from your Langfuse project settings → API Keys.
Requirements
One of:
- 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).
If neither is set up, the hook exits silently — no impact on Claude Code.
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.
State is kept in ~/.claude/state/langfuse_state.json so re-runs only emit new turns.
Privacy
This plugin transmits your Claude Code session data — conversation turns, assistant
generations, tool calls, and token-usage statistics — to the Langfuse endpoint you
configure (LANGFUSE_BASE_URL, default https://us.cloud.langfuse.com; EU and
self-hosted endpoints are supported). Data is sent at the end of each turn (the
Stop hook) and at session end (SessionEnd) using the Langfuse API keys you
provide, which are stored in your OS keychain. No data is sent anywhere other than
the endpoint you configure.
For how Langfuse Cloud handles data it receives, see the Langfuse privacy policy:
https://langfuse.com/privacy . When using a self-hosted Langfuse instance, your data
stays within your own infrastructure.
Reconfigure
claude plugin disable langfuse-observability
claude plugin enable langfuse-observability
Uninstall
claude plugin uninstall langfuse-observability
Troubleshooting
- Nothing in Langfuse: check
~/.claude/state/langfuse_hook.log (enable CC_LANGFUSE_DEBUG).
- 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.
License
MIT
