Pi Langfuse Documentation

Core: Official Langfuse observability extension for the Pi Coding Agent. Maps each user prompt to a single, complete trace combining prompt workflow, LLM generation, tool usage, metrics, and health scores grouped by Pi session.

🚀 Quick Start

• Install: npm install pi-langfuse (Requires Node.js >= 22).
• Load: Start Pi with pi --ext pi-langfuse.
• Setup: Run /langfuse-setup in the Pi CLI/TUI to configure keys interactively.

🔧 Configuration

• Local Config: Interactive setup persists API keys to ~/.pi/agent/pi-langfuse/config.json. This saved config always takes precedence over environment variables.
• Environment Variables: Use PI_LANGFUSE_PUBLIC_KEY, PI_LANGFUSE_SECRET_KEY, and PI_LANGFUSE_HOST when the config.json is missing.
• Privacy Presets: Set PI_LANGFUSE_PRIVACY_PRESET to metadata-only, prompts-only, conversations, or full-debug (default) to control payload granularity.
• Fine-Grained Capture: Override presets with binary flags like PI_LANGFUSE_CAPTURE_TOOL_IO=false or PI_LANGFUSE_CAPTURE_SYSTEM_PROMPT=false.
• Git Identity: Customize trace git tags via a whitelist in .pi-langfuse.metadata.json (keys: repo_identity, repo_name, remote_origin).

📦 Dependencies

• Core SDKs: @langfuse/client, @langfuse/tracing, @langfuse/otel (v5.3+).
• OpenTelemetry: @opentelemetry/sdk-node, @opentelemetry/sdk-trace-base.
• Peer Target: @earendil-works/pi-coding-agent (intercepting Pi’s plugin ExtensionAPI).

💡 Best Practices & Patterns

• Session Isolation (AsyncLocalStorage): Uses Node’s AsyncLocalStorage to scope currentSessionId and prevent active observations, state, and metrics from leaking across overlapping Pi sessions.
• 1:1 Trace Modeling: Maps exactly one user prompt to one pi-agent trace. Sub-events rigorously map to specific Langfuse entities (1 provider request = 1 generation, 1 tool call = 1 tool).
• Event-Driven Architecture: Binds directly to Pi’s lifecycle events (turn_start, before_provider_request, tool_call, agent_end). Execution loops strictly through withSession wrappers to maintain atomic context.
• Automatic Redaction: Extension universally masks tokens, API keys (e.g., AWS, GitHub, NPM), passwords, cookies, and local absolute directory paths before uploading anything to Langfuse.
• Safe Metadata Uploads: Extracts local Git context (commit hash, branch, repo name) but explicitly ignores unrecognized overrides to avoid exfiltrating sensitive credentialed remotes.

🚨 Gotchas / Anti-patterns

• Overriding via Env: Relying on environment variables will fail if a persistent ~/.pi/agent/pi-langfuse/config.json exists. The JSON config always wins.
• Global Mutable Tracing: Using standard global variables for trace IDs creates severe collision leaks during multi-session Pi tasks. Always use the withSession AsyncLocalStorage boundary.
• Orphaned Observations: Failing to close spans on session_shutdown or hard interrupts leaves dangling spans in Langfuse. Always intercept exit signals and invoke closeDanglingObservations() and shutdownRuntime().
• Unsafe Tool Payloads: Do not bypass the applyCapturePolicy redaction layer. Raw local paths and internal tokens must never be sent in observation metadata.
• Multiple Package Managers: Repo exclusively uses npm (package-lock.json). Do not commit yarn.lock or pnpm-lock.yaml.

🔍 Research / References

• NPM: pi-langfuse
• Repository: github.com/gooyoung/pi-langfuse
• Upstream Architecture: Documents local setup in DEVELOPMENT.md detailing the agent trace tree and event flow integration.