code-tool-langfuse

Polished interactive terminal UI for configuring Langfuse tracing for Claude Code, OpenCode, and Codex.

Usage

Run locally from this project:

node bin/cli.js

After publishing to npm:

npx code-tool-langfuse

Commands

code-tool-langfuse
code-tool-langfuse setup
code-tool-langfuse setup claude
code-tool-langfuse setup opencode
code-tool-langfuse setup codex
code-tool-langfuse check
code-tool-langfuse check environment
code-tool-langfuse check claude
code-tool-langfuse check opencode
code-tool-langfuse check codex

The interactive UI supports arrow-key navigation in terminals that support raw input. Use Up / Down to move, number keys for quick selection, Enter to select, and q or Esc to exit. In multi-select setup screens, use Space to toggle targets and Enter to continue. It uses a soft color palette and falls back to plain numeric prompts when raw terminal input is unavailable.

Setup Langfuse supports selecting one or more setup targets:

• Claude Code Langfuse
• OpenCode Langfuse
• Codex Langfuse

During setup, the only required input is User ID, which should be your employee number, for example h00613222. Other setup values use the built-in defaults.

Before setup, the CLI checks required local tools and prints install hints when something is missing:

• Node.js / npm
• Python / pip for Claude Code setup
• Python / pip for Codex setup
• OpenCode CLI for OpenCode setup

Python package installation uses pip's default package index by default. If you need a custom PyPI mirror, set CODE_TOOL_PIP_INDEX_URL or pass --pipIndexUrl=....

Use dry-run mode to preview the script calls without modifying files, installing packages, or writing environment variables:

code-tool-langfuse setup --dry-run

What It Configures

For Claude Code Langfuse setup, the CLI installs langfuse_hook.py, creates ~/.claude/langfuse-venv, installs langfuse into that virtual environment, updates ~/.claude/settings.json, and configures the hook environment. On Ubuntu/Debian, install python3-venv first if the setup reports that venv support is missing.

For OpenCode Langfuse setup, the CLI installs and patches opencode-plugin-langfuse, updates ~/.config/opencode/opencode.json, and can write LANGFUSE_* values to the user environment.

For Codex Langfuse setup, the CLI installs codex_langfuse_notify.py, creates ~/.codex/langfuse-venv, installs langfuse into that virtual environment, writes Langfuse credentials to ~/.codex/langfuse/config.json, and updates the top-level notify command in ~/.codex/config.toml. Restart Codex after setup so the notify command is loaded.

The Codex integration is implemented as a notify-hook exporter. On each notify event it incrementally reads the matching ~/.codex/sessions/**/*.jsonl file, converts new user/assistant/tool/token events into Langfuse observations, and then saves its offset in ~/.codex/langfuse/state.json. If Codex does not provide a session path in the notify payload, the exporter falls back to the latest session JSONL file.

Notes

• Langfuse Base URL, Public Key, and Secret Key have built-in defaults for this internal setup. You can override them with LANGFUSE_BASEURL, LANGFUSE_PUBLIC_KEY, and LANGFUSE_SECRET_KEY.
• The default secret key is not printed in the terminal UI.
• The CLI calls the Node setup/check scripts directly, so it avoids PowerShell npm.ps1 execution-policy failures.
• The Python hook reads userId from hook payload first, then from configured environment variables.
• The Codex hook fails open: tracing errors are logged to ~/.codex/langfuse/codex_langfuse_notify.log and do not block Codex.