opencode-tmux

Auto-spawn tmux panes for OpenCode subagent sessions — when OpenCode creates a child session, this plugin splits a new tmux pane and attaches it automatically.

How It Works

When OpenCode fires a session.created event for a child session (one with a parentID), the plugin:

1. Splits a new tmux pane horizontally
2. Runs opencode attach <serverUrl> --session <id> --dir <dir> in it
3. Applies your configured layout
4. Closes the pane when the session goes idle (if autoClose: true)
5. Polls periodically as a fallback to catch missed events

Requirements

• tmux ≥ 3.0 installed and in PATH
• OpenCode must be running inside a tmux session (the plugin is a no-op otherwise)
• opencode binary must be in PATH (for the attach command in spawned panes)

Usage

OpenCode must be started as a server with an explicit port so the plugin knows the serverUrl to pass to opencode attach in spawned panes:

opencode --port 3000

Without a port, the plugin cannot construct the serverUrl and the opencode attach <serverUrl> --session <id> command in new tmux panes will fail.

Installation

bun add @floschl/opencode-tmux

Register the plugin in your opencode.json (global ~/.config/opencode/opencode.json or project-local):

{
  "plugin": ["@floschl/opencode-tmux"]
}

Note: OpenCode validates opencode.json against its own strict schema and rejects unknown keys. Plugin config lives in a separate file — do not add "tmux": { ... } to opencode.json.

Configuration

Create opencode-tmux.json with the plugin's settings. Keys are flat (no nesting):

Global (~/.config/opencode/opencode-tmux.json):

{
  "layout": "main-vertical",
  "mainPaneSize": 60,
  "autoClose": true
}

Project-local (either path works; <project>/opencode-tmux.json takes precedence):

• <project>/opencode-tmux.json
• <project>/.opencode/opencode-tmux.json

Project-local config overrides global config. Unset keys fall back to defaults.

Configuration Reference

All keys go directly in opencode-tmux.json (flat, no nesting).

Key	Type	Default	Description
layout	string	"main-vertical"	tmux layout: main-vertical, main-horizontal, tiled, even-horizontal, even-vertical
mainPaneSize	number	60	Main pane size as percentage (10–90). Used with main-vertical / main-horizontal layouts
autoClose	boolean	true	Close pane automatically when session goes idle
pollIntervalMs	number	2000	How often (ms) to poll session status as a fallback
sessionTimeoutMs	number	600000	Max session lifetime in ms (10 min default) before force-close

Project-level opencode-tmux.json overrides global config.

Event Handling

Event	Action
session.created (child only)	Spawn new tmux pane with opencode attach
session.status → idle	Close pane (if autoClose: true)
session.status → busy	Re-spawn pane if session is known but pane was closed
session.deleted	Close pane unconditionally
Poll tick	Close idle / timed-out / long-missing sessions

Debugging

Set OPENCODE_TMUX_DEBUG=1 to enable verbose stderr logging:

OPENCODE_TMUX_DEBUG=1 opencode

Limitations

• tmux only — no support for other terminal multiplexers
• Child sessions only — top-level sessions (no parentID) are ignored
• Requires OpenCode to be started from within an active tmux session
• The opencode attach command must be available in the spawned pane's PATH