tabby-tmux-restore

Auto-restore tmux session attachments after SSH reconnect in Tabby.

When your PC sleeps or loses internet, SSH connections die but tmux sessions survive on the server. This plugin remembers which Tabby tab was connected to which tmux session and automatically re-attaches after SSH reconnects — zero manual steps.

Requirements

• Tabby 1.0.230+ (tested on this version)
• tmux on the server with title sequences enabled

Server-side setup

Add to ~/.tmux.conf on the server:

# Send session name as terminal title
set -g set-titles on
set -g set-titles-string "#{session_name}"

# Allow passthrough of title sequences
set -g allow-passthrough on

Then reload: tmux source-file ~/.tmux.conf

Install

From Tabby Plugin Manager

Settings → Plugins → search tabby-tmux-restore → Install → Restart Tabby

From npm (manual)

cd %APPDATA%\tabby\plugins
npm install tabby-tmux-restore --legacy-peer-deps

Restart Tabby.

How it works

1. Title detection: When you attach to a tmux session, tmux sends the session name as a terminal title via OSC escape sequence. The plugin captures this via Tabby's titleChange EventEmitter.

2. State persistence: The plugin saves a mapping of {SSH profile + host → tmux session name} to a JSON state file on disk.

3. Reconnect detection: When SSH reconnects (detected via sessionChanged$ observable), the plugin looks up the saved tmux session for this tab.

4. Auto-restore: After a 1.5s delay (to let the shell initialize), the plugin sends tmux attach -t <session> to the terminal. If the first attempt doesn't succeed, it retries once at 4s.

State file

• Windows: %APPDATA%\tabby-tmux-restore\state.json
• macOS/Linux: ~/.config/tabby-tmux-restore/state.json

You can view or edit this file to see or fix tab-to-session mappings.

Multi-tab support

The plugin supports multiple tabs to the same server with different tmux sessions. It uses Tabby's custom tab title (customTitle) to disambiguate tabs:

• When a tmux session is detected (e.g., "ops"), the plugin sets customTitle = "tmux:ops"
• This makes each tab's state key unique, even with the same SSH profile
• Tabby persists customTitle in its recovery token, so it survives restarts

Important: The plugin manages customTitle for SSH tabs where tmux sessions are detected. If you manually clear or edit the custom title (removing the tmux: prefix), that tab reverts to single-slot-per-host behavior.

Known limitations

• Session name format: Only tmux session names matching ^[a-zA-Z][a-zA-Z0-9_-]{0,63}$ are detected. Names starting with numbers or containing special characters are ignored (to avoid false positives from shell prompts).

• tmux colons: tmux converts : in session names to _ (colon is reserved as tmux's separator). Use hyphens instead.

• customTitle ownership: The plugin overwrites customTitle on SSH tabs when a tmux session is detected. Manual custom titles set by the user will be replaced with tmux:<session>. Clearing the custom title opts the tab back into legacy single-slot behavior.

Troubleshooting

• Tab title not updating: Verify set-titles on and allow-passthrough on are in your tmux.conf and reloaded.
• Plugin not loading: Tabby requires an author field in package.json. If you build from source, ensure it's present.
• Not auto-attaching after reconnect: Check state.json has the correct mapping. The plugin waits 1.5s after reconnect before sending the command.
• Wrong session attached: Delete the entry from state.json and re-attach manually. The plugin will learn the new mapping.

Development

npm install --legacy-peer-deps
npm run build      # production build
npm run watch      # dev build with watch

Built with TypeScript 5.x. Peer dependencies (tabby-core, tabby-terminal) are provided by Tabby at runtime.

License

MIT