Trace Claude Code with Langfuse - Langfuse

Claude Code Tracing with Langfuse

Claude Code in Action: Trace Tool Calls & Decisions with Langfuse - YouTube

What is Claude Code?: Claude Code is Anthropic's agentic coding tool that lives in your terminal. It can understand your codebase, help you write and edit code, execute commands, create and run tests, and help you accomplish complex coding tasks with natural language. Claude Code brings the power of Claude's AI capabilities directly into your development workflow.

What is Langfuse?: Langfuse is an open-source AI engineering platform. It helps teams trace LLM applications, debug issues, evaluate quality, and monitor costs in production.

What Can This Integration Trace?

By using Claude Code's hooks system, this integration captures full conversation interactions and sends them to Langfuse. You can monitor:

How It Works

Claude Code provides a hooks system that allows you to run custom scripts at different lifecycle points. This integration uses the Stop hook, which runs after each Claude Code response.

  1. A global "Stop" hook is configured to run each time Claude Code responds
  2. The hook reads Claude Code's generated conversation transcripts
  3. Messages are converted into Langfuse traces and sent to your Langfuse project
  4. All turns from the same session are grouped using a shared session_id

Quick Start

Easiest path: have Claude Code set this up for you. Open a Claude Code session in any project and paste in the URL to this page along with the instruction "Implement this integration." Claude will read the page, create the hook script, and register it in your settings. You still need to add your API keys yourself (covered in the Enable Tracing Per-Project step below) — those should never be generated by an LLM. If you prefer to install everything by hand, follow the steps below.

Set up Langfuse

  1. Sign up for Langfuse Cloud or self-host Langfuse.
  2. Create a new project and copy your API keys from the project settings.

Install Dependencies

Install the Langfuse Python SDK:

pip install "langfuse>=4.0,<5"

Create the Hook Script

Create the hook script at ~/.claude/hooks/langfuse_hook.py:

mkdir -p ~/.claude/hooks

Register the Hook

Open your existing global Claude Code settings file at ~/.claude/settings.json and add a Stop hook entry:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/langfuse_hook.py"
          }
        ]
      }
    ]
  }
}

Enable Tracing Per-Project

Add your Langfuse credentials to Claude Code's per-project settings file at .claude/settings.json in the project root. Make sure this file is listed in your project's .gitignore so your secret keys aren't committed. Add an env block:

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

Environment Variables:

Variable Description Required
TRACE_TO_LANGFUSE Set to "true" to enable tracing Yes
LANGFUSE_PUBLIC_KEY Your Langfuse public key Yes
LANGFUSE_SECRET_KEY Your Langfuse secret key Yes
LANGFUSE_BASE_URL Langfuse base URL. EU: https://cloud.langfuse.com, US: https://us.cloud.langfuse.com, Japan: https://jp.cloud.langfuse.com, HIPAA: https://hipaa.cloud.langfuse.com No (defaults to EU)

Start Using Claude Code

Now when you use Claude Code in a project with tracing enabled, conversations will be sent to Langfuse:

cd your-project
claude

View Traces in Langfuse

Open your Langfuse project to see the captured traces. The structure mirrors how Claude Code actually works: