Claude Langfuse Monitor

Core Insight: A zero-setup Node.js daemon that tails ~/.claude/projects/**/*.jsonl using chokidar to automatically push local Claude Code CLI activity to self-hosted Langfuse instances without manual instrumentation.

🚀 Quick Start

• Install: npm install -g claude-langfuse-monitor
• Setup Auth: claude-langfuse config --host <URL> --public-key <PK> --secret-key <SK>
• Run Daemon: claude-langfuse start --daemon (Auto-installs via macOS LaunchAgent).

🔧 Configuration

• Config Location: Reads from ~/.claude-langfuse/config.json automatically.
• Env Fallback: Maps LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, and LANGFUSE_SECRET_KEY if JSON config is missing.
• History Flag: --history <hours> dictates how much past .jsonl data gets backfilled upon startup (default: 24h).

💡 Best Practices (Observed Architecture)

• Write-Stability Guard: Wraps chokidar.watch with awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 100 }. Prevents race conditions that parse half-written JSON lines during active Claude Code streams.
• Idempotent Message Ingestion: Employs an in-memory Set() of processed uuids. Re-running the monitor over history guarantees Langfuse traces aren’t double-counted.
• Compound Content Parsing: Iterates through Claude’s message.content array dynamically. Serializes tool_use blocks to readable [Tool: <name>] strings and handles tool_result to maintain deep trace legibility.
• Session Hashing: Generates deterministic Langfuse sessionIds via MD5(projectPath:conversationId). Ensures disconnected daemon restarts resume the identical logical session without fragmentation.
• Graceful Termination: Binds process.on('SIGINT') to trigger watcher.close() and langfuse.shutdownAsync(). Ensures buffered API traces land in Langfuse before process exit.

🚨 Anti-Patterns & Gotchas

• Hardcoded Identity/Model: Traces force userId: 'michael@oboyle.co' and model: 'claude-sonnet-4-5-20250929' unconditionally. Requires manual patching for multi-tenant teams or alternative Claude models.
• Blocking File I/O: Uses synchronous filesystem operations (fs.readdirSync, fs.readFileSync) during the startup backfill tree traversal. Risks blocking the Node.js event loop on massive ~/.claude/ directories.
• Silent Catch Blocks: Catching JSON parsing errors during file streaming without error logging (catch (e) { }). Obfuscates structural changes in Anthropic’s log format.
• Periodic Flush Lag: Explicitly batches traces via if (this.processedMessages.size % 10 === 0) { this.langfuse.flushAsync(); }. Activity spikes of <10 messages may remain unflushed until SIGINT or further activity.

📦 Dependencies

• langfuse (v3.26+): Core telemetry client.
• chokidar (v3.5+): Efficient persistent file watching.
• commander (v11+): CLI parsing.

🔍 Research / References

• Source: npm/claude-langfuse-monitor
• Target Directory: ~/.claude/projects/