Skip to content

About

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

Topics

Resources

Security policy

Stars

52 stars

Watchers

0 watching

Forks

Repository files navigation

opencode-cmux

npm

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

Requirements

  • OpenCode ≥ 1.0, including OpenCode 2 (@opencode/cli)
  • 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
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.

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.

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's own OpenCode integration

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.

OpenCode 2 background service

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" in opencode-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 pane OC | …) 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 --standalone to give each tab its own server and the right notification target without directory matching.

What it does

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.

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

About

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

Topics

Resources

Security policy

Stars

52 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages