Rewrite plugin from Python to TypeScript (running on Bun)

[jannikmaierhoefer]

What

Rewrites the Claude Code observability plugin from Python to a self-contained, pre-bundled TypeScript hook. The plugin now runs on Bun (>= 1.2) instead of requiring python3 and the langfuse Python SDK.

The structure and conventions mirror the sibling codex-observability-plugin: one self-contained dist/index.mjs invoked directly by the hook, deps bundled at build time, Langfuse TS SDK over OpenTelemetry.

Why

The Python version was painful to get running on macOS — it depended on a system python3 having langfuse>=4.0,<5 importable, and silently no-op'd when the SDK wasn't available. Shipping a committed bundle means zero install/build step for users; Bun runs it directly.

What changed

• src/ — hook entry (index.ts), config resolution (config.ts), transcript parsing (parse.ts), Langfuse emit (trace.ts), incremental sidecar state (state.ts), OTel setup (instrumentation.ts), helpers (utils.ts, types.ts).
• dist/index.mjs — committed self-contained bundle (bun build, single ESM file with dynamic imports inlined). All runtime deps (Langfuse SDK, OpenTelemetry, zod) bundled; only Node built-ins (which Bun provides) external. Run directly by the hooks, no install step.
• hooks/hooks.json — invokes bun "${CLAUDE_PLUGIN_ROOT}/dist/index.mjs" on Stop and SessionEnd (was python3 .../langfuse_hook.py), with a 30s timeout.
• Dedup/state — replaced the global ~/.claude/state/langfuse_state.json + file lock with an incremental byte-offset reader and a per-transcript sidecar (.jsonl.langfuse) storing {offset, turnCount}, so each turn uploads exactly once.
• Removed hooks/langfuse_hook.py.
• Merged main and ported its Python-hook features to TS (no merged functionality is dropped): the langfuse-observability plugin rename, LANGFUSE_USER_ID option, isMeta row handling (slash-command/skill injections no longer create phantom turns), skill:<name> trace tags (CC_LANGFUSE_SKILL_TAGS, default on), optional capture of injected skill instructions on the Skill tool span (CC_LANGFUSE_CAPTURE_SKILL_CONTENT, default off), and cwd/git-branch trace metadata.
• Tooling — Bun end to end: bun install (bun.lock), bun build for bundling, native bun test for the test suite, tsc --noEmit + prettier for linting. .gitignore keeps dist/, ignores *.jsonl.langfuse.
• Docs — README rewritten for the Bun/TS setup; plugin bumped to 3.0.0.

Trace structure (unchanged semantics)

One trace per turn, grouped into a Langfuse session by session id; one generation per assistant message with model + token usage (including cache read/write); nested tool observations matched tool_use → tool_result; subagent transcripts expanded inline under the spawning tool call. Original timestamps preserved on every span. Fails open — a tracing error never blocks the session.

Config

Resolved as defaults → ~/.claude/langfuse.json → <cwd>/.claude/langfuse.json → env. For each setting, the Claude Code plugin-config form (CLAUDE_PLUGIN_OPTION_<NAME>) wins, then plain LANGFUSE_*, then CC_LANGFUSE_* aliases — preserving the keys the existing userConfig in plugin.json already exposes. Optional knobs: environment, user_id, tags, metadata, max_chars, skill_tags, capture_skill_content, fail_on_error.

Testing

• bun run lint (prettier + tsc --noEmit + dist-is-current check) and bun test (24 tests) pass.
• Verified the original Node bundle end-to-end against Langfuse Cloud: a turn with a tool call produced a trace with the turn span, two generations, and the nested tool observation, with correct input/output, token usage, cost, and backdated timestamps.
• Verified the Bun runtime end-to-end against a mock Langfuse OTLP endpoint (real wire payload): same span tree, session.id/user.id/tags propagated to every span (AsyncLocalStorage context propagation works on Bun), correct usage and backdated timestamps, exactly-once sidecar dedup, and fail-open confirmed under a real network failure (exit 0 by default, exit 1 with CC_LANGFUSE_FAIL_ON_ERROR=true).
• The ported main features verified the same way: skill:<name> tag on every span of the trace, injected skill instructions only on the Skill tool span, cwd/git-branch metadata on the turn, and isMeta rows no longer splitting turns.
• bun build output confirmed byte-for-byte deterministic (keeps the lint:dist CI guard meaningful).

Reviewer notes

• dist/index.mjs is intentionally committed (large diff) — that's the artifact the hook runs. CI guard (lint:dist) rebuilds and fails if it drifts from src/. Rebuild + commit after any src/ change.
• Breaking: requires Bun >= 1.2 instead of Python; hence the major version bump. Existing installs tracking this should be re-pointed once merged (e.g. to main or a tag).
• The bundle is built with --target node, so it also runs under Node.js >= 20 unchanged — only the hook command and tooling assume Bun.
• The git-commit-message / session-init features from some users' manual Python hook setups are out of scope here — this plugin only does Stop/SessionEnd-hook tracing, matching the original langfuse_hook.py.

🤖 Generated with Claude Code