$ termy docs
Tmux sessions
Optional tmux-backed tabs and panes.
Requires tmux ≥ 3.3 on PATH (macOS / Linux), or reachable through a command prefix (Windows / remote).
tmux_enabled = true
tmux_persistence = true
tmux_binary = tmux
tmux_command_prefix = none
tmux_show_active_pane_border = false| Key | Effect |
|---|---|
tmux_enabled | New tabs use tmux instead of a raw PTY |
tmux_persistence | Sessions survive app restarts |
tmux_binary | Path or name of the tmux binary |
tmux_command_prefix | Command that tmux runs through, e.g. wsl.exe -e or ssh myhost |
Open Manage tmux Sessions from the command palette, or bind manage_tmux_sessions.
Termy creates one session per window (termy-<window-id>). Splits map to real tmux panes.
Windows (WSL) and remote hosts
tmux cannot run natively on Windows, but Termy can drive a tmux that lives inside WSL
or on a remote machine. Set tmux_command_prefix to the command that reaches it:
# tmux inside WSL (default distro)
tmux_enabled = true
tmux_command_prefix = wsl.exe -e
# tmux on a remote host over SSH (needs key-based auth)
tmux_enabled = true
tmux_command_prefix = ssh myhostTermy then launches wsl.exe -e tmux ... (or ssh myhost tmux ...) for the control
channel and all session management commands. The prefix is split on whitespace, so it
cannot contain arguments with embedded spaces. On Windows, tmux mode stays off until a
prefix is configured. New sessions start in the default directory of the WSL distro or
remote shell — the host working directory is not forwarded.
Troubleshooting
| Symptom | Fix |
|---|---|
| Blank tabs | Set tmux_binary to an absolute path |
protocol version mismatch | Point tmux_binary at the tmux version you intend to use |
| Sessions lost on quit | Set tmux_persistence = true |
| Double active-pane border | Set tmux_show_active_pane_border = false |
| tmux mode ignored on Windows | Set tmux_command_prefix (e.g. wsl.exe -e) |
ssh prefix hangs at startup | Use key-based auth; the control channel cannot answer password prompts |