| 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:
- 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.
- 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
bash scripts/tail-hook-log.sh
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: admin@local.test (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:
envless list — if LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY are present, source them.- 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.
