Skip to main content
Termy’s tmux integration provides powerful terminal multiplexing capabilities with a native UI. This guide will walk you through enabling tmux, managing sessions, and working with panes.

​
What is Tmux Integration?

Tmux integration allows you to:
  • Manage multiple terminal sessions that persist across app restarts
  • Split your terminal into multiple panes for side-by-side workflows
  • Switch between sessions seamlessly
  • Keep your work running even when Termy is closed
Termy integrates with tmux through control mode, giving you the power of tmux with Termy’s modern UI.

​
Prerequisites

Before enabling tmux integration, ensure you have tmux installed: 
# macOS (Homebrew)
brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux

# Fedora/RHEL
sudo dnf install tmux
Termy requires tmux 3.3 or later.

​
Enabling Tmux

1

Open Configuration

Open your Termy configuration file at ~/.config/termy/config.txt
2

Enable Tmux Integration

Set tmux_enabled to true:
tmux_enabled = true
3

Configure Optional Settings

Customize additional tmux settings:
# Reuse tmux tabs and panes across app restarts
tmux_persistence = true

# Custom tmux binary path (if not in PATH)
tmux_binary = tmux

# Show active pane border highlight
tmux_show_active_pane_border = false
4

Restart Termy

Restart Termy to apply the changes. Termy will now launch in tmux mode.
When tmux_persistence is enabled, your tabs and panes will persist across app restarts. Termy creates a dedicated tmux socket named termy to manage sessions.

​
Session Management

​
Creating and Switching Sessions

Access tmux session management through the command palette or File menu:
1

Open Session Manager

Press Cmd+P (macOS) or Ctrl+P (Linux/Windows) to open the command palette, then search for “tmux Sessions”
2

Session Operations

From the session manager, you can:
  • Attach to existing sessions
  • Create new sessions
  • Switch between active sessions
  • Rename sessions
  • Delete sessions

​
Session Naming

When creating a new session, provide a meaningful name: 
work
project-api
devops-tasks
Session names help you quickly identify and switch between different contexts.
Deleting a session will terminate all processes running in that session’s panes. Make sure to save your work before deleting.

​
Pane Operations

​
Splitting Panes

Termy provides intuitive pane splitting: Vertical Split (side-by-side):
  • Command Palette: Search for “Split Pane Vertical”
  • The keybinding is configurable via config.txt
Horizontal Split (top-bottom):
  • Command Palette: Search for “Split Pane Horizontal”
  • The keybinding is configurable via config.txt
1

Split Your First Pane

Open the command palette and select “Split Pane Vertical” to create a side-by-side layout
2

Navigate Between Panes

Click on any pane to focus it, or use keyboard shortcuts to switch focus
3

Resize Panes

Drag the divider between panes to adjust their size

​
Closing Panes

To close a pane:
  1. Focus the pane you want to close
  2. Type exit or press Ctrl+D to terminate the shell
  3. The pane will automatically close
Alternatively, use the command palette and search for “Close Pane”.

​
Pane Focus Highlighting

When working with multiple panes, Termy visually highlights the active pane: 
# Adjust the dimming effect for inactive panes
pane_focus_effect = soft_spotlight
pane_focus_strength = 0.6

# Show a border around the active pane (tmux mode)
tmux_show_active_pane_border = false

​
Keyboard Shortcuts

Customize tmux-related keybindings in your config.txt: 
# Example keybindings (customize to your preference)
keybind = cmd-d=split_pane_vertical
keybind = cmd-shift-d=split_pane_horizontal
keybind = cmd-w=close_pane
Tmux-only keybind actions require an active tmux session to function.

​
Persistence and Recovery

With tmux_persistence = true, Termy preserves your workspace: What Persists:
  • Tab layout and arrangement
  • Pane splits and sizes
  • Working directories
  • Session names
What Doesn’t Persist:
  • Running processes (they terminate when Termy closes)
  • Scrollback buffer contents
  • Command history within the session
1

Close Termy

Quit Termy normally
2

Reopen Termy

Launch Termy again
3

Resume Work

Your tabs, panes, and layout will be restored automatically

​
Troubleshooting

​
Tmux Version Error

tmux 3.3+ required, found 3.2
Solution: Update tmux to version 3.3 or later: 
# macOS
brew upgrade tmux

# Ubuntu (may need to add PPA for newer version)
sudo add-apt-repository ppa:tmux/tmux
sudo apt-get update
sudo apt-get install tmux

​
Custom Tmux Binary Path

If tmux is not in your PATH: 
tmux_binary = /opt/homebrew/bin/tmux

​
Session Won’t Attach

If Termy can’t attach to a session:
  1. Check if tmux is running: 
    tmux -L termy list-sessions
  2. Kill stale sessions: 
    tmux -L termy kill-session -t session_name
  3. Restart Termy with a fresh tmux socket
Termy uses a dedicated socket named termy (via tmux -L termy). Don’t manually attach to these sessions from the command line, as it may interfere with Termy’s control mode.

​
Control Mode Issues

If you see control mode errors:
  1. Ensure no other application is using the termy tmux socket
  2. Check tmux version compatibility
  3. Verify tmux binary path in configuration

​
Advanced Configuration

​
Custom Socket Name

Termy uses the socket name termy by default. This keeps Termy sessions separate from your manual tmux sessions.

​
Window Options

For managed sessions, Termy overrides certain tmux window options to ensure proper integration. These are configured automatically.

​
Shell Integration

When tmux mode is enabled, Termy disables shell integration environment variables for tmux child processes: 
# These are NOT exported in tmux sessions
TERMY_SHELL_INTEGRATION=0
TERMY_TAB_TITLE_PREFIX is removed
This prevents conflicts between tmux control mode and shell-level integration.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us