Usage

Basic Commands

# Start a new session (auto-starts server if needed)
wtmux

# Start a named session
wtmux new-session -s work

# List sessions
wtmux ls

# Test whether a session exists (exit code only)
wtmux has-session -t work

# Rename a session
wtmux rename-session -t work main

# Attach to the most recent session
wtmux attach

# Attach to a named session
wtmux attach -t work

# Kill a session
wtmux kill-session -t work

# Kill the server and all sessions
wtmux kill-server

# Set a session status-bar option at runtime (e.g. from a shell prompt)
wtmux set-option status-right " branch: main "

# Set the global default used by sessions without an override
wtmux set-option -g status-right " %H:%M "

# Query option values at runtime
wtmux show-option -g status-right
wtmux show-option -g
wtmux show-options -g

# Show or print a formatted message
wtmux display-message "#{session_name}: #{window_name}"
wtmux display-message -p "#S:#I:#W"

# Show a large clock in a pane until any key is pressed
wtmux clock-mode [-t target]

# Clear a pane's scrollback history
wtmux clear-history [-t target]

# Capture or pipe pane content
wtmux capture-pane [-p] [-e] [-S start] [-E end] [-b buffer] [-J] [-t pane]
wtmux pipe-pane [-I] [-O] [-o] [-t pane] [shell-command]

# Manage windows
wtmux kill-window [-a] [-t target]
wtmux last-window
wtmux move-window [-r] [-s src] [-t dst]
wtmux swap-window [-s src] [-t dst]
wtmux link-window [-s src] [-t dst] [-k]
wtmux unlink-window [-t target] [-k]
wtmux find-window match

# Rearrange panes
wtmux swap-pane [-dDU] [-s src] [-t dst]
wtmux rotate-window [-DU]
wtmux last-pane
wtmux break-pane [-d] [-s src]
wtmux join-pane [-s src] [-t dst] [-h|-v]
wtmux move-pane [-s src] [-t dst] [-h|-v]
wtmux select-layout [-t target] <layout>
wtmux next-layout [-t target]

# Ask for y/n confirmation before running a command
wtmux confirm-before -p "kill-pane? (y/n)" kill-pane

# Set or show environment variables applied to newly created panes
wtmux set-environment -g FOO bar
wtmux show-environment -g

# Send keys to a pane (scripting / automation)
wtmux send-keys -t work "echo hello" Enter

# Manage paste buffers
wtmux set-buffer "text to paste"
wtmux show-buffer -b 0
wtmux save-buffer [-a] [-b name] <path>
wtmux load-buffer [-b name] <path>
wtmux list-buffers
wtmux paste-buffer -b 0 -t work
wtmux choose-buffer

# Start with a specific shell
wtmux new-session -c "pwsh.exe"

# Start in a specific directory
wtmux new-session -d "C:\Projects"

Shell Completion

wtmux can generate completion scripts for PowerShell, bash, zsh, and fish. Add the command for your shell to its startup file:

PowerShell ($PROFILE):

wtmux completion powershell | Out-String | Invoke-Expression

bash (~/.bashrc):

source <(wtmux completion bash)

zsh (~/.zshrc):

source <(wtmux completion zsh)

fish (~/.config/fish/config.fish):

wtmux completion fish | source

The scripts complete commands, aliases, command-specific flags, option and format-variable names, live session targets, and paste-buffer names. Dynamic session and buffer candidates are read from the running wtmux server. If no server is running, completion remains silent, does not start one, and continues to provide static candidates.

Default bindings

See the Default Bindings reference for every built-in prefix, root, custom-table, mouse, and copy-mode binding and the exact override precedence.

Full-screen pagers and cursor keys

wtmux mirrors the active pane's normal/application cursor-key mode to the host terminal. Arrow keys therefore use the SS3 sequences expected by full-screen applications such as the less pager opened by git diff. With mouse on, unbound wheel events over an application that requested application cursor keys, entered the alternate screen, or hid the cursor for full-screen input, but did not request mouse tracking, are translated into Up/Down cursor keys; explicit mouse bindings still take precedence.

Window status flags

The status bar shows tmux-style window flags in the window list: * for the current window, - for the previously selected window, # for monitored activity, ! for a bell, ~ for silence, and Z for a zoomed pane. Activity and bell flags clear when you switch to that window; silence clears when the window produces output again.

An application BEL (0x07) in a window allowed by bell-action is forwarded as one host-terminal bell to each client attached to the session. Windows Terminal then applies its configured sound/flash behavior. visual-bell on uses only wtmux's transient visual alert; visual-bell both keeps the host bell and the visual alert.

Host terminal working directory

When the active pane reports its current directory with OSC 7 or OSC 9;9, wtmux forwards the normalized path to the attached host terminal. Windows Terminal can then use the active pane's directory for Duplicate Tab, Duplicate Pane, and similar shell-integration actions. The host directory updates when you change panes, windows, or sessions; reports from background panes take effect only after that pane becomes active.

wtmux generates a new sanitized sequence rather than forwarding pane output. It uses Windows Terminal's OSC 9;9 form for native Windows paths and OSC 7 with a file URI when URI encoding is needed. Paths are limited to 4096 characters, terminal control characters are removed, and unchanged updates are suppressed. If the active path is unavailable, or when the client detaches, the host is restored to the directory from which the wtmux client was attached.

Retaining and respawning panes

Set remain-on-exit to keep a pane visible after its command exits instead of closing it automatically:

set -g remain-on-exit on

A retained pane keeps its final screen contents and shows a [dead] marker. Use respawn-pane from the command prompt or a key binding to restart a dead pane's original command. Pass a new shell command to replace it, or use -k to kill and restart a pane that is still running:

respawn-pane
respawn-pane -k pwsh
respawn-window -k "dotnet test"

respawn-window applies to every pane in the target window; without a new shell command, each pane reuses its own original command.

Window management

wtmux supports tmux-style window management for reordering, sharing, and finding windows without restarting the processes running inside panes:

kill-window [-a] [-t target]
last-window
move-window [-r] [-s src] [-t dst]
swap-window [-s src] [-t dst]
link-window [-s src] [-t dst] [-k]
unlink-window [-t target] [-k]
find-window match
  • kill-window destroys the target window immediately. Use -a to kill every window except the current one.
  • last-window switches back to the previously selected window. Press Ctrl+B then l to toggle between the current and previous window.
  • move-window moves a source window to a numeric target index and renumbers the session from base-index; -r only renumbers the existing order. Press Ctrl+B then . to open a prompt prefilled with move-window -t .
  • swap-window exchanges two windows' positions while preserving their panes and running processes.
  • link-window adds the same live window to another session's window list. Use -k when the destination index is occupied and should be replaced.
  • unlink-window removes a linked window from the current or target session. The underlying panes keep running until the last linked session removes the window.
  • find-window match searches window names and pane titles. One match switches directly; multiple matches open a filtered chooser. Press Ctrl+B then f to search interactively.

Window targets use the same forms as other commands: a window index like 1, a session target like work:1, or a pane id such as %3.

Pane rearrangement

wtmux supports tmux-style pane rearrangement without restarting the processes running inside panes:

swap-pane [-dDU] [-s src] [-t dst]
rotate-window [-DU]
last-pane
break-pane [-d] [-s src]
join-pane [-s src] [-t dst] [-h|-v]
move-pane [-s src] [-t dst] [-h|-v]
select-layout [-t target] <layout>
next-layout [-t target]
  • swap-pane swaps two panes while keeping the current layout shape and split sizes. Use -U or -D to swap the active pane with the previous or next pane in layout order, or use -s and -t for explicit source and target panes. -d keeps the currently active pane selected.
  • rotate-window cycles panes through the current window's layout positions. -D is the default direction; -U rotates the opposite way. Press Ctrl+B then Ctrl+o to rotate the active window.
  • last-pane selects the previously active pane. Press Ctrl+B then ; to toggle between the current and previous pane.
  • break-pane moves the active pane into its own new window, preserving its scrollback, cursor state, title, and running process. Press Ctrl+B then ! to break the active pane; -d leaves the current window active.
  • join-pane and move-pane move a source pane into the target pane's window, splitting the target pane. Use -h for a left/right split and -v for a top/bottom split. If the source window becomes empty, it closes automatically.
  • select-layout rebuilds the existing binary pane tree as tiled, even-horizontal, even-vertical, main-horizontal, or main-vertical. Pane processes, buffers, pane ids, the active pane, and the previously active pane are preserved.
  • next-layout cycles in tmux order: even-horizontal, even-vertical, main-horizontal, main-vertical, then tiled. Press Ctrl+B then Space to cycle the active window.

Pane ordering is deterministic. Non-main layouts retain the current layout traversal order (top/left branches before bottom/right branches); even-horizontal places that order left-to-right, even-vertical places it top-to-bottom, and tiled places it row-by-row with earlier rows receiving an extra pane when the count is uneven. Main layouts make the active pane the primary pane (top for main-horizontal, left for main-vertical) with 60% of the usable primary dimension; other panes retain their relative traversal order. Applying or cycling a layout while zoomed keeps the pane zoomed and applies the new arrangement when zoom is toggled off.

Targets accept pane ids such as %3 and the existing window target forms used by commands like send-keys, clock-mode, and respawn-pane.

Synchronize panes

Press Ctrl+B then S to toggle synchronize-panes for the current window. When enabled, typed input is duplicated to every live pane in that window. Copy mode, menus, pickers, and popups keep owning their input and are not mirrored.

You can also toggle or set it from the command prompt or CLI:

setw synchronize-panes          # toggle current window
setw synchronize-panes on       # enable current window
setw synchronize-panes off      # disable current window
setw -t 1 synchronize-panes on  # enable a target window

Add #{synchronize_panes} (or #{pane_synchronized}) to a status format to show 1 when the active window is synchronized and 0 otherwise.

Clock mode

Press Ctrl+B then t, or run clock-mode [-t target] from the command prompt, to display a large digital clock centered in a pane. Any key press exits clock mode without forwarding that key to the pane. Configure 12- or 24-hour display with clock-mode-style, and set the digit color with clock-mode-colour.

Copy mode

Copy mode lets you browse a pane's scrollback without changing the live process. Press Ctrl+B then [ to enter it. See Copy-mode defaults for the complete keyboard, mouse, and live-bottom behavior.

Use clear-history [-t target] from the command prompt or CLI to clear a pane's retained scrollback while leaving the visible screen intact. If the current client is viewing the target pane in copy mode, wtmux exits copy mode safely before repainting.

Use capture-pane to copy pane content without entering copy mode:

wtmux capture-pane -p                  # print the visible screen
wtmux capture-pane -S -100 -E -1 -p    # print the last 100 scrollback lines
wtmux capture-pane -b build-log -S -200 # save a range to a named paste buffer

By default, capture-pane captures the visible screen and saves it to a new paste buffer. -p prints to stdout instead. -S and -E select line ranges: negative values address retained scrollback before the visible screen, while 0 starts at the top visible row; - or an omitted value uses the default visible-screen edge. -J joins captured rows after trimming trailing blanks. -e includes best-effort SGR style/color escape sequences for captured cells; it does not reconstruct non-SGR terminal state or Sixel graphics.

Use pipe-pane to connect a pane to a command:

wtmux pipe-pane -O -t %3 "findstr ERROR > errors.txt" # pane output -> command stdin
wtmux pipe-pane -I -t %3 "type commands.txt"          # command stdout -> pane input
wtmux pipe-pane -o -O "more > pane.log"               # toggle the same command off/on
wtmux pipe-pane -t %3                                  # turn off the active pipe

-O is the default and writes raw pane output bytes to the command's stdin. -I feeds the command's stdout back into the pane as input; combine -I and -O for bidirectional piping. -o closes an existing pipe on the target pane when the same command is already active. Output piping is best-effort and uses a bounded queue, so wtmux drops chunks rather than blocking pane rendering if the pipe command stops reading fast enough.

Paste buffers

Copy mode keeps a tmux-like paste buffer stack. Each copy creates a new numbered automatic buffer; the most recent automatic buffer is 0, older automatic buffers are renumbered to 1, 2, and so on. Named buffers can be created explicitly and are selected by name.

Press Ctrl+B then ] to paste the most recent buffer into the active pane. The paste is sent through the pane's ConPTY, the same as typed input or send-keys.

wtmux set-buffer [-a] [-b name] <text>
wtmux show-buffer [-b name]
wtmux save-buffer [-a] [-b name] <path>
wtmux load-buffer [-b name] <path>
wtmux paste-buffer [-b name] [-t target] [-d]
wtmux list-buffers
wtmux delete-buffer [-b name|-a]
wtmux choose-buffer
  • set-buffer creates a new automatic buffer when -b is omitted. With -b name, it sets or creates a named buffer; -a appends to the selected buffer.
  • show-buffer prints the full text of the top buffer by default, or the selected buffer with -b.
  • save-buffer writes the full text to a client-side path; -a appends, and - writes to stdout.
  • load-buffer reads a client-side path into a new automatic buffer or the selected named buffer; - reads from stdin.
  • Content sent by set-buffer or load-buffer must fit within the 10 MB IPC message limit. Oversized input exits with a clear size-limit error.
  • paste-buffer pastes the top buffer by default, or the named/numbered buffer selected by -b. -t accepts the same targets as send-keys; -d deletes the buffer after pasting.
  • list-buffers shows buffer names, sizes, and previews.
  • delete-buffer deletes the top buffer by default, a selected buffer with -b, or all buffers with -a.
  • choose-buffer opens an interactive picker. Press Enter to paste the highlighted buffer into the active pane, d to delete it, or Esc/q to cancel. Press Ctrl+B then = to open it while attached.

Window, pane, buffer, and client pickers

Press Ctrl+B then w to open the window tree picker. Use ↑/↓ or k/j to move, Enter to switch to the highlighted window or pane, and Esc or q to cancel. Press Ctrl+B then = to open the paste-buffer picker. Use the same movement keys, Enter to paste the highlighted buffer into the active pane, d to delete it, and Esc or q to cancel. Press Ctrl+B then D, or run choose-client from the attached command prompt, to list every attached client. Entries show a server-local client number, session name, and terminal dimensions; * marks the current client. Use the same movement keys, then press Enter (matching tmux's default action) or d to detach the highlighted client. Detaching the current client safely ends the current attachment. HUP and suspend actions are not yet supported. Press Ctrl+B then q to display numbers over the panes in the current window. Press the shown digit to focus that pane, or Esc to cancel.

On-screen overlays

wtmux supports tmux-style overlays from the command prompt, key bindings, config commands, and the CLI where noted.

# Show a transient status-line message for display-time milliseconds
wtmux display-message "#{session_name}: #{window_name}"

# Print the expanded format to stdout instead of drawing a status message
wtmux display-message -p "#S:#I:#W"

# List supported status/message format variables
wtmux display-message -a

# Show an interactive menu; arguments are name/key/command triples
# (quote commands that contain spaces)
display-menu -T Actions Split s "split-window -h" Popup p "display-popup -E pwsh"

# Open a centered popup shell, or run a command in a sized popup
display-popup
display-popup -E -w 100 -h 30 pwsh
  • display-message [-p|-a] <message> expands the same #S, #I, #W, #{session_name}, #{window_name}, and related formats used by the status bar. Without -p, the expanded text temporarily replaces the status line. With -p, it is printed to stdout and does not attach to the session. With -a, wtmux lists the supported format variables and operators.
  • display-menu [-T title] [-x X] [-y Y] <name key command>... draws a small menu at the requested zero-based cell position, or centered when no position is supplied. Use ↑/↓ or k/j to move, Enter to run the highlighted command, a listed item key to run that item directly, and Esc, q, or Ctrl+C to cancel. When mouse is on, left-click an item to run it or click outside the menu to dismiss it.
  • display-popup [-E] [-w width] [-h height] [-x X] [-y Y] [shell-command] draws a bordered ConPTY popup above the pane layout. With no command, it runs the session's default shell. Input is routed to the popup until you press Esc; with -E, the popup also closes when the command exits. Width and height are cells including the border and default to about 75% of the client area.

Environment Variables

When wtmux spawns a shell for a pane, it injects environment variables so processes, scripts, and shell prompts can detect that they are running inside a wtmux session (mirroring tmux's $TMUX/$TMUX_PANE):

Variable Description
WTMUX Set inside every wtmux pane. Value is <pipe-name>,<server-pid>,<session-id>. Absent outside of wtmux.
WTMUX_PANE Identifies the current pane, formatted as %<pane-id>.

All other environment variables are inherited from the wtmux server's environment. Use set-environment to add, override, or remove variables for panes created after the change:

wtmux set-environment [-g] NAME VALUE
wtmux set-environment [-g] -u NAME
wtmux show-environment [-g]

Without -g, the change applies to the current wtmux session (when run from inside a pane). With -g, it applies globally to new panes in all sessions. Configured variables override inherited variables; unset variables are removed from the child environment. WTMUX and WTMUX_PANE are always set by wtmux.

Desktop Notifications

Pane applications can request a Windows desktop notification with OSC 9:

ESC ] 9 ; message BEL

wtmux accepts notifications only from the active pane of the active window. Notifications from background panes or windows are dropped rather than deferred, and only clients currently attached to the owning session receive the event. Each eligible attached client receives one sanitized host-terminal OSC 9 notification; detached clients and clients that have switched sessions do not receive stale notifications.

The current pane title is used as the notification title (falling back to wtmux). Titles are limited to 128 UTF-16 code units and messages to 1024. ESC, BEL, ST, and all other C0/C1 controls are removed, and empty messages are dropped. Pane text is never inserted into a screen-update frame; the client re-sanitizes the modeled body before emitting the host OSC 9 sequence. Core wtmux does not create native Windows toast notifications; that desktop integration is left to an optional plugin.

Sixel Graphics

wtmux supports Sixel image output from pane applications when the attached host terminal advertises Sixel capability. The server decodes Sixel DCS payloads into bounded in-memory image placements attached to the pane buffer, then re-emits those modeled images into the composed frame for Sixel-capable clients. Clients that do not support Sixel omit the graphics payloads so panes continue to render as text without escape-sequence corruption.

Capability detection is automatic for known Sixel-capable terminals, including Windows Terminal. You can override detection with WTMUX_SIXEL=1 to force Sixel on or WTMUX_SIXEL=0 to force it off before launching or attaching a client.

Examples:

# Detect whether you're inside wtmux (PowerShell)
if ($env:WTMUX) { "inside wtmux" } else { "not in wtmux" }

:: Refuse to nest a wtmux session inside another (cmd)
if defined WTMUX ( echo Already inside wtmux & exit /b 1 )

Setting Options at Runtime

Use set-option to change an option while the server is running. This is most useful for pushing dynamic content into the status bar from a shell prompt — for example showing git status, build state, or the current kube-context:

wtmux set-option [-g|-t target] [-u] <option> [<value>...]

Without -g, set-option applies to the current session (when run inside a pane with WTMUX) or to the session named by -t <target>. The -g flag sets the server-wide default used by sessions without an override. -u clears a session override so it falls back to the global value.

Session scoping is available for options the server resolves while rendering or creating panes, including status-*, window-status-*, set-titles*, base-index, pane-base-index, monitor-*, alert action/visual options, default-command, default-terminal, automatic-rename, remain-on-exit, history-limit, display-time, and destroy-unattached. synchronize-panes is window-scoped: without -g, set-window-option changes the active or -t targeted window; with -g, it sets the default for newly created windows. Client-resolved or server startup options such as prefix, mouse, key bindings, set-clipboard, default-shell, default-shell-args, clock-mode-style, and clock-mode-colour are global-only and must use -g at runtime.

For example, a PowerShell prompt can update only its own session's status-right on each prompt:

function prompt {
    # Compute your own status text (git branch, dirty state, etc.)
    $status = & pwsh -NoProfile -File "$HOME\scripts\git-status.ps1" $PWD.Path
    if ($env:WTMUX) { wtmux set-option status-right " $status " | Out-Null }
    "PS $($PWD.Path)> "
}

A detached hook can target a known session explicitly:

wtmux set-option -t work status-right " build: green "
wtmux set-option -t work status-position top
wtmux set-option -t work -u status-position

Use show-option (alias show) to query a single option, or omit the option name to list every option as option-name value lines. Use -g to query the global defaults; without -g, wtmux shows the current session's effective value when run inside a pane and falls back to global values outside a session. show-options is the plural form and also lists options.

wtmux show-option [-g] [option]
wtmux show-options [-g]
wtmux show-option -g status-right

Unknown option names are reported as errors on stderr and return a non-zero exit code instead of printing help text.

Use source-file (alias source) or reload-config (alias reload) to re-read configuration without restarting the server:

wtmux source-file [path]
wtmux reload-config

From the command prompt, run source-file [path] or reload. With a path, source-file reloads that file in both the server and attached clients; relative paths resolve against the server process's working directory. Without a path, reload re-reads ~/.wtmux.conf or ~/.tmux.conf in each process. Prefix-key, key binding, mouse, and status changes take effect live. Session-scoped options captured when panes are created, such as history-limit, default-command, and default-terminal, apply to newly created panes in that session; global-only startup options such as default-shell apply to newly created sessions.

Command Prompt

Press Ctrl+B then : to open a command prompt in the status bar. Type a wtmux/tmux command and press Enter to run it, or press Esc to cancel.

The prompt uses the same command parser as configuration files and runtime CLI commands, so commands such as split-window -h, new-window build, rename-window "build logs", set-option status-right " main ", bind, unbind, and send-keys work while attached to a session.

Command lines may contain multiple commands separated by top-level semicolons:

split-window -h; new-window build; display-message "ready"

Use \; for a literal semicolon. Semicolons inside quotes or inside #{...} format expressions do not split the command sequence.

confirm-before [-p prompt] <command> asks the attached client for y/n confirmation before running the command. Press y to run it; press n, Esc, or any other key to cancel. The default prefix x binding uses confirm-before -p "kill-pane? (y/n)" kill-pane before closing a pane.

Command aliases let short command names expand before dispatch. wtmux includes these tmux-compatible aliases when the target command is supported: neww → new-window, splitw → split-window, killp → kill-pane, selectp → select-pane, resizep → resize-pane, displayp → display-panes, selectl → select-layout, and nextl → next-layout. Add or override aliases with set -g command-alias name=command, for example:

set -g command-alias sp=split-window -h
sp; neww build

Sending Keys (Scripting)

Use send-keys to programmatically send input to a pane. This is the foundation for automating and scripting sessions (equivalent to tmux's send-keys).

wtmux send-keys [-t target] [-l] <keys...>
  • -t <target> selects the target pane. The target may be a session name or numeric id (keys go to that session's active pane), or a pane id in %N form (see the WTMUX_PANE environment variable). When omitted, the most recently created session's active pane is used.
  • -l sends every token literally, disabling key-name lookup.

Each argument is either a literal string or a named key. Arguments are sent with no separators between them, so spaces must be quoted into a single argument.

# Type a command into the "work" session and run it
wtmux send-keys -t work "echo hello" Enter

# Send Ctrl+C to interrupt the running program in a specific pane
wtmux send-keys -t %3 C-c

# Send the literal text "Enter" instead of the Enter key
wtmux send-keys -t work -l Enter

Recognized key names include Enter, Tab, Space, Escape, BSpace, the arrow keys (Up, Down, Left, Right), Home, End, PageUp, PageDown, Insert, Delete, and F1–F12. Modifiers use C- for Ctrl (e.g. C-c) and M- for Alt/Meta (e.g. M-x).