Langfuse Tracing.
Wire two hooks and every Claude Code session writes to Langfuse Cloud automatically. Every prompt, every tool call, every dollar spent, every overnight run. The fleet stops being a black box and starts being a system you actually operate. This is the foundation every later observability move needs.
- Every session, visible after the fact open one dashboard and see what each agent did last night, what it cost, which tool calls were slow, where anything broke.
- Tags that filter the fleet by computer, by agent source (you at the keyboard versus a scheduled job), by client project. Multi-machine fleets stop being a blur.
- A free starting tier Hobby covers an individual fleet for the first weeks. Core at $29/mo covers serious 8D work. Pick the right one at sign-up.
Wire your first trace.
Hand the build off to Claude in one paste. The agent walks you through Cloud sign-up, both hooks, redaction, and tagging in one flow. You approve every step.
How this fits in the OS.
Claude Code installed and running. A Langfuse Cloud account (free to sign up, no card needed for the Hobby tier). A password manager (1Password or Infisical) so the API keys never live in plain text on disk.
Two Claude Code hooks (Stop and PostToolUse), the Langfuse Python SDK, and a redaction helper that scrubs known secret patterns before any payload leaves your computer.
Every session visible after the fact. Cost per model per day. Slowest tool calls surfaced. Error-rate alerts. The first real observability primitive your fleet needs once agents start running while you sleep.
Why this is the foundation.
Once your fleet runs more than one agent and more than one schedule, the question "what happened last night?" stops having an obvious answer. The Slack ping says the morning brief delivered. But what did the brief actually cost? Which sources took the longest? Did the heartbeat agent quietly fail at 3am? Were tool calls retried? Did any agent get a 429 and silently skip work?
Langfuse is the record. Every Claude Code session, every tool call, every model invocation, every dollar spent writes to one database, queryable in one dashboard. The fleet stops being a black box.
Tyler runs a two-database write-back pattern: every action in the fleet writes to a Kanban board (task-level, who-is-working-on-what right now) AND to Langfuse (every call, every cost, every decision, ever made). The Kanban tells you what is happening right now. Langfuse tells you what happened last night, what it cost, and why it took the path it did. Observability is to your fleet what a Cairn is to your knowledge base: a durable, queryable record. You do not read it daily. You read it when you need an answer.
The agent does this for you. Once the two hooks are wired, you never call the tracer by hand. Every session your agents run writes itself to the dashboard automatically. The dashboard is the artifact; the discipline is just keeping the hooks alive.
What you will build.
Two small Python scripts living in ~/.claude/hooks/, registered in ~/.claude/settings.json, fired automatically by Claude Code at two lifecycle events. They open a connection to Langfuse Cloud, scrub secrets, and post every turn and every tool call as structured trace data.
Once it is wired, the loop is:
You run a short test session at the end, watch the trace appear, then know the system is real before you trust it with overnight work.
The Cloud plans you will see at sign-up.
Langfuse Cloud has four tiers. The free Hobby tier is generous on features and constrained on volume. Most students start here. The realistic landing for serious 8D fleet work is Core at $29 a month.
| Plan | Price | Volume | Retention | What you get |
|---|---|---|---|---|
| Hobby | Free, no card | 50k units / month | 30 days | 2 users, all platform features, 1 annotation queue, community support |
| Core | $29 / mo | 100k units / month | 90 days | Unlimited users, in-app support, 48h response SLO, 3 annotation queues. Overage runs $8 per additional 100k units. |
| Pro | $199 / mo | 100k units / month | 3 years | 20k requests / min, SOC2, ISO27001, HIPAA BAA, unlimited annotation queues |
| Enterprise | $2,499 / mo | 100k units / month | 3 years | Audit logs, SCIM, custom limits, dedicated engineer, SLAs |
A "unit" is a trace OR an observation OR a score. It is not a user request. A single Claude Code session with five tool calls and three model invocations emits nine or more units (one trace, plus each tool call, plus each model call). Sizing by request count understates real consumption ten-fold. Expect the Hobby tier to handle thousands of light sessions per month. Expect serious 8D fleet work (multiple cron jobs, heartbeats every five minutes) to exhaust Hobby within weeks and land you on Core.
Recommended path: sign up for Hobby. Wire the hooks. Run for a week. If Hobby starts pinching, upgrade to Core. You can upgrade later without losing data. The free tier is the right starting place for almost every student.
One sign-up decision worth thirty seconds of thought: region. Cloud has US, EU, Japan, and HIPAA regions. You cannot easily move regions later. Pick the region closest to where your agents will run. North America defaults to US (https://us.cloud.langfuse.com).
What changes for you.
The dashboard is the easy part. The bigger thing is the shift in how you operate the fleet. Three shifts you will feel:
- You stop trusting the agent's self-report. Asking "what did you do last night?" is fine for chat. For ops, you read the traces. The traces are the record.
- You start filtering by tag instead of scrolling. "Show me everything the mention listener did on the Mac Mini in the last 24 hours" becomes a two-click filter, not a log dive.
- You watch the cost dashboard weekly. One model dominating, one bad day, one script silently defaulting to Opus on tiny tasks. All of it surfaces in one place instead of biting you on the invoice.
This is the moment your fleet stops being a black box and starts being a system you actually run.
Before you start.
Three prereqs. Skip any and the build stalls.
- Claude Code installed and working on the computer where you plan to trace. Run a session by hand first and confirm hooks fire (any existing hook is a fine smoke test).
- A Langfuse Cloud account. Free sign-up at
cloud.langfuse.com/auth/sign-up. Pick the region closest to where your agents run. - A password manager you actually use. 1Password or Infisical, either works. The Langfuse keys go there, not into a config file you might commit to git.
When tracing is on, your prompts and assistant responses leave your machine and land in Langfuse Cloud. The redaction helper scrubs known secret patterns (Anthropic, OpenAI, Slack, GitHub PATs, JWTs, 1Password references, Langfuse keys themselves) before sending. It is defense in depth, not a guarantee. If your work touches sensitive client material, factor that into your region choice and your retention plan.
The build.
Six steps. The starter prompt above walks Claude through all of them with confirmation gates between each one. What follows is the human-readable version so you know what good looks like.
Create the project, generate the keys
~5 minSign in at cloud.langfuse.com, create an organization (your handle), then a project inside it (your fleet name, e.g. personal-agents). Go to Settings → API Keys → Create new API keys. You get three values: a public key (pk-lf-...), a secret key (sk-lf-...), and a host URL.
The secret key is shown once. If you lose it, you rotate. Do not paste it into chat.
I created a Langfuse Cloud project named <name>. I have the public key, secret key, and host URL ready in my password manager. Do not ask me to paste them. Tell me which three field names you need stored, where to put them, and what to call them. I will add them to 1Password (or Infisical) myself using the placeholder pattern. If you offer to enter the real values for me, say no. I always type real values directly into my password manager.
PASTE_HERE placeholder pattern, type the value into your password manager yourself, then point the script at the password manager's reference (op://... for 1Password). If Claude offers to handle the real value for you, say no.
Wire the environment variables
~5 minFive variables. Three secrets (public key, secret key, host) plus two tags (machine hostname, agent source) that let you filter the dashboard later.
LANGFUSE_PUBLIC_KEYandLANGFUSE_SECRET_KEYresolve from your password manager.op://references on Mac and Linux, the equivalent on Windows.LANGFUSE_HOSTpoints athttps://us.cloud.langfuse.comfor the US region, or your chosen region's host.LANGFUSE_MACHINEdefaults to your hostname. Useful when filtering "what did each computer do today."LANGFUSE_AGENT_SOURCEisinteractivefor a human-at-the-keyboard session. Override tomention-listener,responder, orcron-jobfor autonomous agents (set in their launchd plist or systemd unit, not globally).TRACE_TO_LANGFUSEis the opt-in switch. Do not set it globally. Set it per-shell when you want tracing on, or in the plist for agents that should always trace.
The agent does the wiring for you. You confirm the variable names load correctly with echo $LANGFUSE_PUBLIC_KEY.
Drop in the two hook scripts
~15 minTwo files at absolute paths. Hooks run from a working directory you do not control, so relative paths break.
- Stop hook (
~/.claude/hooks/langfuse_trace.py). Fires at the end of every assistant turn. Walks the Claude Code session JSONL, finds turns since the last run, posts each one to Langfuse via the Python SDK. A production version also handles an offline queue at~/.claude/state/pending_traces.jsonlthat drains when Langfuse is reachable again. - PostToolUse hook (
~/.claude/hooks/langfuse_tool_hook.py). Fires after every tool call. Posts that one call as a span via raw HTTP (no SDK import, keeps execution under 100ms so long sessions do not drag).
Both share an opt-in check (exit silently unless TRACE_TO_LANGFUSE=true), an environment-variable loader, and the redaction helper. Both always exit 0. A failing tracer must never block Claude Code.
The agent writes the scripts for you using the canonical patterns in guides/observability/03-claude-code-integration.md. You read the diff, approve it, save. Do not hand-type the regex list. The redaction helper covers Anthropic, OpenAI, Slack, GitHub PATs, Langfuse's own keys, JWTs, and 1Password references out of the box.
~/.claude/state/langfuse_hook.log and find the traceback. Add a try / except around the offender and make sure every exit path is sys.exit(0). Observability that breaks the agent is worse than no observability at all.
Register the hooks in settings.json
~5 minEdit ~/.claude/settings.json and add a hooks block with two entries, Stop and PostToolUse, each matching *, each pointing at the absolute path of its script.
The agent does this for you and shows you the diff. You confirm the paths are correct on your machine (Mac users will see /Users/yourname/..., Windows-with-Git-Bash users will see /c/Users/yourname/... mapped from C:\Users\yourname\...) before saving.
Run a test session
~10 minTurn tracing on for one shell. Have a short conversation that hits at least one tool. Confirm the trace lands before you trust the system with anything bigger.
export TRACE_TO_LANGFUSE=true && cd ~/some-project && claude
Inside the session, ask Claude to read a file, run a command, and write something small. Exit. Open the Langfuse dashboard. Navigate to Tracing → Sessions. You should see one new session, each turn as its own trace, each tool call as a nested span with input and output, and tags including your hostname plus interactive.
If you see all of that, the build works. Move on.
Verify redaction
~5 minRun one more session, this time deliberately reading a file that contains an API-key-shaped string (your .env.example with a fake sk-ant-test123456789 is fine). Check the trace in the dashboard.
The value should appear masked as something like sk-a***6789. Each match keeps the first four and last four characters on purpose, so you can debug "did I leak the right kind of token?" without exposing the value.
If the value appears in plain text, the regex did not catch it. Add a pattern, restart your shell, retest. If Claude offers to bypass redaction "just for testing," say no. The whole point of this step is that redaction is on every single trace, every single time.
TRACE_TO_LANGFUSE=true now lands in the dashboard with full prompts, responses, tool calls, costs, durations, and tags. The fleet just became observable.
When it works.
You will know the build is real when all of these are true:
- A trace appears within seconds of an assistant turn ending. Refresh the Sessions view. If it is not there, the hook did not fire.
- Every tool call is its own span with input and output captured. Bash commands, Read calls, Edit diffs, WebFetch pulls, your custom CLIs. All of it.
- Tags filter cleanly. Pick "Tags contains
<hostname>" and only your computer's sessions show up. Pickinteractiveand only your at-the-keyboard work shows. - Cost appears on every generation. The model name, token counts in and out, dollar amount. If cost is missing, the SDK probably did not get the model identifier through.
- The hook logs are quiet.
tail ~/.claude/state/langfuse_hook.logshows successful posts, no tracebacks. Errors here are silent in the agent and loud in the log on purpose.
If you get stuck.
Common failure modes, ranked by how often they bite people:
- Set
TRACE_TO_LANGFUSE=truein the wrong shell. Most common. The opt-in is per-shell on purpose. Runecho $TRACE_TO_LANGFUSEin the shell that ran Claude Code. If it prints nothing, the export did not happen there. - Traces appear but tool calls are missing. The
PostToolUsehook is not registered. Re-check~/.claude/settings.json, restart Claude Code, retest. - Hook log shows "Langfuse unavailable." Network is blocking the host, or the URL is wrong. Try
curl $LANGFUSE_HOSTfrom the same shell. - Login works but traces get 401. Stale or wrong API keys. Rotate the keys in Langfuse, update the password-manager entry, restart the shell.
- You hit your Hobby tier ceiling earlier than expected. Check the unit gotcha aside above. A multi-agent fleet emits 10 or more units per request. Upgrade to Core ($29 / mo, 100k units) without losing data; you keep your traces, your tags, your dashboard.
- The pending-traces queue keeps growing. Your hooks cannot reach Langfuse. Fix the connection, do not let the queue swell. A bloated queue means data sits on the source computer instead of in the dashboard.
- Pasted a real key into chat by accident. Rotate the key in Langfuse immediately. Then redo the credential step using the password-manager reference. If Claude offers to enter the real key for you next time, say no. Real values always go directly into your password manager.
Still stuck? Post the prompt, the hook log excerpt, and what you expected, in the workshop Slack. Someone in the cohort is solving the same thing.
Where to go next.
Traces are flowing. The pattern compounds from here. The natural next moves: