opencode-cmux

OpenCode plugin that bridges OpenCode events to cmux notifications and sidebar metadata.

Requirements

• OpenCode ≥ 1.0
• cmux (macOS app) installed; the plugin invokes cmux via $CMUX_BUNDLED_CLI_PATH (set by cmux's shell integration), falling back to cmux on $PATH
• The plugin is a no-op when not running inside a cmux workspace

Installation

Add to ~/.config/opencode/opencode.json:

{
  "plugin": ["opencode-cmux"]
}

OpenCode will download the package automatically on next start.

Local / development

Build the package, then symlink the output directly into OpenCode's plugin directory:

ln -sf ~/path/to/opencode-cmux/dist/index.js ~/.config/opencode/plugins/cmux.js

Make sure opencode-cmux is not listed in opencode.json when using the symlink, to avoid loading it twice.

Configuration

Create ~/.config/opencode/opencode-cmux.json to customize plugin behavior:

{
  "splits": true,
  "notifications": {
    "done": false
  }
}

Option	Type	Default	Description
splits	boolean	false	Open cmux split panes for subagent sessions
notifications.done	boolean	true	Show a popup when a session finishes
notifications.permission	boolean	true	Show a popup when OpenCode requests a permission
notifications.question	boolean	true	Show a popup when OpenCode asks a clarifying question
notifications.error	boolean	true	Show a popup when a session errors

If the file does not exist or any key is omitted, defaults are used. Each notification type can be toggled independently — useful when running multiple agents in parallel and per-turn Done popups become noisy.

Subagent splits

When splits is enabled and a subagent spawns, the plugin opens a cmux split with a live opencode attach view. Requires --port to expose an HTTP server:

opencode --port 0  # binds to first available port

Without --port, splits are silently skipped even when enabled.

What it does

Event	cmux action
Session starts working	Sidebar status: "working" (amber, terminal icon)
Session completes (primary)	Desktop notification + log + clear status
Session completes (subagent)	Log only (no notification spam)
Session error	Desktop notification + log + clear status
Permission requested	Desktop notification + sidebar status: "waiting" (red, lock icon)
AI has a question (ask tool)	Desktop notification + sidebar status: "question" (purple)

How it works

The plugin responds to OpenCode lifecycle events by firing cmux CLI commands (cmux rpc notification.create, cmux set-status, etc.). Each action targets the current cmux workspace, providing ambient awareness of what OpenCode is doing without requiring you to switch context. All commands are no-ops when cmux is not running.

License

MIT