/langfuse

name: langfuse
description: "Use Langfuse for LLM observability and evaluation and look up Langfuse documentation. In HybridClaw, data access (traces, observations, sessions, scores, prompts, datasets, metrics) goes through the gateway-proxied langfuse.cjs helper with SecretRef auth — reads are green, writes are grant-gated. Documentation retrieval uses langfuse.com llms.txt, markdown pages, and search-docs. Covers instrumentation, prompt migration, error analysis, and LLM-as-a-judge calibration."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: langfuse-basic-auth
    kind: header
    required: true
    secret_ref:
      source: store
      id: LANGFUSE_BASIC_AUTH
    scope: "Langfuse public API Authorization Basic header secret for <LANGFUSE_HOST>/api/public"
    how_to_obtain: |
      In Langfuse, open Project Settings → API Keys and create a key pair
      (public key `pk-lf-...` and secret key `sk-lf-...`). Locally base64-encode
      `public-key:secret-key`. Set only that encoded credential as
      `LANGFUSE_BASIC_AUTH` through browser admin at
      `/admin/secrets`; if browser admin is unavailable,
      use `/secret set LANGFUSE_BASIC_AUTH "<base64-public-colon-secret>"` in
      browser `/chat` or TUI; local console fallback:
      `hybridclaw secret set LANGFUSE_BASIC_AUTH "<base64-public-colon-secret>"`.
      The same key reads observability data and writes scores, comments,
      datasets, and prompt versions.
config_variables:
  - id: langfuse-host
    env: LANGFUSE_HOST
    required: true
    scope: "Langfuse API base URL used in <LANGFUSE_HOST>/api/public"
    how_to_obtain: |
      Use your Langfuse deployment base URL: `https://cloud.langfuse.com` (EU),
      `https://us.cloud.langfuse.com` (US), `https://jp.cloud.langfuse.com` (JP),
      or your self-hosted origin. Store it in chat with
      `/env set LANGFUSE_HOST https://cloud.langfuse.com`.
metadata:
  hybridclaw:
    category: observability
    short_description: "Langfuse LLM observability: traces, scores, prompts, datasets, metrics, docs lookup, and guarded evaluation writes."
    tags:
      - langfuse
      - observability
      - llm
      - evaluation
      - tracing
      - prompts
    stakes_tiers:
      green:
        - health
        - get-project
        - list-traces
        - get-trace
        - list-observations
        - get-observation
        - list-sessions
        - get-session
        - list-scores
        - get-score
        - list-score-configs
        - get-score-config
        - list-prompts
        - get-prompt
        - list-datasets
        - get-dataset
        - list-dataset-items
        - get-dataset-item
        - list-dataset-runs
        - get-dataset-run
        - list-models
        - get-model
        - list-comments
        - get-comment
        - metrics
      amber:
        - create-score
        - create-comment
        - create-dataset
        - create-dataset-item
        - create-prompt
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: langfuse

Langfuse

This skill helps you use Langfuse effectively across all common workflows: instrumenting applications, migrating prompts, debugging traces, accessing data, and evaluating outputs.

> **HybridClaw integration.** This is the official Langfuse skill > ([github.com/langfuse/skills](https://github.com/langfuse/skills), MIT) > adapted for HybridClaw. Two things differ from the upstream skill: > > 1. **Credentials never leave the gateway.** Do not export > `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY`, run `npx langfuse-cli`, or > paste keys anywhere. Store them once in the runtime stores (below); the > gateway injects them server-side. > 2. **Data access goes through `langfuse.cjs`**, not the Langfuse CLI. The > helper builds each REST request and sends it through the HybridClaw gateway, > which resolves `Authorization: Basic <secret:LANGFUSE_BASIC_AUTH>` and the > `<env:LANGFUSE_HOST>` base URL. Wherever a reference says to run > `langfuse-cli` or `curl -H "Authorization: Basic $AUTH"`, use the helper > instead. Documentation retrieval (section 2) is unchanged.

HybridClaw setup

The helper never sees credentials. Store two values once. For secrets, use this order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets`. 2. Browser `/chat` or TUI fallback. 3. Local console fallback.

1. `LANGFUSE_BASIC_AUTH` — base64 of `public-key:secret-key`: `/secret set LANGFUSE_BASIC_AUTH "<base64-public-colon-secret>"` 2. `LANGFUSE_HOST` — your Langfuse base URL: `/env set LANGFUSE_HOST https://cloud.langfuse.com` (use `https://us.cloud.langfuse.com` for US, `https://jp.cloud.langfuse.com` for JP, or your self-hosted origin).

Local console fallback: `hybridclaw secret set LANGFUSE_BASIC_AUTH "<...>"` and `hybridclaw env set LANGFUSE_HOST https://cloud.langfuse.com`.

See [references/operator-setup.md](references/operator-setup.md) for key scope, host selection, autonomy defaults, and network-policy notes.

Core Principles

Follow these principles for ALL Langfuse work:

1. **Documentation first**: never implement from memory. Langfuse updates frequently — fetch current docs (section 2) before writing instrumentation or SDK code. 2. **Helper for data access**: use `langfuse.cjs` (gateway + SecretRef) when querying or modifying Langfuse data. It owns endpoints, methods, bodies, stakes tiers, host, and the Basic auth placeholder. 3. **Best practices by use case**: check the relevant reference below before implementing. 4. **Use latest Langfuse versions**: unless the user says otherwise, target the latest Langfuse SDKs/APIs.

Use-case references

• instrumenting an existing function/application:

[references/instrumentation.md](references/instrumentation.md)

• migrating prompts from a codebase into Langfuse:

[references/prompt-migratio