Claude Tracing Guide 🚀

Claude Code hooks for Langfuse OTLP tracing — cross-platform. Captures Claude Code sessions as structured traces in Langfuse with zero configuration changes to your workflow.

---

🚀 Quick Start

• Global Install (Recommended): Run npm install -g @ciandt-flow/flow-ai-obs. The postinstall script automatically guides authentication and registers hooks.
• Authentication: Run flow-ai-obs auth login. Credentials securely share with flow-plugins-cli via the OS native keychain.
• No-Install Execution: Use npx @ciandt-flow/flow-ai-obs install to apply hooks without a global install.

---

🔧 Configuration

• Automatic Hook Injection: Installs commands into ~/.claude/settings.json automatically.
• Manual Override: Add customCommands to .claude/settings.local.json pointing to the flow-ai-obs executable.
• Hooks Used: Uses preprompt, postprompt, pretool, and posttool hooks to trace interactions.

Env Var	Purpose
FLOW_OBS_GATEWAY_URL	Overrides the default OpenTelemetry gateway endpoint.
FLOW_OBS_DEBUG	Set to 1 to append verbose debug logs to /tmp/flow-obs-debug.log.

---

📦 Dependencies

• Runtime: Requires Node.js >= 18.0.0.
• Optional: keytar is an optional dependency for OS native keychain storage (macOS Keychain, Linux Secret Service, Windows Credential Manager).

---

💡 Best Practices (Patterns)

• Targeted Tracing: The package intentionally filters out noise. Only sessions with at least one Skill or Agent call generate traces.
• Shared Keychain Auth: Leverage the OS native keychain to share credentials with other Flow CLI tools. This prevents authentication fatigue.
• Containerized Sandboxing: Use the provided Docker environment (make build && make start) for development. This prevents accidental corruption of your host’s Claude Code configuration.
• Cost & Usage Tracking: Root spans automatically calculate input/output token usage and estimated costs per prompt.

---

🚨 Gotchas / Warnings (Anti-patterns)

• Offline Trace Purging: Buffered offline traces are automatically discarded if they are older than 24 hours or exceed 50 files. Do not rely on local buffering for long-term offline work.
• Manual Settings Edits: Manually editing the customCommands array in your host’s settings.json during development can break local Claude Code. Always use the provided Docker sandbox for testing hook changes.
• PII Leakage: While the package redacts obvious secrets (AWS keys, GitHub tokens, IPs), ensure PII is scrubbed before prompts are sent.

---

🔍 Research / References

• Package Registry: npmjs.com/package/@ciandt-flow/flow-ai-obs
• Source Format: Built with TypeScript (CommonJS output via tsup). Contains an obfuscated ES-build distribution in the public registry.
• Repository: Private Git repository at CI-T-HyperX/flow-codeassistant-observability.