Claude Code Tracing with Langfuse

Install the Langfuse Claude Code tracing integration in this repository by following the latest manual guide from langfuse.com. Please:
1. install or update the Python langfuse package
2. download the latest Langfuse Claude Code hook scripts into ~/.claude/hooks
3. merge the Langfuse hook entries into ~/.claude/settings.json without removing unrelated hooks
4. create or update .claude/settings.local.json with TRACE_TO_LANGFUSE, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL, and LANGFUSE_PROJECT_ID
5. install a prepare-commit-msg wrapper that preserves any existing hook by chaining prepare-commit-msg.pre-langfuse
6. add .langfuse/ and .claude/settings.local.json to .gitignore
7. verify the setup with a short Claude Code session and one commit

This guide explains how to manually install the same hook-based Claude Code tracing workflow that was proposed in langfuse-cli PR #3, without requiring the CLI automation itself.

What is Claude Code? Claude Code is Anthropic’s agentic coding tool that lives in your terminal. It can inspect your codebase, edit files, run commands, and complete multi-step coding tasks.

What is Langfuse? Langfuse is the open-source LLM engineering platform. It helps you trace agent behavior, understand tool use, analyze latency and costs, and evaluate outputs.

Why this integration matters

The updated integration is designed to create a durable link between:

• the Claude Code session in Langfuse
• the trace(s) and tool calls emitted from that session
• the git commit created during that session
• the files changed by that commit in the local repository

That makes it easier to answer questions like:

• Is your Claude Code subscription worth it, or should you switch to a bring-your-own-key setup?
• How do latency and activity change by time of day, region, or developer?
• What prompts, tool calls, and intermediate steps led to a specific code change?

What changed from the original guide

The earlier version of this page documented a single Stop hook and one Python script. After reviewing langfuse-cli PR #3, the newer hook stack is more complete and materially better for code-to-trace linking:

• It adds a PreToolUse session-init hook that creates a deterministic Langfuse trace_id from Claude Code’s session_id before the first tool runs.
• It keeps the Stop hook, but upgrades it to the latest incremental transcript reader that emits detailed generation and tool observations.
• It adds a SessionEnd hook as a final flush point for the same tracing script.
• It adds a PostToolUse Bash hook that detects git commit executions, enriches tracing with git metadata, and writes repo-local manifest files under .langfuse/.
• It adds a git prepare-commit-msg hook that appends a Langfuse-Session: trailer to commit messages and preserves any existing hook by chaining it.
• It adds shared utilities so all hook scripts use the same state files, manifest writers, git helpers, and debug logging.

How the updated hook stack works

Manual installation

mkdir -p ~/.claude/hooks ~/.claude/state
python3 -m pip install --upgrade langfuse

curl -fsSL https://raw.githubusercontent.com/langfuse/langfuse-cli/main/hooks/langfuse_utils.py -o ~/.claude/hooks/langfuse_utils.py
curl -fsSL https://raw.githubusercontent.com/langfuse/langfuse-cli/main/hooks/langfuse_session_init_hook.py -o ~/.claude/hooks/langfuse_session_init_hook.py
curl -fsSL https://raw.githubusercontent.com/langfuse/langfuse-cli/main/hooks/langfuse_hook.py -o ~/.claude/hooks/langfuse_hook.py
curl -fsSL https://raw.githubusercontent.com/langfuse/langfuse-cli/main/hooks/langfuse_git_commit_hook.py -o ~/.claude/hooks/langfuse_git_commit_hook.py
curl -fsSL https://raw.githubusercontent.com/langfuse/langfuse-cli/main/hooks/langfuse_prepare_commit_msg.py -o ~/.claude/hooks/langfuse_prepare_commit_msg.py
 
chmod +x ~/.claude/hooks/langfuse_*.py

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/langfuse_session_init_hook.py"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/langfuse_hook.py"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/langfuse_hook.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/langfuse_git_commit_hook.py"
          }
        ]
      }
    ]
  }
}

{
  "env": {
    "TRACE_TO_LANGFUSE": "true",
    "LANGFUSE_PUBLIC_KEY": "pk-lf-...",
    "LANGFUSE_SECRET_KEY": "sk-lf-...",
    "LANGFUSE_BASE_URL": "https://cloud.langfuse.com",
    "LANGFUSE_PROJECT_ID": "cloramnkj0002jz088vzn1ja4"
  }
}

if [ -f .git/hooks/prepare-commit-msg ] && ! rg -q "langfuse-trace-trailer" .git/hooks/prepare-commit-msg; then
  mv .git/hooks/prepare-commit-msg .git/hooks/prepare-commit-msg.pre-langfuse
fi
 
cat > .git/hooks/prepare-commit-msg <<'EOF'
#!/bin/sh
# langfuse-trace-trailer — installed manually
python3 ~/.claude/hooks/langfuse_prepare_commit_msg.py "$@" 2>/dev/null || true
if [ -x "$(dirname "$0")/prepare-commit-msg.pre-langfuse" ]; then
    "$(dirname "$0")/prepare-commit-msg.pre-langfuse" "$@"
fi
EOF
 
chmod +x .git/hooks/prepare-commit-msg

.langfuse/
.claude/settings.local.json

git log -1 --pretty=%B

Langfuse-Session: https://cloud.langfuse.com/project/<project-id>/sessions/<session-id>

What gets linked together

The hook stack produces both Langfuse traces and repo-local metadata so you can move between code, commits, sessions, and traces.

A typical .langfuse/traces/<session-id>.json file looks like this:

{
  "schema_version": 1,
  "langfuse": {
    "trace_id": "bcee2dea6c117f48ee1e51f01c6b67bc",
    "trace_url": "https://cloud.langfuse.com/trace/bcee2dea6c117f48ee1e51f01c6b67bc",
    "session_id": "b1bccb92-3cd3-4988-bbd9-9b46a7d01cba",
    "session_url": "https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/sessions/b1bccb92-3cd3-4988-bbd9-9b46a7d01cba",
    "host": "https://cloud.langfuse.com"
  },
  "git": {
    "commit_sha": "6636a89b6bafd03ddf437503b2f60c84",
    "commit_url": "https://github.com/org/repo/commit/6636a89b6bafd03ddf437503b2f60c84",
    "branch": "main",
    "commit_message": "test: update README comment for Langfuse tracing integration test"
  }
}

This is the key link model:

• Claude Code session -> Langfuse trace via deterministic trace_id generation in PreToolUse
• Langfuse trace -> repo metadata via .langfuse/current-session.json and .langfuse/traces/<session-id>.json
• Git commit -> Langfuse session via the Langfuse-Session: commit trailer
• Changed files -> trace URL via .langfuse/traces/agent-trace-<commit>.json

If you want the strongest possible link between code and tracing data, ask Claude Code itself to run the final git commit command. That guarantees the Bash PostToolUse hook and the git prepare-commit-msg hook both execute in the same agent session.

How to use the data in Langfuse

Once this setup is installed, you can use Langfuse to answer the questions that matter for agent-assisted coding:

• Cost and ROI: Compare the number, duration, and cost of Claude Code sessions with the quality and speed of code changes.
• Latency patterns: Inspect turn and tool timings by session, user, or time window to see whether latency changes during busy hours.
• Change provenance: Start from a commit, jump to the Langfuse session, and inspect the prompts, responses, and tool calls that produced the code.
• Operational debugging: Filter traces by session_id, commit_sha, github_commit_url, or the claude-code tag.

The latest Stop hook also records detailed tool observations, including Bash commands, so Langfuse becomes a practical debugging surface for understanding how a code change happened, not just that it happened.

Troubleshooting

No traces appear in Langfuse

1. Verify that .claude/settings.local.json contains TRACE_TO_LANGFUSE: "true" and valid Langfuse credentials.
2. Confirm the Langfuse SDK is installed:

python3 -m pip show langfuse

3. Check the hook log:

tail -f ~/.claude/state/langfuse_hook.log

4. Make sure ~/.claude/settings.json includes PreToolUse, Stop, SessionEnd, and PostToolUse entries for the Langfuse scripts.

Traces appear, but commits are not linked

1. Confirm LANGFUSE_PROJECT_ID is set in .claude/settings.local.json.
2. Verify .git/hooks/prepare-commit-msg exists and is executable.
3. Let Claude Code run at least one tool before the first commit, so langfuse_session_init_hook.py can initialize the session trace.
4. Prefer having Claude Code run the git commit itself. The Bash PostToolUse hook only fires when Claude uses the Bash tool.

A commit message is missing the Langfuse-Session trailer

The latest hook script skips trailer insertion when:

• the commit is a merge or squash commit
• there is no recent active Langfuse session state
• LANGFUSE_PROJECT_ID is missing
• the prepare-commit-msg hook is not installed or is not executable

I already have other Claude Code or git hooks

Do not delete them. Merge the Langfuse entries into ~/.claude/settings.json, and chain any existing prepare-commit-msg hook by renaming it to .git/hooks/prepare-commit-msg.pre-langfuse.

Hook sources

These are the latest hook files used by this guide:

• langfuse_utils.py
• langfuse_session_init_hook.py
• langfuse_hook.py
• langfuse_git_commit_hook.py
• langfuse_prepare_commit_msg.py

Resources

• Claude Code documentation
• Claude Code hooks guide
• Langfuse Sessions
• Langfuse Observability Overview
• Langfuse Python SDK Reference