langfuse-local

name	langfuse-local
description	Local self-hosted Langfuse v3 at http://localhost:3000 — operate the stack, log in, query traces/sessions via API, and mine the data for DORA + Kanban + AI-engineering metrics. Use this skill whenever the user mentions Langfuse, asks to open it, asks about traces or sessions for Claude Code activity, asks 'tá pesando quanto', 'quantos traces hoje', 'qual ferramenta tá mais lenta', wants DORA or Kanban metrics derived from coding sessions, wants to benchmark or A/B compare runs, wants to detect tool/session anomalies, or asks 'como vejo X' about agent observability.
tools	["Bash","Read","Write","Edit","WebFetch","mcp__plugin_playwright_playwright__browser_navigate","mcp__plugin_playwright_playwright__browser_click","mcp__plugin_playwright_playwright__browser_fill","mcp__plugin_playwright_playwright__browser_take_screenshot","mcp__plugin_playwright_playwright__browser_snapshot"]

Local Langfuse — operate, query, mine

Two integration surfaces feed data into this Langfuse instance:

1. Stop hook (~/.claude/hooks/langfuse_hook.py) — ingests every Claude Code transcript turn-end and emits backdated Claude Code - Turn N traces with nested Generations + Tools.
2. docker compose stack — postgres + clickhouse + redis + minio + langfuse-web + langfuse-worker, defined in assets/docker-compose.langfuse.yml.template.

The skill operates both surfaces and mines the resulting data.

Quick state check

bash scripts/status.sh         # container health + most-recent trace timestamp + hook log mtime
bash scripts/tail-hook-log.sh  # tail -F the Stop-hook log (one-liner)

Workflows

User says	Run
"open langfuse" / "abre langfuse"	bash scripts/open-ui.sh — opens Chrome and auto-logs in via Playwright if MCP is loaded; otherwise opens and prints creds to stdout
"subir langfuse" / "bring up"	bash scripts/up.sh — docker compose up -d then polls /api/public/health until 200
"down langfuse"	bash scripts/down.sh — data persists in named volumes
"ver traces da sessão X"	bash scripts/traces.sh <session-id> [limit]
"métricas DORA" / "DORA metrics"	python3 scripts/metrics.py dora --since 7d
"kanban flow"	python3 scripts/metrics.py kanban --since 24h
"qual ferramenta tá mais lenta"	python3 scripts/metrics.py tool-latency --window 60min
"deviation hoje vs ontem"	python3 scripts/metrics.py anomaly --window 24h --baseline 7d
"quanto custou essa semana"	python3 scripts/metrics.py cost --since 7d --group-by day
"benchmark sessão X vs Y"	python3 scripts/bench.py <eval-set.json>
"rerun stop hook na sessão X"	bash scripts/replay-session.sh <sid> <transcript-path>
"perdi a senha" / "mostra as creds"	Read references/creds.md and print to chat — only when user explicitly asks

Credentials

Stored in references/creds.md (file mode 600, gitignored). Login: [e-mail] (or any address you chose during setup).

Why envless first: credentials must never appear in shell history or chat transcripts unless the user explicitly asks. Scripts resolve creds in this order:

1. envless list — if LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY are present, source them.
2. Fall back to parsing references/creds.md via the shared helper scripts/_creds.sh.

Never hard-code credentials in script bodies. Never echo them to stdout in non-interactive paths.

Environment variables (override defaults)

Variable	Default	Purpose
LF_COMPOSE	~/.claude-pessoal/skills/langfuse-local/assets/docker-compose.langfuse.yml	path to compose file
LF_BASE_URL	http://localhost:3000	Langfuse base URL
LF_DATA_DIR	~/.langfuse-data	host path for named volumes

Scripts — one-line purpose per file

Script	Purpose
scripts/up.sh	Bring the compose stack up; wait for /api/public/health = 200
scripts/down.sh	Bring the compose stack down; named volumes survive
scripts/status.sh	One-screen dashboard: container health + last trace timestamp + hook log mtime
scripts/open-ui.sh	Open Chrome at the sign-in URL; auto-fill creds via Playwright MCP if available
scripts/tail-hook-log.sh	Tail the Stop-hook log at ~/.claude/state/langfuse_hook.log
scripts/traces.sh	Curl wrapper: list traces for a session-id, pretty-print via python -m json.tool
scripts/replay-session.sh	Re-ingest a session: reset state entry + re-run the Python hook with a fake Stop payload
scripts/metrics.py	Subcommands: dora, kanban, tool-latency, anomaly, cost, sessions-summary
scripts/bench.py	A/B benchmark: run a prompt with/without a skill, tag runs in Langfuse, compute delta
scripts/creds.sh	Print export LANGFUSE_PUBLIC_KEY=... lines for shell sourcing; warns if interactive without --i-know
scripts/_creds.sh	Internal helper: resolve creds from envless or references/creds.md; sourced by other scripts
scripts/_check-symlink.sh	Abort if ~/.claude-mukutu/skills/langfuse-local is not a symlink to the canonical; run in CI

References — when to read which file

File	Read when
references/architecture.md	Need to understand how the Stop hook + fan-out integration flows data into Langfuse (ASCII diagram + ADR citations)
references/api.md	Need Langfuse public API surface: auth, trace/session/observation/score endpoints, params, curl + Python examples
references/dora.md	Need DORA metric definitions mapped to Langfuse queries (Deployment Frequency, Lead Time, CFR, MTTR)
references/kanban.md	Need Kanban / flow metric definitions (WIP, cycle time, throughput, flow efficiency, block time)
references/metrics-bench.md	Need AI-engineering metrics (token velocity, cache hit ratio, retry rate, subagent fan-out, cost/session) or A/B benchmark patterns
references/creds.md	Need credentials for the local instance — read only when user explicitly asks, file mode 600
references/troubleshooting.md	Stack unhealthy, OrbStack not running, Python 3.14 ABI break, port 3000 collision, hook log empty, ClickHouse high CPU
references/install.md	Fresh-machine install: docker, envless, symlink steps, cross-profile layout
references/notebooklm-sources.md	Canonical NotebookLM sources for DORA + Kanban deep dives; create notebook lazily on first metrics.py --explain dora

Assets — templates used on install

Asset	Purpose
assets/docker-compose.langfuse.yml.template	Vendored compose snapshot; up.sh copies to $LF_DATA_DIR if missing
assets/langfuse_hook.py.template	Canonical copy of the official Stop hook; install.sh syncs to ~/.claude/hooks/
assets/metrics-report.md.template	Markdown report skeleton used by metrics.py --as-report
assets/eval-prompts.json	10 realistic CC prompts (5 trigger / 5 not-trigger) for skill-creator description optimization

Cross-profile install

Canonical location: ~/.claude-pessoal/skills/langfuse-local/

The ~/.claude-mukutu/ profile symlinks to the canonical so edits propagate automatically:

mkdir -p ~/.claude-mukutu/skills
ln -s ~/.claude-pessoal/skills/langfuse-local ~/.claude-mukutu/skills/langfuse-local

Run bash scripts/_check-symlink.sh to verify the symlink is intact. See references/install.md for full setup steps.

Why this exists

Langfuse is the only telemetry surface available for Claude Code activity. Every tool call, token count, and session boundary is already captured here — mining it compounds leverage over time.