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 terminal title from set-titles-string while attached (restoring the original title on detach).	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.

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
set-clipboard	on, off, or external (true/1 also on; false/0 also off)	external	Controls whether copy-mode yanks write to the Windows clipboard. off only updates wtmux paste buffers; on and external both use the Windows clipboard path because wtmux strips OSC 52 from server frames.	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).