tabby-tmux

中文

A Tabby plugin that provides tmux Control Mode integration, inspired by iTerm2 tmux Integration.

Features

• Native UI integration — Maps tmux windows and panes into native Tabby components
• Session persistence — tmux sessions survive Tabby restarts; reconnect via tmux -CC attach
• Window bar — Collapsible bottom bar for switching tmux windows, with support for creating new windows and disconnecting
• Layout sync — Automatically syncs tmux layout into Tabby SplitTab

Installation

Via Tabby Settings

1. Open Tabby → Settings → Plugins
2. Search for tabby-tmux
3. Click Install

Via command line

cd <tabby-plugins-dir>
npm install tabby-tmux

Usage

1. Open any terminal tab in Tabby
2. Right-click the tab → Enter Tmux Mode
3. The bottom window bar appears — switch between tmux windows and panes from there
4. Right-click → Exit Tmux Mode to detach

Configuration

Right-click behavior

By default, right-clicking inside a tmux pane opens the tmux pane context menu (used for actions like Enter/Exit Tmux Mode, New Window, etc.), regardless of the Settings → Terminal → "On right-click" option.

If you set "On right-click" to Paste or Clipboard in Tabby settings, this plugin will respect that choice:

• Quick right-click → performs the configured action (paste from clipboard / copy selection)
• Long press (≥ 250 ms) → still opens the tmux pane context menu, so all tmux features remain accessible

Tip: If the tmux menu feels hard to reach after changing the setting, hold the right mouse button down for a moment before releasing.

Keyboard shortcuts

In tmux mode, shortcuts are layered (see doc/DESIGN_KEYBINDINGS.md):

• Pane operations reuse Tabby's native shortcuts — they act on the tmux pane directly (the plugin translates them into tmux commands):
  • Split: Ctrl+Shift+S (right) / Ctrl+Shift+D (down)
  • Pane navigation: Ctrl+Alt+Arrow
  • Zoom pane (maximize): Ctrl+Alt+Enter — press again to unzoom (⌘+⌥+Enter on macOS)
• Window operations are tmux-mode-specific shortcuts (defaults below; rebind in Tabby Settings → Hotkeys):
  • Previous / next window: Ctrl+Shift+[ / Ctrl+Shift+]
  • Go to window 1–9: Ctrl+Shift+1..9
  • New window: Ctrl+Shift+B
  • Toggle tmux mode: Ctrl+Shift+X — exits tmux mode when connected; enters it from the active terminal tab when idle
• Tabby top-level shortcuts (switch/close tabs, etc.) are unchanged

All shortcuts — including the plugin-specific ones — are configured in Tabby Settings → Hotkeys; the plugin settings page intentionally has no shortcut form, to avoid a second conflicting entry point.

Compatibility

trzsz

This plugin is fully compatible with the tabby-trzsz plugin, enabling file transfer (trz/tsz) and drag-and-drop upload over tmux panes.

Install both plugins and they work together automatically:

cd <tabby-plugins-dir>
npm install tabby-tmux tabby-trzsz

Note: When uploading files over WebSocket terminals (e.g. via tabby-ws-term), use trzsz -B 10K to improve compatibility.

Development

pnpm install
pnpm run watch  # watch mode

# Launch Tabby with the plugin loaded
TABBY_PLUGINS=$(pwd) tabby --debug

License

MIT