npm package: @grympler/opencode-tmux-handover
Description: OpenCode Desktop plugin for launching tmux with AI assistants (OpenCode, Claude, Copilot) in split panes
Author: Olivier
Latest version: 1.0.4

# 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](https://github.com/anthropics/claude-cli) (`claude` command)
- **`/tmux-copilot`** - [GitHub Copilot CLI](https://github.com/github/copilot-cli) (`copilot` command)

## Install

```bash
./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`:

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

And symlink the commands:

```bash
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

```bash
./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.