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 an interactive menu or popup on the invoking attached client
wtmux display-menu -T Actions Split s "split-window -h"
wtmux display-popup -E -w 100 -h 30 pwsh

# 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"

Interactive startup uses the host title wtmux even before the server connects. The default set-titles off keeps that friendly title while attached; enable set-titles to use a dynamic session/window title. On exit, wtmux restores the title captured before startup when the host exposes it. One-shot commands do not change the title. See Terminal title for configuration and host restoration limits.

When several terminals attach to the same session, the shared pane layout uses the smallest attached width and height. Larger terminals show unused space to the right or below the panes; each terminal keeps its own correctly positioned status line. Attaching, resizing, switching sessions, or detaching recalculates the available area. Resizing is detected while input is idle; no key press or focus change is needed. A linked window also fits the terminals attached to every owning session, accounting for each owner's status-line reservation. Connections without a reported terminal size do not constrain the layout. There is no larger-canvas viewport or configurable window-size policy.

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.

Terminal input modes

wtmux also models application keypad, bracketed-paste, and focus-reporting modes per pane. The active pane's requested keypad and paste modes are mirrored to the host terminal only while normal pane input is active; copy mode, choosers, menus, popups, clocks, and command/confirmation prompts temporarily restore safe numeric-keypad and non-bracketed-paste modes. Focus reporting remains enabled while those interfaces are open so real host focus changes are still observed, but focus is reported to a pane only while it owns normal input.

A native host paste uses the standard xterm bracketed-paste protocol: the host terminal wraps pasted text in the CSI 200~ (begin) and CSI 201~ (end) control sequences so wtmux can tell a paste apart from typed input. wtmux pins the paste to the pane and pane-process generation that was active when CSI 200~ arrived. Its contents bypass prefix, root, custom-table, mouse, and prompt handling and stream to that pane until CSI 201~. wtmux aborts after 10 MiB, 30 seconds, pane close, or pane respawn; it discards through the matching host delimiter rather than redirecting the remainder to a newly active pane.

paste-buffer, the buffer chooser, and right-click paste add bracketed-paste delimiters when the target pane requested DEC private mode 2004 (bracketed paste). Ordinary typing, send-keys, and pipe-pane -I retain their existing behavior.

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.

Press Esc or q to leave copy mode without copying. Subsequent ordinary input is preserved even when it arrives in the same input batch as the exit key. Escape disambiguation does not require another key to finish; the separately bounded ambiguity for an active host color response still applies. An unsupported complete terminal key such as Delete or F1 cancels copy mode through the Escape fallback, consuming that key's whole CSI/SS3 sequence without typing its encoding into the pane. Ordinary input following the key is still preserved.

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. When the pane requests bracketed paste, wtmux wraps it with CSI 200~ and CSI 201~; send-keys is unchanged.

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)
wtmux 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
wtmux display-popup
wtmux display-popup -E -w 100 -h 30 pwsh

# Outside a wtmux pane, explicitly target a session, window, or pane
wtmux display-popup -t work:1
wtmux display-menu -t %7 Split s "split-window -h"
  • 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] [-t target] <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] [-t target] [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.

Standalone overlay commands use the same command tokenizer, alias expansion, option parser, and runtime dispatcher as config commands, key bindings, the command prompt, plugins, and control-mode requests. When run inside a pane, wtmux validates the WTMUX pipe, server process, and session identity together with WTMUX_PANE, then routes the overlay to the one focused attached client displaying that pane. Focus identity is tracked even when a pane is linked into another session and retains its original WTMUX value. If multiple owner clients remain and focus does not identify exactly one, wtmux returns an error instead of choosing another terminal.

Outside a pane, -t is required and accepts the existing session/window/pane target grammar: a session name or index, session:window, or %pane-id. The resolved target must have exactly one eligible attached client, or exactly one focused client when several clients share it. Missing, malformed, stale, or ambiguous context, malformed menu triples, invalid options or targets, transport failure, and a response timeout all return a nonzero exit code. These commands connect only to an existing server; they do not start a server merely to request an overlay. A %pane-id belonging to a window linked into multiple sessions is evaluated across every owner session and succeeds only when exactly one eligible attached client remains globally; session/window targets retain their specific owner context.

The -t/--target option is currently specific to standalone wtmux display-menu and wtmux display-popup invocation. Config commands, key bindings, the attached command prompt, plugins, and control-mode requests return an explicit error if they supply it rather than accepting and ignoring a target.

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. Standalone client-owned commands validate all three fields against the connected server.
WTMUX_PANE Identifies the current pane, formatted as %<pane-id>; validated together with WTMUX before targeting an attached client.

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.

Clipboard Integration (OSC 52)

Pane applications can write or clear the Windows clipboard with OSC 52:

ESC ] 52 ; Pc ; Pd BEL

Set allow-application-clipboard on to explicitly trust eligible active-pane applications with clipboard writes while using the default set-clipboard external. The opt-in defaults to off, so application-owned copying (for example a mouse selection in Copilot CLI) is blocked until authorized. It trusts applications to replace or clear your clipboard, not just individual gestures:

wtmux set-option -g allow-application-clipboard on

The setting is global and applies to existing panes immediately. Turning it off or removing it from a reloaded config revokes the opt-in and clears outstanding requests when the effective policy no longer authorizes them. set-clipboard on already authorizes eligible pane writes independently of the opt-in. set-clipboard off always rejects all clipboard writes, regardless of the opt-in. wtmux's own copy-mode/paste-buffer writes continue to work under external and on; under off they only update internal paste buffers. Right-click clipboard reads/paste are unchanged (see set-clipboard). Clipboard queries (Pd of ?) are never answered — wtmux does not implement clipboard readback.

wtmux accepts a request only from the active pane of the active window, and only when the owning session has at least one eligible attached client; background panes, background windows, and detached sessions are dropped. Pc selects targets from xterm's c/p/q/s/0-7 list — an empty list or any list containing c maps to the single Windows clipboard (duplicate c entries still write once); a valid list without c is recognized but ignored; an unknown target character rejects the whole request. Pd is standard Base64 (RFC 4648, no whitespace or URL-safe characters, exact padding) decoded as strict UTF-8, up to 1 MiB; an empty Pd clears the clipboard. Malformed, oversized, unauthorized, background, and query requests are dropped silently: no client message is sent and no diagnostic is shown.

Exactly one write or clear is delivered to the longest-attached eligible client for the owning session through a bounded, acknowledged per-client queue (osc52-queue-limit, default 4, range 1-64). Only one request per client is ever in flight, bounded by a two-second acknowledgment timeout; a full queue drops the oldest undelivered request to admit the newest, and wtmux never fails a dropped request over to another client. An unsent request that expires or an acknowledgment timeout is not retried or treated as a reason to detach. If cancellation interrupts an actual IPC write, however, the connection closes to prevent subsequent messages from following a partially delivered frame. A full queue, a clipboard write/clear failure, and a write/acknowledgment timeout each show a brief, payload-free status message, rate-limited to at most one per client per minute so a misbehaving pane cannot spam the status bar.

Pane applications can mark clickable text with OSC 8:

ESC ] 8 ; params ; URI BEL-or-ST   text   ESC ] 8 ; ; BEL-or-ST

wtmux never forwards this sequence to the host terminal as-is. The server parses bounded opens/closes into per-cell metadata (a compact reference into a per-pane registry, not the URI text itself), then regenerates canonical, ST-terminated OSC 8 only around the visible linked runs in the composed frame — closing before borders, the status line, overlays, other panes, and the end of the frame. The attached client independently re-parses and revalidates every hyperlink the server sends before writing it to the host, so a compromised or outdated server frame cannot bypass scheme, parameter, length, or terminator checks.

Two global options control what gets modeled:

set -g hyperlink-schemes http,https   # default; empty disables all modeled links
set -g hyperlink-parameters id        # default; empty strips all parameters

hyperlink-schemes is a comma-separated allowlist of absolute URI schemes (RFC URI-scheme syntax); configuring file explicitly allows syntactically valid absolute URIs with an explicit file: scheme, including UNC/remote-host forms. wtmux validates only OSC 8 syntax and the configured allowlist; the host terminal decides whether a user click opens or executes the target. hyperlink-parameters is a comma-separated allowlist of OSC 8 parameter names to preserve; parameters outside the allowlist are dropped, while malformed parameter syntax rejects the link. Both options are global only (see Configuration Options) — the server's parser and every attached client's independent sanitizer always validate against the same policy, so session-level set-option attempts are rejected rather than stored and ignored. A global runtime change takes effect immediately without discarding already-stored link metadata: a link that becomes disallowed renders as plain text until policy allows it again.

Each pane retains up to 1,024 live hyperlink definitions, reclaiming entries no longer referenced by any visible, scrollback, or alternate-screen cell before rejecting a new one. An open without an explicit id always creates a new logical link (matching multiplexer convention); an open with the same non-empty id and URI in one pane reuses one logical link so wrapped or repeated occurrences group together on hover. When wtmux emits a link, it always replaces the id with a bounded, wtmux-generated value that namespaces the pane and link identity, so two different panes can never collide even if their content is identical.

Copy-mode selection, paste-buffer text, and ordinary capture-pane output contain visible text only — links are never exposed as text. capture-pane -e additionally emits canonical OSC 8 open/close pairs around approved linked runs alongside its existing SGR output, re-applying the current hyperlink-schemes/hyperlink-parameters policy at capture time.

display-popup panes are ordinary panes: OSC 8 inside a popup is modeled and rendered exactly like any other pane's, namespaced to the popup's own pane identity and clipped to the popup's interior.

Non-interactive CLI commands that can echo pane-derived text to your real console — wtmux capture-pane -e, wtmux show-buffer, and wtmux save-buffer - — independently re-validate and canonicalize it the same way an attached client does before writing anything, so a compromised or outdated server can never inject raw OSC 8 or other terminal control sequences through these commands either. wtmux save-buffer <file> (a real file destination, not the console) writes the exact buffer bytes unmodified.

wtmux never auto-opens, prefetches, resolves, or logs a URI; clicking remains entirely controlled by the host terminal under its own user-gesture policy.

Terminal Colors

The included official stable Microsoft ConPTY runtime preserves these operations between pane applications and wtmux on every supported Windows version; no outer-terminal palette passthrough is enabled.

Pane applications can set, query, and reset xterm colors without changing another pane or the host's palette. OSC 4 supports palette indexes 0-255 and multiple index/specification pairs; OSC 104 resets all entries, or the listed indexes. OSC 10-19 supports successive specifications and queries, and OSC 110-119 resets the corresponding dynamic role. BEL and ST terminators are accepted.

Specifications accept rgb: with 1-4 hexadecimal digits per component, the X11 #RGB/#RRGGBB/#RRRGGGBBB/#RRRRGGGGBBBB forms, and the complete pinned X.Org named-color table. Names ignore case and whitespace. rgb: scales to 16 bits; legacy # values occupy the high bits without repeating the low bits. Responses always use lowercase rgb:rrrr/gggg/bbbb. rgbi: is not supported.

Palette overrides and OSC 10/11 default foreground/background overrides recolor existing pane cells, scrollback, and escape-sequence captures. Reset returns cells to host-native indexed/default colors. OSC 12 changes the cursor only while the pane is active; each client restores its own original cursor on switching, reset, and detach. A client first queries its original cursor. If this query cannot return RGB, times out, or is skipped (including during paste or overload), cursor overrides remain modeled but are not applied for that client attachment. This also applies to Windows Terminal: resetting the theme cannot restore an unknown cursor color previously selected by another application. OSC 13-19 are stored/queryable only (mouse, Tektronix, and highlight roles). Pane color changes never recolor borders, status UI, menus, clocks, or another pane; a popup terminal has its own isolated cell colors.

An overridden color answers locally. Otherwise, wtmux asks every attached rendering terminal belonging to any session that owns the pane's window. Each color independently uses unanimous exact RGB responses, or a canonical xterm fallback when any terminal disagrees, cannot answer, disconnects, or misses the deadline. With no terminals, fallback is immediate. Queries do not change rendering or install overrides.

The fallback palette uses stock xterm's sixteen ANSI colors, the 6x6x6 RGB cube, and the 24-level gray ramp. Dynamic fallbacks use stock, non-reverse-video xterm resources: black for OSC 10, 12, 13, 15, 17, 18; white for OSC 11, 14, 16, 19. These are deterministic answers, not an assumption about your terminal theme. See the xterm resource reference and color controls.

color-query-timeout defaults to 250 milliseconds (0-5000, global or session); zero disables host queries. Linked windows use the minimum effective timeout across all owning sessions, including owners without clients; any zero bypasses host queries. The timeout is snapshotted for each batch. Queries and replies are bounded. Identical pending items share a physical host query, and completed/timed-out items have a one-second quarantine: queries during quarantine fall back rather than risk attributing an old response to a new request. Expected late replies are consumed during that interval; unrelated keyboard, mouse, and bracketed-paste input is preserved. Hosts must not interleave response bytes with keystrokes/paste, or deliver replies after quarantine: OSC has no request identifiers and cannot distinguish such input from a new response. Unsolicited OSC input is not intercepted. An ambiguous standalone Escape/partial OSC introducer can wait up to two seconds; completing an unrelated key sequence releases it unchanged. A captured response is never replayed into pane input. Unrelated controls (including interrupt and detach) or new Escape sequences interrupt an incomplete response, and a two-second absolute lifetime prevents an unterminated response from swallowing input indefinitely. Prefixes are pinned from their first Escape byte: a response that began before a new query cannot complete that query, even across quarantine, provided it finishes within that partial-response lifetime. Fragments arriving after this bound cannot be distinguished from ordinary input.

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, color-query-timeout, 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, allow-application-clipboard, osc52-queue-limit, 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).