Windows and tabs

The window model

vmuxMac uses standard macOS windows. Each window is a single terminal and runs one independent shell or remote session. There is no concept of "splits" inside a window on Mac — if you want two terminals side by side, you open two windows or two tabs.

Internally, every terminal — window or tab — has a unique pane identifier that follows it for its entire lifetime. That identifier is what tells the menu bar, the command palette, and the keyboard which terminal you are currently focused on. You will see it referenced in places that share code with vmux on visionOS, but you never need to type it.

When this manual says "pane," it means the terminal inside the window or tab you are currently focused on.

New windows and tabs

The two essential shortcuts:

• Cmd+N opens a new window.
• Cmd+T opens a new tab in the current window.

Both create a fresh local shell. They do not clone the working directory or environment of the previous terminal — every new window or tab starts in your home directory under your default shell. To start a new session in a specific directory, use the local shell: cd ~/projects/foo && open -a vmuxMac is one way; another is to run cd after the new window opens.

You can also create new windows from the File menu (replacing the default macOS New item) and from the command palette with the New Window and New Terminal entries.

macOS tab integration

vmuxMac uses native macOS tabs, which means the standard system behaviors apply:

• Drag a tab out of its window to make it a standalone window.
• Drag a window into another window's tab bar to merge them.
• Right-click the tab bar for Move Tab to New Window, Show Tab Bar, Show All Tabs, and other system items.
• The tab bar appears automatically when there is more than one tab and disappears with one tab.
• macOS's System Settings → Desktop & Dock → Prefer tabs when opening documents affects whether Cmd+N prefers new tabs or new windows.

If you prefer a strict one-window-per-terminal workflow, set the macOS preference to never for tabs. If you prefer everything to live in one window, set it to always and use Cmd+T as your default.

Closing windows

• Cmd+W closes the current window or tab.
• Cmd+Shift+W closes the entire window (including all tabs).
• Cmd+Q quits the app.

If the window has an active SSH or Mosh session, closing it disconnects the session. There is no confirmation prompt by default — if you want a prompt before closing connected sessions, the same setting that exists in vmux on visionOS applies (currently disabled on Mac while the terminal runs through libghostty).

Focus

The focused window is the one your keyboard sends bytes to. On macOS, focus follows the standard rules: clicking a window focuses it, Cmd+` cycles through vmuxMac's open windows, and Cmd+Tab switches between apps.

vmuxMac also offers Focus Follows Mouse, which switches focus to whichever window your pointer is currently over without requiring a click. Toggle it from the Mac tab in Settings, the command palette, or with the vsh command set-focus-follows-mouse. This is on by default and matches Ghostty's behavior. When focus-follows-mouse is on, hovering a window does not raise it to the front — it only routes keystrokes — so you can keep multiple windows visible and type into whichever one you point at.

Restoring sessions on relaunch

vmuxMac does not restore windows on the next launch. The system preference NSQuitAlwaysKeepsWindows is explicitly disabled, so quitting the app and reopening it always gives you a single fresh window. This is intentional: terminal state, especially with active SSH sessions, does not survive a quit.

If you want long-running sessions to outlive the app, run them on a remote host with tmux or screen, or use the vmux daemon on your workstation to keep panes alive while GUI apps come and go.

Full-screen and Spaces

vmuxMac windows support standard macOS full-screen. Use the green traffic-light button or the system shortcut Ctrl+Cmd+F. Full-screen windows live in their own Space.

The window's collection behavior includes fullScreenPrimary, which means a full-screen window can also host its tabs in the same Space. You can swipe between full-screen vmuxMac windows with the standard four-finger swipe (or three-finger, depending on your trackpad settings).

Mission Control treats vmuxMac windows like any other Mac app's windows. Hidden title bar windows still appear in Mission Control with the app icon and current title.

Hidden title bar mode

By default, vmuxMac uses a hidden title bar. The window background extends all the way to the top edge, the traffic-light controls float over the terminal, and the window title is implied by the active terminal's title rather than being shown explicitly.

Toggle this from Settings → Mac → Hidden Title Bar, or via the command palette entry Hidden Title Bar, or the vsh command set-titlebar. With the title bar visible, you get a standard macOS title bar with the running terminal's title displayed across the top.

Whichever mode you pick, the window remains opaque with a black background. vmuxMac does not currently use a glass or translucent background on Mac.

Window padding

The terminal content sits inside a configurable padding. The default is twenty pixels on each side, which gives a comfortable visual margin without wasting too much screen real estate.

Adjust it from Settings → Mac → Padding (range 0 to 80 pixels), the command palette Window Padding entry, or vsh. Setting padding to zero makes the terminal fill the entire window.

Multiple displays

Windows track which display they are on so the terminal can target that display's specific color profile and refresh rate. Move a window between displays and the engine adjusts automatically — there is no setting to configure.

If you start vmuxMac and a previously open window's saved frame is on a display that is no longer attached, vmuxMac re-centers the window on the main display at a sensible size (about nine hundred by six hundred pixels).

The menu bar

vmuxMac adds a Terminal menu with the most common actions, and replaces the default File → New with vmux-specific items.

The font-zoom commands target the focused pane: if multiple windows are open, only the one you are currently in is affected.

Where to go next

• Command palette — every command keyboard-accessible.
• Settings — toggle hidden title bar, padding, focus-follows-mouse.
• Connecting — start a remote session in a new window.