opencode-remote-cmux

Temporary OpenCode plugin that emits an OSC 9 notification for completed primary sessions when OpenCode is running in an SSH remote environment.

The package is authored in TypeScript from src/ and published as compiled ESM JavaScript in dist/.

The plugin implementation is type-checked against the official @opencode-ai/plugin and @opencode-ai/sdk packages.

This exists as a workaround for opencode-cmux, which currently depends on the local cmux CLI and becomes a no-op in SSH remote sessions.

Current Scope

• Notify only
• Primary sessions only
• SSH remote sessions only by default
• No sidebar status, logs, permission prompts, or question prompts

Why this exists

opencode-cmux shells out to commands such as cmux notify. That works when OpenCode can reach the local macOS cmux binary and workspace state, but it does not work when OpenCode itself runs on a remote Linux host over SSH.

This plugin takes the smallest possible approach: when a primary session becomes idle, it writes an OSC 9 escape sequence to the controlling terminal (/dev/tty) so the local terminal stack can forward it to cmux.

If the process has no controlling terminal, it falls back to stdout.

When OpenCode runs inside tmux, the plugin wraps that OSC 9 sequence in tmux passthrough so it can reach the outer terminal. tmux still needs passthrough enabled; the config alone does not rewrite raw OSC output.

Installation

Add opencode-remote-cmux to the plugin array in ~/.config/opencode/opencode.json.

If you already use opencode-cmux, your config will usually look like this:

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

Restart OpenCode after saving the config. OpenCode will install npm plugins automatically at startup.

From a local checkout (Development)

Use this if you are testing this repository directly before publishing it to npm.

1. Link the entrypoint into OpenCode's local plugin directory:

npm run build
ln -sf ~/path/to/opencode-remote-cmux/dist/index.js ~/.config/opencode/plugins/remote-cmux-notify.js

2. Point ~/.config/opencode/opencode.json at that local file:

{
  "plugin": [
    "opencode-cmux",
    "~/.config/opencode/plugins/remote-cmux-notify.js"
  ]
}

3. Restart OpenCode.

Which one should I use?

• Use "opencode-remote-cmux" for normal installation.
• Use "~/.config/opencode/plugins/remote-cmux-notify.js" only when developing or testing from a local checkout.

After publishing, you can submit a PR to the OpenCode ecosystem list to make the plugin easier to discover.

Behavior

• On session.status with status.type === "busy", the plugin clears its duplicate-notify guard for that session.
• On session.status with status.type === "idle", the plugin:
  • checks that it is in a remote SSH session
  • skips subagent sessions
  • emits one OSC 9 notification for the primary session

The emitted message format is:

Done: <session title>

Environment controls

• OPENCODE_REMOTE_CMUX_NOTIFY=1: force-enable notifications even without SSH_CONNECTION or SSH_TTY
• OPENCODE_REMOTE_CMUX_NOTIFY=0: disable notifications even in SSH sessions

tmux

If you run OpenCode inside tmux, enable passthrough in your tmux.conf:

set -g allow-passthrough on

This is necessary but not sufficient on its own. The plugin now emits tmux passthrough-wrapped OSC 9 when TMUX is present, and your outer terminal stack still needs to support the notification sequence.

Development

Run tests with:

npm test

Build compiled output with:

npm run build

• Source: src/
• Package output: dist/
• Test output: .test-build/

Notes

• This is a temporary workaround, not a replacement for upstream remote support in opencode-cmux.
• Delivery still depends on your SSH and terminal path allowing OSC sequences through.

License

MIT