OpenCode plugin that bridges OpenCode events to cmux notifications and sidebar metadata.
- OpenCode ≥ 1.0, including OpenCode 2 (
@opencode/cli) - cmux (macOS app) installed; the plugin invokes
cmuxvia$CMUX_BUNDLED_CLI_PATH(set by cmux's shell integration), falling back tocmuxon$PATH - The plugin is a no-op when not running inside a cmux workspace
Add to ~/.config/opencode/opencode.json:
{
"plugin": ["opencode-cmux"]
}OpenCode will download the package automatically on next start.
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.jsMake sure opencode-cmux is not listed in opencode.json when using the symlink, to avoid loading it twice.
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 |
resolution |
string | "env" |
How the target workspace is chosen: "env" uses the server environment, "cwd" resolves it from the session's working directory |
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.
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 portWithout --port, splits are silently skipped even when enabled.
OpenCode 2 has no opencode attach and every server asks for a password. The split runs opencode --server <url> --session <id>, so it works only when OPENCODE_SERVER_PASSWORD is exported in your shell profile, where both OpenCode and the new pane can read it. Without it, splits are skipped.
cmux 0.65 can install its own OpenCode plugins with cmux hooks setup (or cmux hooks opencode install). They go in ~/.config/opencode/plugins/cmux-session.js and cmux-feed.js. With those and this plugin both loaded, every finished turn shows two notifications. Keep one of them: remove cmux's with cmux hooks opencode uninstall, or remove opencode-cmux from opencode.json.
By default OpenCode 2 runs sessions in one shared background service, and plugins run inside it. The service keeps the cmux variables of the tab that started it, so notifications from other tabs open that first tab. There are two ways to fix the target:
- Set
"resolution": "cwd"inopencode-cmux.json(recommended). The plugin then matches the session's working directory against the open cmux workspaces — preferring an exact match, then the longest matching prefix — and addresses notifications, sidebar statuses, and log entries to the workspace the session ran in. When several workspaces share a directory, the workspace with a running OpenCode TUI (the TUI titles its paneOC | …) is preferred. Resolutions are cached for 10 seconds. A session whose directory belongs to no open workspace (e.g. a temp directory) is not delivered anywhere, so the tab that started the service is not rung; the environment is used only when the directory is unknown or cmux cannot be queried. - Start OpenCode with
--standaloneto give each tab its own server and the right notification target without directory matching.
The sidebar uses the same states cmux shows for Claude Code and Codex.
| Event | cmux action |
|---|---|
| Session starts working or retries | Sidebar status: "Running" (blue, bolt.fill) |
| Session completes (primary) | Desktop notification with the start of the final response + log + sidebar status: "Idle" (gray, pause.circle.fill) |
| Session completes (subagent) | Log only (no notification spam) |
| Session error | Desktop notification with the error message + log + "Idle" |
| Session interrupted (Esc) | "Idle" (no notification) |
| Permission requested | Desktop notification + sidebar status: "Needs input" (blue, bell.fill) |
AI has a question (question tool) |
Desktop notification + "Needs input" |
"Needs input" stays until every pending permission and question is answered.
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.
MIT