You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
OpenCode plugin: log to file instead of console.error so agents can self-diagnose #190
The OpenCode plugin's WMUX_PLUGIN_DEBUG=1 mode logs to console.error, which writes to stdout/stderr inside the OpenCode process. This output is not visible to the user or the agent:
OpenCode is a TUI that owns the terminal — console.error output is swallowed or interleaved with the UI.
The agent running inside OpenCode cannot read its own process's stderr.
The only way to observe plugin behaviour is to run OpenCode from another terminal and capture its output, which defeats the purpose of an in-session debug flag.
This made diagnosing #189 unnecessarily difficult. The fix was found by manually patching the plugin to write to a file, then reading that file from within the session.
Proposal
When WMUX_PLUGIN_DEBUG=1, write structured log lines to a file instead of (or in addition to) console.error. A reasonable default:
The current console.error call only fires on execFile errors. A file log is cheap enough to record more:
Entry
Why it helps
Plugin init (env vars, resolved runtime)
Confirms the plugin loaded and found Node
Every event received (type + truncated props)
Shows whether OpenCode is emitting the expected events
Every wmux CLI call (command + args)
Shows what the plugin asked wmux to do
execFile result (ok / error message)
Shows whether the CLI call succeeded
Benefits
An agent can read the log file with its Read tool and diagnose issues within the same session.
Users can share the log file in bug reports without needing to reproduce in a special terminal setup.
No runtime cost when debug is off — the flag is checked once at init.
Context
Related to #189, which was diagnosed by manually adding appendFileSync logging to the plugin. That patch revealed the 17 ms blocked/unblocked race in seconds — the same issue had been invisible through console.error logging.
Shipped in v1.10.0 (9164e07), plugin version 4 — implemented as proposed, including the path form.
export WMUX_PLUGIN_DEBUG=1 # %TEMP%\wmux-plugin-debug.log / $TMPDIR/wmux-plugin-debug.logexport WMUX_PLUGIN_DEBUG=/tmp/wmux.log # anything else is taken as a path
console.error is gone rather than kept alongside — it corrupts the OpenCode TUI and, as you say, nobody can read it. A test asserts the shipped file contains no console.* call.
Logged: plugin init (resolved runtime, surface id, CLI path, pid), every event with a length-capped payload, every wmux CLI call, and each call's result.
Three things worth knowing:
Writes are synchronous. The ordering between an event and the CLI call it caused is the entire diagnostic — an async write reorders exactly the millisecond races this exists to catch.
Init is logged before the WMUX !== "1" gate, as init: inactive. "Loaded but did nothing" was previously indistinguishable from "never loaded", and it is the commonest failure.
Every write error is swallowed. A bad path or a full disk must not take OpenCode down; there is a test for a log path whose directory does not exist.
Zero cost when off: the destination is resolved once at init and the logger becomes a no-op.
Documented in docs/opencode-plugin.md, and the README now points people here before they file an OpenCode sidebar bug. One caveat noted there: the log records event payloads, so it can contain prompt text — read it before attaching it.
You were right that #189 was the argument for this. Thanks for filing both.
Activity
fix(opencode): keep the block through the ask's own part update, log …
amirlehmam commentedon Aug 23, 2026
Shipped in v1.10.0 (9164e07), plugin version 4 — implemented as proposed, including the path form.
console.erroris gone rather than kept alongside — it corrupts the OpenCode TUI and, as you say, nobody can read it. A test asserts the shipped file contains noconsole.*call.Logged: plugin init (resolved runtime, surface id, CLI path, pid), every event with a length-capped payload, every wmux CLI call, and each call's result.
Three things worth knowing:
WMUX !== "1"gate, asinit: inactive. "Loaded but did nothing" was previously indistinguishable from "never loaded", and it is the commonest failure.Zero cost when off: the destination is resolved once at init and the logger becomes a no-op.
Documented in docs/opencode-plugin.md, and the README now points people here before they file an OpenCode sidebar bug. One caveat noted there: the log records event payloads, so it can contain prompt text — read it before attaching it.
You were right that #189 was the argument for this. Thanks for filing both.