OpenCode Tmux Plugin Suite

Launch tmux sessions from OpenCode with various AI assistants in split panes.

What It Does

This plugin provides multiple commands to open maximized tmux sessions:

• /tmux - Simple tmux session (single pane)
• /tmux-oc - Tmux with horizontal split, OpenCode in right pane
• /tmux-claude - Tmux with horizontal split, Claude in right pane
• /tmux-copilot - Tmux with horizontal split, GitHub Copilot in right pane

All commands run locally — no LLM calls, no token costs.

Requirements

• OpenCode Desktop (dev build with command.execute.before hook)
• tmux
• A terminal emulator (gnome-terminal, terminator, konsole, alacritty, kitty, xterm)

Optional - For AI Assistant Splits

• /tmux-oc - OpenCode (included with OpenCode Desktop)
• /tmux-claude - Claude CLI (claude command)
• /tmux-copilot - GitHub Copilot CLI (copilot command)

Install

./install.sh

This will:

1. Register the plugin in ~/.config/opencode/opencode.json
2. Symlink command definitions to ~/.config/opencode/commands/

Manual Installation

If you prefer to set it up manually, add the plugin path to your opencode.json:

{
  "plugin": [
    "/path/to/opencode-tmux-handover"
  ]
}

And symlink the commands:

ln -s $(pwd)/src/commands/tmux.md ~/.config/opencode/commands/
ln -s $(pwd)/src/commands/tmux-oc.md ~/.config/opencode/commands/
ln -s $(pwd)/src/commands/tmux-claude.md ~/.config/opencode/commands/
ln -s $(pwd)/src/commands/tmux-copilot.md ~/.config/opencode/commands/

Usage

Type any of the commands in OpenCode:

• /tmux - Simple tmux session
• /tmux-oc - Tmux + OpenCode split
• /tmux-claude - Tmux + Claude split
• /tmux-copilot - Tmux + Copilot split

Each command will:

• First run: Create a new tmux session
• Already in tmux: Create a new split in current window
• Session exists: Attach to existing session

Session names are based on directory names.

Uninstall

./uninstall.sh

This will unregister the plugin from opencode.json and remove command symlinks.

File Structure

src/
├── index.ts                    # Main plugin entry point
├── commands/
│   ├── tmux.md               # /tmux command definition
│   ├── tmux-oc.md            # /tmux-oc command definition
│   ├── tmux-claude.md        # /tmux-claude command definition
│   └── tmux-copilot.md       # /tmux-copilot command definition
└── scripts/
    ├── opencode-tmux.sh      # Simple tmux script
    ├── opencode-tmux-oc.sh   # OpenCode split script
    ├── opencode-tmux-claude.sh # Claude split script
    └── opencode-tmux-copilot.sh # Copilot split script

scripts/
├── register-plugin.js          # Registers plugin in opencode.json
└── unregister-plugin.js        # Unregisters plugin from opencode.json

install.sh                      # Installation script
uninstall.sh                    # Uninstallation script
package.json                    # Plugin manifest

How It Works

The plugin uses OpenCode's command.execute.before hook to intercept commands before they reach the LLM. When a command is detected:

1. The plugin executes the corresponding bash script
2. The script launches a terminal with tmux
3. For split commands, the AI assistant launches in the right pane
4. The command output is cleared (output.parts = []) to prevent LLM processing

The plugin is self-contained - bash scripts are referenced using relative paths from the plugin directory, so no global installation of scripts is needed.