tmux Integration

Nexion includes a native tmux session manager that lets you attach to local and remote tmux sessions directly from the app. No command-line gymnastics: browse, create, attach, and detach tmux sessions through a visual floating panel.

Overview

tmux is a terminal multiplexer that lets you run persistent terminal sessions on local or remote machines. Nexion wraps tmux with a native macOS interface so you can:

  • • Browse sessions visually: See all tmux sessions on any host with live status (attached/detached, window count, creation time).
  • • Attach with one click: Double-click any session to attach, or use the "Attach" button. Nexion opens a dedicated split pane for the session.
  • • Manage sessions: Create new sessions with custom names, delete sessions you no longer need, and refresh the session list in real time.
  • • Connect to remote hosts via SSH: Nexion reads your ~/.ssh/config and lists all configured hosts. Remote and local tmux sessions go through the same UI flow.

Getting Started

Prerequisites

  • • tmux installed: Nexion detects tmux at /opt/homebrew/bin/tmux (Apple Silicon), /usr/local/bin/tmux (Intel), or /usr/bin/tmux (system), in that order. Install with: brew install tmux
  • • For remote hosts: tmux must also be installed on the remote machine, and you need a working SSH configuration in ~/.ssh/config.

Enable the tmux Button

The tmux attach button is hidden by default. To enable it:

  1. Open Preferences (Cmd+Shift+,)
  2. Go to the General tab
  3. Check "Show tmux attach button in toolbar"

Once enabled, a tmux Attach button appears in the toolbar of any project tab. Click it to open the tmux session panel.

The Session Panel

The tmux session panel is a floating window split into two areas:

Connections Sidebar (Left)

Lists all available hosts:

  • • Local: Your local machine (always shown first).
  • • SSH Hosts: Every Host entry from your ~/.ssh/config is listed automatically. Wildcard patterns (*, ?) are excluded. Each entry shows the host alias and, where available, the user@hostname details.

Sessions Panel (Right)

Shows all tmux sessions on the selected host with live status:

Info Description
Session Name The name of the tmux session
Status Indicator Green dot = attached, gray dot = detached
Window Count Number of tmux windows in the session
Created Relative timestamp (e.g. "2h ago")

Session Actions

Action How
Attach to Session Double-click or click the Attach button. Opens in a new split pane.
Create New Session Click + New Session, optionally type a name, then press Create. Auto-names to nexion-XXXX if left blank.
Delete Session Hover over a session and click Delete. Requires confirmation: kills the session and all its processes.
Refresh Cmd+R or click the refresh button to reload sessions.

How Attach Works

When you attach to a tmux session, Nexion:

  1. Opens a new horizontal split pane in your terminal: the session is never sent into an existing shell (to avoid conflicts with running LLMs or nested tmux).
  2. Sends the tmux attach-session -t <name> command automatically.
  3. Hides tmux's built-in status bar (set -g status off) since Nexion provides its own status indicator.
  4. Unsets the $TMUX environment variable so you can attach even from within another tmux session.

Status Bar

When attached to a tmux session, a green "tmux: session-name" badge appears in the pane status bar.

Detach using the tmux keyboard shortcut Ctrl+B, D or by closing the pane.

Remote SSH Sessions

Nexion makes remote tmux sessions first-class citizens. When the remote agent is connected, tmux operations use fast RPC calls instead of SSH subprocesses.

  • • Agent-accelerated: When the remote agent is running, tmux list/create/kill/configure operations use JSON-RPC (~10ms), bypassing SSH subprocess overhead. Falls back to SSH subprocess when the agent is unavailable.
  • • Automatic SSH config parsing: All hosts from ~/.ssh/config appear in the sidebar. No extra configuration needed.
  • • 1Password & SSH agent support: Nexion allocates a real PTY for SSH authentication. That lets 1Password biometric prompts and SSH_ASKPASS-style helpers run interactively, which most GUI Git/tmux clients block.
  • • Independent connections: Each tmux tab creates its own ControlMaster socket. Closing one tab doesn't affect other sessions on the same host.
  • • Inline tmux config: Nexion applies its tmux settings (status bar off, mouse on, clipboard, truecolor) inline before attaching, so the session is pre-configured without extra SSH round-trips.
  • • Session restore: SSH+tmux tabs are restored when you reopen Nexion. The tmux session name is saved, and the tab re-attaches automatically on startup.
  • • Remote shell detection: Commands are wrapped in a login shell on the remote host, so tmux is found even when it's installed via Homebrew and not in the default PATH.

SSH Config Example

To connect to remote tmux sessions, add hosts to ~/.ssh/config: 

Host dev-server
    HostName 192.168.1.100
    User deploy
    Port 22

Host production
    HostName prod.example.com
    User admin
    IdentityFile ~/.ssh/prod_key

Both dev-server and production will appear in the Connections sidebar. Click one to browse and attach to its tmux sessions.

Keyboard Shortcuts

Session Management

Action Shortcut
Open tmux Session Panel Click the tmux Attach toolbar button
Refresh Sessions Cmd+R (inside the panel)
Detach from Session Ctrl+B, D or close the pane

Pane Management (inside tmux or Nexion)

When attached to a tmux session, Nexion's native pane management shortcuts still work. You can also use standard tmux keybindings (prefixed with Ctrl+B):

Action Nexion Shortcut tmux Shortcut
Split Vertically Cmd+D Ctrl+B, %
Split Horizontally Cmd+Shift+D Ctrl+B, "
Close Pane Cmd+W Ctrl+B, X
Next Pane Cmd+Opt+Right or Cmd+Opt+Down Ctrl+B, O
Previous Pane Cmd+Opt+Left or Cmd+Opt+Up Ctrl+B, ;
Resize Left Cmd+Ctrl+Left Ctrl+B, Left
Resize Right Cmd+Ctrl+Right Ctrl+B, Right
Resize Up Cmd+Ctrl+Up Ctrl+B, Up
Resize Down Cmd+Ctrl+Down Ctrl+B, Down
Zoom / Unzoom Pane Cmd+Shift+Z Ctrl+B, Z
Equalize Panes Cmd+Opt+E -
Rotate Clockwise Cmd+Opt+R Ctrl+B, }
Rotate Counter-clockwise Cmd+Opt+Shift+R Ctrl+B, {
Mark / Swap Pane Cmd+Opt+M -
Synchronized Input Cmd+Opt+S Ctrl+B, :setw synchronize-panes
Show Pane Numbers Cmd+Opt+Q Ctrl+B, Q
Rename Pane Cmd+Opt+N -
Break Pane to New Tab Cmd+Shift+B Ctrl+B, !
Join Pane from Another Tab Cmd+Opt+J -
Layout Presets 1 to 5 Cmd+Opt+1 through Cmd+Opt+5 Ctrl+B, Opt+1 through Opt+5
Detach from Session Close pane Ctrl+B, D

Nexion shortcuts (Cmd-based) operate on Nexion's own split panes. The tmux column shows default tmux keybindings: every binding (including the prefix Ctrl+B) can be remapped via ~/.tmux.conf. If you have a custom config, your bindings may differ.

Tips & Best Practices

  • • Persistent workflows: Use tmux sessions for long-running processes (builds, servers, watchers). Detach when you're done, and re-attach later without losing state.
  • • Remote dev environments: Attach to tmux on your development server, run builds remotely, and detach without killing the process. Come back hours later and everything is still running.
  • • Combine with split panes: Nexion attaches tmux sessions in a new split pane, so you can work in your local terminal side-by-side with a remote tmux session.
  • • Name your sessions: Give sessions meaningful names (e.g. api-server, build-runner) for easy identification in the panel.

Troubleshooting

Problem Solution
"tmux not found" Install tmux: brew install tmux
"No sessions" Start a session first: tmux new -s mywork, or create one via the "New Session" button.
SSH authentication failed Verify your SSH key is loaded (ssh-add -l) and your ~/.ssh/config is correct.
Connection timed out Check that the remote host is reachable and SSH is running on the expected port.
tmux not found on remote Install tmux on the remote host. Nexion wraps commands in a login shell, but tmux must be installed.