Skip to content

README.md

Latest commit

 

History

History
113 lines (86 loc) · 3.43 KB

README.md

File metadata and controls

113 lines (86 loc) · 3.43 KB
Raw

langfuse-opencode

📦 Part of the langfuse-coding-agents monorepo. Other tools: claude-code · codex · oh-my-codex · opencode · gemini-cli

English | 한국어

Automatic Langfuse tracing for OpenCode using local plugin hooks. This project forwards OpenCode event stream payloads to a Python hook and reconstructs assistant turns into Langfuse traces.

Status (February 25, 2026)

  • ✅ OpenCode + OpenRouter free-model run verified end-to-end
  • ✅ session.created / turn / session.idle traces confirmed in Langfuse
  • ✅ Turn metadata includes session_id, user_id, hostname, parts, and message-level history
  • Progress docs: English | 한국어

Features

  • Event-hook based integration (langfuse_plugin.js -> langfuse_hook.py)
  • Fail-open design (never blocks OpenCode)
  • Reliable event forwarding (sync hook invocation to reduce end-of-session event loss)
  • Runtime gate: TRACE_TO_LANGFUSE=true
  • Supports:
    • LANGFUSE_PUBLIC_KEY
    • LANGFUSE_SECRET_KEY
    • LANGFUSE_BASE_URL
    • LANGFUSE_USER_ID
    • OPENCODE_LANGFUSE_LOG_LEVEL (DEBUG|INFO|WARN|ERROR)
  • Turn reconstruction for assistant output from:
    • message.updated
    • message.part.updated
  • Lifecycle traces for:
    • session.created
    • session.idle
    • session.error
    • session.compacted
  • Metadata tags include opencode and product=reconstruction
  • Turn metadata includes session_id, user_id, hostname, and per-turn user/assistant parts
  • Turn metadata also includes per-message history from message.updated events (message_events.user, message_events.assistant)

Quick Start

git clone https://github.com/BAEM1N/langfuse-coding-agents.git
cd langfuse-coding-agents/tools/opencode
bash install.sh

Windows PowerShell:

git clone https://github.com/BAEM1N/langfuse-coding-agents.git
cd langfuse-coding-agents/tools/opencode
.\install.ps1

Manual Setup

  1. Install SDK:
python3 -m pip install --upgrade langfuse   # or `python -m pip install ...` on Windows
  1. Install plugin + hook:
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/hooks ~/.config/opencode/state/langfuse
cp langfuse_plugin.js ~/.config/opencode/plugins/langfuse_plugin.js
cp langfuse_hook.py ~/.config/opencode/hooks/langfuse_hook.py
chmod +x ~/.config/opencode/hooks/langfuse_hook.py
  1. Create ~/.config/opencode/.env:
TRACE_TO_LANGFUSE=true
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com
LANGFUSE_USER_ID=opencode-user
OPENCODE_LANGFUSE_LOG_LEVEL=INFO
OPENCODE_LANGFUSE_MAX_MESSAGE_EVENTS_PER_MESSAGE=30
  1. Merge plugin registration into ~/.config/opencode/opencode.json:
{
  "plugin": [
    "file:///Users/<you>/.config/opencode/plugins/langfuse_plugin.js"
  ]
}

Keep existing opencode.json values and append this plugin path only if missing.

Validation

python3 -m py_compile langfuse_hook.py   # or `python -m py_compile ...` on Windows
node --check langfuse_plugin.js

Files

  • langfuse_plugin.js: OpenCode local plugin (event hook)
  • langfuse_hook.py: Python trace emitter + stateful reconstruction
  • install.sh, install.ps1: interactive installers with merge-safe config update

License

MIT