oh-langfuse

oh-langfuse 是用于给 Claude Code、OpenCode、Codex 配置 Langfuse 追踪的命令行工具。它既提供交互式安装向导，也支持 setup、check、update、auto-update 等直接命令。

当前 npm 版本：0.1.60

能做什么

• 为 Claude Code 安装 Stop hook，把会话事件写入 Langfuse。
• 为 OpenCode 安装并 patch opencode-plugin-langfuse，开启 OpenTelemetry，并输出 OpenCode Agent Turn 指标。
• 为 Codex 安装 notify hook，增量读取 session JSONL 并写入 Langfuse。
• 记录本地 runtime 版本，支持启动前更新检查和手动更新。
• 校验员工号、环境变量、插件、hook、launcher、命令 shim 是否安装完整。

员工号必须匹配：

^[a-z](?:\d{8}|wx\d{7})$

示例：h00613222、hwx1234567。

快速使用

建议始终带 @latest：

npx oh-langfuse@latest
npx oh-langfuse@latest setup
npx oh-langfuse@latest check

指定目标：

npx oh-langfuse@latest setup claude
npx oh-langfuse@latest setup opencode
npx oh-langfuse@latest setup codex

npx oh-langfuse@latest check claude
npx oh-langfuse@latest check opencode
npx oh-langfuse@latest check codex

更新已安装运行时：

npx oh-langfuse@latest update all
npx oh-langfuse@latest update claude
npx oh-langfuse@latest update opencode
npx oh-langfuse@latest update codex

确认是否已经更新到 npm 最新版本：

npx oh-langfuse@latest verify-update all
npx oh-langfuse@latest verify-update opencode

交互式菜单

运行 npx oh-langfuse@latest 会打开菜单：

• Setup Langfuse：选择 Claude Code、OpenCode、Codex 中的一个或多个目标安装。
• Update Installed Runtimes：刷新已安装目标的 hook、plugin、launcher、命令 shim 和 runtime 版本记录。
• Check Environment：检查 Node.js、npm、Python、pip、OpenCode CLI 等基础依赖。
• Check Configuration：检查已写入的目标配置。

多选菜单默认不选中任何目标，避免误写本地配置。

自动更新

安装或更新 runtime 后，工具会在：

~/.config/oh-langfuse/runtime.json

记录 Claude Code / OpenCode / Codex 当前写入本机 runtime 的包名和版本。

verify-update 会读取这份记录，并对比 npm oh-langfuse@latest：

npx oh-langfuse@latest verify-update all

输出示例：

[OK] OpenCode Langfuse runtime is current: 0.1.60
[FAIL] Codex Langfuse runtime is outdated: installed 0.1.59, latest 0.1.60
[FIX] Run: npx oh-langfuse@latest update codex
[SKIP] Claude not installed

check 用于检查配置完整性；verify-update 才用于确认本机 runtime 是否已经更新到 npm 最新版本。

OpenCode setup 会生成直接命令 shim：

• Windows：~/.config/opencode/bin/opencode.cmd
• Linux/macOS：~/.config/opencode/bin/opencode

新开终端后直接运行 opencode，会先做轻量更新检查，再转发到真实 OpenCode CLI。为了避免在 agent 启动链路里嵌套运行完整 installer，shim 默认只提示更新命令；需要更新时关闭 agent 后运行：

npx oh-langfuse@latest update opencode

Claude Code 和 Codex 也会生成 launcher：

• ~/.claude/launch-claude-langfuse.cmd / ~/.claude/launch-claude-langfuse.sh
• ~/.codex/launch-codex-langfuse.cmd / ~/.codex/launch-codex-langfuse.sh

也可以手动触发轻量检查：

npx oh-langfuse@latest auto-update opencode
npx oh-langfuse@latest auto-update claude
npx oh-langfuse@latest auto-update codex

Skill 使用统计

当前版本把 skill 使用汇总写入每次交互的 agent-specific Agent Turn observation，不再额外生成独立 Skill Use observation。

Agent Turn 的 observation name 会带上来源，方便在 Langfuse 后台直接区分：

• Claude Agent Turn
• OpenCode Agent Turn
• Codex Agent Turn

常见字段：

metadata.skill_use_count
metadata.unique_skill_count
metadata.repeated_skill_count
metadata.skill_names
metadata.skill_names_all
metadata.skill_invocation_modes
metadata.skill_agent_paths

Repository context is also attached to each Agent Turn when the runtime can identify a current working directory. The hook performs only lightweight read-only git probes and stays silent on timeout or failure.

Common repository fields:

metadata.cwd
metadata.cwd_source
metadata.git_context_available
metadata.is_git_repo
metadata.git_remote
metadata.git_repo_slug
metadata.git_branch
metadata.git_commit

Dashboard 统计建议：

View: Observations
Filter: Observation Name contains Agent Turn
Metric: Sum skill_use_count

如果 Langfuse Dashboard 支持 metadata 维度，可用 metadata.skill_names 聚合；导出数据时可用 metadata.skill_names_all 保留重复调用顺序。

各目标写入内容

OpenCode

写入或更新：

• ~/.config/opencode/opencode.json
• ~/.config/opencode/plugins/opencode-plugin-langfuse
• ~/.config/opencode-plugin-langfuse/config.json
• ~/.config/opencode/launch-opencode-langfuse.cmd 或 .sh
• ~/.config/opencode/bin/opencode.cmd 或 opencode

Windows 下会尝试写入用户级 LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_BASEURL、LANGFUSE_USER_ID。当前终端不会立即继承用户级环境变量，新开终端或使用 launcher 即可生效。

Claude Code

写入或更新：

• ~/.claude/hooks/langfuse_hook.py
• ~/.claude/langfuse-venv
• ~/.claude/settings.json
• ~/.claude/bin/claude.cmd 或 claude
• ~/.claude/launch-claude-langfuse.cmd 或 .sh

Linux 环境缺少 python3-venv/ensurepip 时，安装器会降级尝试 python3 -m pip --user、pip3 --user、pip --user 安装 langfuse。

Codex

写入或更新：

• ~/.codex/hooks/codex_langfuse_notify.py
• ~/.codex/langfuse-venv
• ~/.codex/langfuse/config.json
• ~/.codex/config.toml 顶层 notify
• ~/.codex/bin/codex.cmd 或 codex
• ~/.codex/launch-codex-langfuse.cmd 或 .sh

配置后需要重启 Codex，让新的 notify 命令加载。notify hook 会增量读取 ~/.codex/sessions/**/*.jsonl，并把读取偏移记录到 ~/.codex/langfuse/state.json。

notify hook 会读取 ~/.codex/langfuse/config.json（或 CODEX_HOME/langfuse/config.json）中的 baseUrl / host，并把该主机补入 NO_PROXY，避免自建 Langfuse 服务被代理干扰。

环境变量

| 变量 | 作用 | | --- | --- | | LANGFUSE_BASEURL / LANGFUSE_HOST | Langfuse 服务地址 | | LANGFUSE_PUBLIC_KEY | Langfuse public key | | LANGFUSE_SECRET_KEY | Langfuse secret key | | LANGFUSE_USER_ID / CC_USER_ID | 用户标识，必须匹配员工号规则 | | CODEX_HOME | 自定义 Codex home 目录 | | OPENCODE_SKIP_PLUGIN_INSTALL | 跳过 OpenCode npm 插件安装 | | OPENCODE_NPM_REGISTRY | OpenCode 插件 npm 安装 registry | | LANGFUSE_PIP_INDEX_URL | Python langfuse 安装 index |

Secret key 不会在交互式界面中明文展示。

WSL

WSL 用户请在 WSL shell 中直接安装和检查：

npx oh-langfuse@latest setup opencode --userId=h00613222 --yes
npx oh-langfuse@latest check opencode

工具不会做 Windows 到 WSL 的转发；在 WSL 中运行时，配置写入 WSL 用户自己的 $HOME/.config/opencode。

开发与验证

npm run check
npm test
npm pack --dry-run

涉及安装、hook、CLI、OpenCode、Claude Code、Codex、Langfuse、packaging 或 verification 行为的修改，应运行真实闭环验证：

npm run self:verify -- --targets=opencode --userId=h00613222

完整覆盖可运行：

npm run self:verify -- --targets=claude,opencode,codex --userId=h00613222

发布包暴露两个命令：

• oh-langfuse
• code-tool-langfuse