Skip to content

OpenCode plugin: log to file instead of console.error so agents can self-diagnose #190

Closed

Description

@zutur

Problem

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:

%TEMP%/wmux-plugin-debug.log     (Windows)
$TMPDIR/wmux-plugin-debug.log    (macOS/Linux)

Or let WMUX_PLUGIN_DEBUG accept a path — if the value is not "1", treat it as the log file path:

# boolean on, default log location
export WMUX_PLUGIN_DEBUG=1

# explicit path
export WMUX_PLUGIN_DEBUG=/tmp/wmux-debug.log

What to log

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.

Environment

  • wmux: v1.9.0 (plugin version 3)
  • OpenCode: latest (opencode.exe compiled binary)
  • OS: Windows 11

Activity

  1. amirlehmam commented on Aug 23, 2026

    @amirlehmam
    Owner

    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.log
    export 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions