Configuration Options
The tables below list every option accepted by set, set-option, setw, and set-window-option. Option names are case-sensitive and aliases are listed separately because the parser accepts each token. Runtime set-option uses the same option parser. A "Global or session" entry means set-option <option> <value> creates an override for the current session, set-option -t <target> <option> <value> targets another session by name or ID, set-option -u <option> clears the session override, and set-option -g <option> <value> updates the global fallback. A "Global only" entry must use -g at runtime because the option is resolved by the client or by server-wide startup state and cannot be represented as a per-session server override.
Boolean options enable on on, true, or 1; any other value disables them unless noted.
Prefix and keys
| Option | Accepted value(s) | Default | Description | Runtime set-option |
|---|---|---|---|---|
prefix |
Key name such as C-a through C-z |
C-b |
Sets the command prefix key. | Global only |
command-alias |
name=command |
Built-in tmux-compatible short aliases | Adds or overrides a command alias. The alias name is one token; the value may include command arguments, e.g. set -g command-alias sp=split-window -h. Repeating the option appends or overrides aliases. |
Global only |
Key bindings use the bind/bind-key and unbind/unbind-key directives, not set options. See Root key bindings, Custom key tables, and Mouse bindings. Command lines can contain top-level ; separators; use \; for a literal semicolon.
Shell and terminal
| Option | Accepted value(s) | Default | Description | Runtime set-option |
|---|---|---|---|---|
default-shell |
Command name or path token | System default shell | Sets the shell executable used when wtmux starts new sessions. | Global only |
default-shell-args |
String | Not set | Appends arguments to default-shell. |
Global only |
default-shell-arg |
String | Not set | Alias for default-shell-args. |
Global only |
default-command |
String | Not set | Overrides the command run in new panes/windows. wtmux passes the command string directly to ConPTY; when unset, panes use default-shell plus default-shell-args. Runtime changes apply to future panes/windows in sessions created with the default pane command; sessions created with an explicit command keep using that command. |
Global or session |
default-terminal |
String | Not set | Sets $TERM for panes created after the option is set; an explicit set-environment TERM ... override wins. |
Global or session |
set-titles |
on/off (true/1 also on) |
off |
When on, sets the host title from set-titles-string starting with the first screen update; when off, keeps the friendly wtmux title. Cleanup restores the pre-bootstrap console title when the host exposes it; see Terminal title. |
Global or session |
set-titles-string |
Format string | #S:#I:#W |
The host terminal title format when set-titles is on; expands the same variables as the status bar (#S, #I, #W, #P, #T, #H, etc.). |
Global or session |
Windows and panes
| Option | Accepted value(s) | Default | Description | Runtime set-option |
|---|---|---|---|---|
base-index |
Integer | 0 |
Sets the number of the first window; status formats, window switching, and new-window targets use this numbering. Runtime changes renumber existing windows. | Global or session |
pane-base-index |
Integer | 0 |
Sets the number of the first pane shown by #P and display-panes; runtime changes update display and picker numbering. |
Global or session |
automatic-rename |
on/off (true/1 also on) |
on |
Enables automatic window renaming from the active pane title for new sessions/windows. | Global or session |
remain-on-exit |
on/off (true/1 also on) |
off |
Keeps panes visible after their command exits, preserving final output with a [dead] marker until the pane is closed or respawned. |
Global or session |
synchronize-panes |
on/off (true/1 also on; empty or toggle toggles at runtime) |
off |
Duplicates typed input to every live pane in the target window. set -g sets the default for newly created windows; runtime set-window-option without -g changes the target window. |
Window (set-window-option) |
history-limit |
Integer | 10000 |
Sets scrollback rows for panes created after the option is applied. | Global or session |
Activity, bell, and silence monitoring
| Option | Accepted value(s) | Default | Description | Runtime set-option |
|---|---|---|---|---|
monitor-activity |
on/off (true/1 also on) |
off |
Flags background windows that receive output. | Global or session |
monitor-bell |
on/off (true/1 also on) |
off |
Flags windows whose output contains BEL (0x07). |
Global or session |
monitor-silence |
Integer seconds, on/true (30 seconds), or off/false/0 |
0 (off) |
Flags windows with no output for the configured interval. | Global or session |
activity-action |
any, none, current, or other |
other |
Selects which windows are eligible for activity alerts. | Global or session |
bell-action |
any, none, current, or other |
any |
Selects which windows may forward a host-terminal BEL and receive monitored bell alerts. | Global or session |
silence-action |
any, none, current, or other |
other |
Selects which windows are eligible for silence alerts. | Global or session |
visual-activity |
off, on, or both |
off |
Shows a transient status-line message for activity alerts when enabled. | Global or session |
visual-bell |
off, on, or both |
off |
off forwards the host-terminal BEL only; on uses the monitored transient visual alert only; both emits both. Enable monitor-bell for the visual alert/window flag. |
Global or session |
visual-silence |
off, on, or both |
off |
Shows a transient status-line message for silence alerts when enabled. | Global or session |
wtmux can flag windows in the status bar when something needs attention:
set -g monitor-activity on # mark background windows that receive output
set -g monitor-bell on # mark windows whose output contains BEL (0x07)
set -g monitor-silence 60 # mark windows with no output for 60 seconds; 0/off disables
Alert scope options control which windows are eligible to trigger an alert. activity-action current has no effect for activity monitoring because activity is only tracked for non-current windows.
Visual alert options control whether an alert also shows a transient status-line message for display-time milliseconds. Pane BEL events are forwarded to the host terminal by default when bell-action allows their window, so Windows Terminal can apply its configured sound/flash behavior. For visual-bell, off keeps the host BEL only, on suppresses it in favor of the monitored visual message, and both provides both. Enable monitor-bell to set the ! flag and show the visual message:
set -g visual-activity on
set -g visual-bell both
set -g visual-silence on
The default window-status formats include #F, so flags appear automatically. Activity (#) and bell (!) flags clear when you switch to the flagged window; silence (~) clears when that window produces output again.
Status bar
| Option | Accepted value(s) | Default | Description | Runtime set-option |
|---|---|---|---|---|
status |
on/off (true/1 also on) |
on |
Shows or hides the status bar; when hidden, panes use the reclaimed row. | Global or session |
status-position |
top or bottom |
bottom |
Places the status bar at the top or bottom of the terminal. | Global or session |
status-left |
Format string | [#S] |
Sets left status content before the window list. | Global or session |
status-right |
Format string | %H:%M |
Sets right-aligned status content. | Global or session |
status-style |
Style string with fg=<color> and/or bg=<color> |
Not set (inverse video) | Sets status foreground/background colors in one option. | Global or session |
status-fg |
Color | Not set | Sets the status foreground color. | Global or session |
status-foreground |
Color | Not set | Alias for status-fg. |
Global or session |
status-bg |
Color | Not set | Sets the status background color. | Global or session |
status-background |
Color | Not set | Alias for status-bg. |
Global or session |
status-interval |
Integer seconds | 15 |
Interval in seconds between periodic status-bar refreshes, including clocks and other time-based status-right content. The effective tick is at least 1 second and may be more frequent when monitor-silence is lower. |
Global or session |
window-status-current-format |
Format string | #I:#W#F |
Sets the active window entry format in the status bar. | Global or session |
window-status-format |
Format string | #I:#W#F |
Sets inactive window entry formats in the status bar. | Global or session |
#{prefix_highlight} is a format variable, not a set option; it renders the configured prefix key when the prefix is active.
Hyperlinks
| Option | Accepted value(s) | Default | Description | Runtime set-option |
|---|---|---|---|---|
hyperlink-schemes |
Comma-separated URI schemes (RFC URI-scheme syntax) | http,https |
Allowlist of OSC 8 hyperlink URI schemes that are modeled instead of dropped. Normalized to lowercase with duplicates removed; an empty value disables all modeled hyperlinks. Configuring file explicitly allows syntactically valid absolute URIs with an explicit file: scheme, including remote-host/UNC forms. wtmux validates only OSC 8 syntax and policy; whether a click opens or executes a target remains the host terminal's responsibility. |
Global only |
hyperlink-parameters |
Comma-separated parameter names | id |
Allowlist of OSC 8 parameter names preserved from an open; parameters outside the allowlist are dropped, while malformed parameter syntax rejects the link. Normalized to lowercase with duplicates removed; an empty value strips all parameters while retaining an allowed URI. | Global only |
wtmux models bounded OSC 8 hyperlinks as per-cell metadata rather than forwarding raw escape
sequences; see Hyperlinks (OSC 8) for the full behavior. Both
options are enforced server-wide only: the server's parser and every attached client's
independent sanitizer must validate against the same policy, so a session-level
set-option or set-option -t <target> attempt is rejected as global-only rather than
stored and ignored.
Mouse
| Option | Accepted value(s) | Default | Description | Runtime set-option |
|---|---|---|---|---|
mouse |
on/off (true/1 also on) |
off |
Enables mouse reporting, pane selection, border dragging, and scrollback mouse defaults. | Global only |
Environment
Environment is configured with directives rather than set options.
| Directive | Accepted value(s) | Default | Description | Runtime set-option |
|---|---|---|---|---|
set-environment / setenv |
[-g] NAME VALUE or [-g] -u NAME |
Inherited process environment | Sets or unsets variables passed to panes created after the change. | No; use set-environment |
show-environment / showenv |
[-g] |
Current environment map | Recognized by config parsing and the CLI for tmux compatibility. | No |
Miscellaneous
| Option | Accepted value(s) | Default | Description | Runtime set-option |
|---|---|---|---|---|
clock-mode-style |
12 or 24 |
24 |
Selects 12-hour or 24-hour display for clock-mode. |
Global only |
clock-mode-colour |
Color | green |
Sets the foreground color for the large digits in clock-mode. Accepts the same named, colourN/colorN, and numeric palette values as status colors. |
Global only |
display-time |
Integer milliseconds | 750 |
Sets how long temporary status messages are displayed. | Global or session |
color-query-timeout |
Integer milliseconds, 0-5000 |
250 |
Deadline for unanimous host answers to unmodified OSC 4/10-19 colors; 0 skips host queries and uses stock xterm response-only fallback. |
Global or session |
set-clipboard |
on, off, or external (true/1 also on; false/0 also off) |
external |
Controls the Windows clipboard for both wtmux copy-mode/paste-buffer writes and pane-originated OSC 52 requests. off disables all clipboard writes, even with allow-application-clipboard on (copy-mode only updates wtmux paste buffers). external allows copy-mode/paste-buffer writes and rejects pane OSC 52 unless allow-application-clipboard on is set. on already trusts eligible active-pane OSC 52 writes/clears regardless of the additional option. |
Global only |
allow-application-clipboard |
on/off, true/false, or 1/0 |
off |
Explicitly authorizes eligible active-pane OSC 52 writes/clears while set-clipboard external is used, including application-owned selection copying. This trusts pane applications, not only individual mouse gestures. It never overrides set-clipboard off, and is unnecessary with set-clipboard on. Existing bounds, capability and lifecycle checks still apply; clipboard readback remains unsupported. |
Global only |
osc52-queue-limit |
Integer, 1-64 |
4 |
Maximum queued (not yet delivered) pane-originated OSC 52 clipboard requests per attached client; applies independently to each client and does not affect wtmux copy-mode/paste-buffer writes. | Global only |
destroy-unattached |
on/off (true/1 also on) |
off |
Destroys a session once its last attached client detaches, switches away, or disconnects. | Global or session |
User options (@)
Options whose name begins with @ are user options: arbitrary named values that wtmux stores but does not otherwise interpret, following the tmux convention. Set them like any other option — set -g @my_theme dark in the config file or wtmux set-option -g @my_theme dark at runtime — and read them back with #{@my_theme} in any format string or with wtmux show-option -g @my_theme. wtmux show-options -g lists the user options that are set alongside the built-in options. User option names are case-sensitive, the value may contain spaces when quoted, and an unset @ variable expands to an empty string. They are primarily used to configure plugins (a plugin reads its own @ options through the host API — see Plugins).