Configuration
bmux is configured via a bmux.toml file. If no config file exists, bmux uses sensible defaults for all options.
Config File Location
bmux looks for bmux.toml in the standard XDG config directory:
~/.config/bmux/bmux.toml
[general]
Core session defaults: shell, scrollback depth, and server connection settings
| Option | Type | Default | Description |
| default_mode | string (normal, insert, visual, command) | NORMAL | Default interaction mode when starting bmux |
| mouse_support | bool | true | Enable mouse support for clicking to focus panes, scrolling through output, and dragging to resize pane borders |
| default_shell | string (optional) | — | Default shell to launch in new panes. When unset, uses the SHELL environment variable or falls back to /bin/sh. |
| scrollback_limit | integer | 10000 | Maximum number of scrollback lines retained per pane. Must be at least 1. |
| server_timeout | integer | 5000 | Server socket timeout in milliseconds. Must be at least 1. |
[appearance]
Visual styling: color theme, pane borders, status bar placement, and window titles
| Option | Type | Default | Description |
| theme | string | (empty) | Name of the color theme to apply. Empty string uses the default theme. |
| status_position | string (TOP, BOTTOM, OFF) | BOTTOM | Where to render the status bar. TOP places it above panes, BOTTOM below panes, and OFF hides it entirely. |
| pane_border_style | string (SINGLE, DOUBLE, ROUNDED, THICK, NONE) | SINGLE | Drawing style for pane borders. NONE hides borders entirely, giving panes the full terminal width. |
| show_pane_titles | bool | false | Display a title label in each pane’s border showing the running process name |
| window_title_format | string | (empty) | Format string for the outer terminal’s title bar. Empty string leaves the title unset. |
[behavior]
Runtime behavior toggles for terminal protocol handling, layout persistence, and build compatibility
| Option | Type | Default | Description |
| aggressive_resize | bool | false | Immediately resize panes to the largest remaining client when a client disconnects, rather than keeping the previous dimensions |
| visual_activity | bool | false | Highlight panes in the status bar when they produce output while unfocused, so you can tell which panes have new activity |
| bell_action | string (NONE, ANY, CURRENT, OTHER) | ANY | How to handle terminal bell signals from panes. NONE ignores bells entirely. ANY notifies on bells from any pane. CURRENT only notifies from the focused pane. OTHER only notifies from unfocused panes. |
| automatic_rename | bool | false | Automatically rename windows based on the currently running command in the focused pane |
| exit_empty | bool | false | Exit bmux when no sessions remain |
| restore_last_layout | bool | true | Restore and persist the last local CLI runtime layout across sessions, so reattaching resumes where you left off |
| confirm_quit_destroy | bool | true | Prompt for confirmation before a destructive quit that clears persisted local runtime state |
| pane_term | string | bmux-256color | Terminal type exposed to pane processes via the TERM environment variable. Common values: bmux-256color, xterm-256color, screen-256color. |
| protocol_trace_enabled | bool | false | Enable protocol query/reply tracing in the runtime. Useful for debugging terminal protocol behavior with CSI/OSC/DCS sequences. |
| protocol_trace_capacity | integer | 200 | Maximum number of in-memory protocol trace events to retain. Must be at least 1. |
| terminfo_auto_install | string (ask, always, never) | never | What to do when the bmux terminfo entry is missing from the system. ask prompts before installing. always installs silently. never skips installation, which may degrade terminal rendering. |
| terminfo_prompt_cooldown_days | integer | 7 | Number of days to wait before prompting again after the user declines terminfo installation |
| stale_build_action | string (error, warn) | error | What to do when the running server was built from a different version than the current CLI binary. error refuses to connect until the server is restarted. warn connects with a warning message. |
| kitty_keyboard | bool | true | Enable the Kitty keyboard protocol for enhanced key reporting. When true, bmux negotiates enhanced keyboard mode with the outer terminal, allowing modified special keys like Ctrl+Enter to be correctly forwarded to pane programs. |
[multi_client]
Settings for multiple clients attached to the same session, controlling independent views and mode synchronization
| Option | Type | Default | Description |
| allow_independent_views | bool | false | Allow clients to have independent views of the same session, with separate focused panes and scroll positions |
| default_follow_mode | bool | false | When true, new clients automatically track the leader client’s focused pane and scroll position. When false, clients start with an independent view. |
| max_clients_per_session | integer | 0 | Maximum number of clients that can attach to a single session. Set to 0 for unlimited. |
| sync_client_modes | bool | false | When true, switching interaction modes (e.g. Normal to Insert) on one client applies to all attached clients in the same session |
[keybindings]
Keyboard shortcuts organized by scope. Prefix-chord bindings (runtime) require pressing the prefix key first. Modal bindings (normal, insert, visual, command) are active only in their respective interaction modes.
| Option | Type | Default | Description |
| prefix | string | ctrl+a | Prefix key for runtime key chords (e.g. “ctrl+a”). All runtime bindings require pressing this key first. |
| timeout_ms | integer (optional) | — | Exact timeout in milliseconds for multi-stroke chord resolution. Takes precedence over timeout_profile. Valid range: 50-5000. |
| timeout_profile | string (optional) | — | Named timeout profile for multi-stroke chord resolution. Built-in profiles: fast (200ms), traditional (400ms), slow (800ms). Ignored when timeout_ms is set. |
| timeout_profiles | table | (empty) | Override values for built-in timeout profiles or define custom ones. Keys are profile names, values are timeout in milliseconds. |
| runtime | table | (see defaults below) | Key bindings triggered after pressing the prefix key. Maps key chords to runtime action names. |
| global | table | (empty) | Key bindings that trigger without the prefix key. Use sparingly to avoid conflicts with pane input. |
| scroll | table | (see defaults below) | Key bindings active in scrollback/copy mode. No prefix required unless the chord explicitly includes it. |
| normal | table | (see defaults below) | Key bindings for Normal mode, the default mode for navigation and pane management. Keystrokes are intercepted by bmux, not forwarded to the pane. |
| insert | table | (see defaults below) | Key bindings for Insert mode, where keystrokes are forwarded directly to the focused pane process. Typically only Escape is bound to return to Normal mode. |
| visual | table | (see defaults below) | Key bindings for Visual mode, used for text selection and copy operations in scrollback |
| command | table | (see defaults below) | Key bindings for Command mode, the : command-line for executing runtime commands by name |
Default runtime bindings
[keybindings.runtime]
'"' = "split_focused_horizontal"
"%" = "split_focused_vertical"
"?" = "show_help"
"[" = "enter_scroll_mode"
"]" = "exit_scroll_mode"
arrow_down = "focus_down_pane"
arrow_left = "focus_left_pane"
arrow_right = "focus_right_pane"
arrow_up = "focus_up_pane"
"ctrl+e" = "scroll_down_line"
"ctrl+y" = "scroll_up_line"
d = "detach"
g = "scroll_top"
h = "focus_left_pane"
j = "focus_down_pane"
k = "focus_up_pane"
l = "focus_right_pane"
minus = "decrease_split"
o = "focus_next_pane"
page_down = "scroll_down_page"
page_up = "scroll_up_page"
plus = "increase_split"
q = "quit"
r = "restart_focused_pane"
"shift+arrow_down" = "resize_down"
"shift+arrow_left" = "resize_left"
"shift+arrow_right" = "resize_right"
"shift+arrow_up" = "resize_up"
"shift+c" = "new_session"
"shift+g" = "scroll_bottom"
"shift+h" = "resize_left"
"shift+j" = "resize_down"
"shift+k" = "resize_up"
"shift+l" = "resize_right"
t = "toggle_split_direction"
v = "begin_selection"
x = "close_focused_pane"
Default scroll bindings
[keybindings.scroll]
arrow_down = "move_cursor_down"
arrow_left = "move_cursor_left"
arrow_right = "move_cursor_right"
arrow_up = "move_cursor_up"
"ctrl+a ]" = "exit_scroll_mode"
"ctrl+e" = "scroll_down_line"
"ctrl+y" = "scroll_up_line"
enter = "confirm_scrollback"
escape = "exit_scroll_mode"
g = "scroll_top"
h = "move_cursor_left"
j = "move_cursor_down"
k = "move_cursor_up"
l = "move_cursor_right"
page_down = "scroll_down_page"
page_up = "scroll_up_page"
"shift+g" = "scroll_bottom"
v = "begin_selection"
Default normal bindings
[keybindings.normal]
'"' = "split-horizontal"
"%" = "split-vertical"
"&" = "kill-window"
"/" = "search"
":" = "enter-command-mode"
"?" = "show-help"
H = "resize-pane-left"
J = "resize-pane-down"
K = "resize-pane-up"
L = "resize-pane-right"
c = "new-window"
d = "detach"
f = "fuzzy-find"
h = "move-pane-left"
i = "enter-insert-mode"
j = "move-pane-down"
k = "move-pane-up"
l = "move-pane-right"
n = "next-window"
p = "prev-window"
r = "refresh"
v = "enter-visual-mode"
x = "kill-pane"
z = "zoom-pane"
Default insert bindings
[keybindings.insert]
Esc = "enter-normal-mode"
Default visual bindings
[keybindings.visual]
":" = "enter-command-mode"
Esc = "enter-normal-mode"
d = "cut-selection"
h = "move-left"
j = "move-down"
k = "move-up"
l = "move-right"
y = "copy-selection"
Default command bindings
[keybindings.command]
Backspace = "backspace"
C-u = "clear-line"
C-w = "delete-word"
Enter = "execute-command"
Esc = "enter-normal-mode"
[plugins]
Plugin discovery, enablement, and per-plugin settings. Bundled plugins (like bmux.windows and bmux.permissions) are enabled by default.
| Option | Type | Default | Description |
| enabled | list of strings | (empty) | Plugin IDs to enable in addition to the bundled defaults. Bundled plugins like bmux.windows and bmux.permissions are enabled automatically without being listed here. |
| disabled | list of strings | (empty) | Plugin IDs to explicitly disable, including bundled ones. Overrides both bundled defaults and the enabled list. |
| search_paths | list of paths | (empty) | Additional directories to scan for plugin binaries beyond the default plugin search path |
| settings | table | (empty) | Per-plugin settings keyed by plugin ID. Each plugin defines its own accepted keys and values. |
[status_bar]
Content and layout of the status bar displayed at the top or bottom of the terminal
| Option | Type | Default | Description |
| left | string | (empty) | Format string for the left side of the status bar. Empty string disables the left section. |
| right | string | (empty) | Format string for the right side of the status bar. Empty string disables the right section. |
| update_interval | integer | 0 | How often to refresh the status bar content, in seconds |
| show_session_name | bool | false | Display the active session name in the status bar |
| show_window_list | bool | false | Display the list of open panes in the status bar |
| show_mode | bool | false | Display the current interaction mode (Normal, Insert, etc.) in the status bar |
[recording]
Session recording for terminal replay, debugging, and playbook generation. Records pane I/O and lifecycle events to disk.
| Option | Type | Default | Description |
| dir | path (optional) | — | Root directory for recording data. Relative paths are resolved against the directory containing bmux.toml. |
| enabled | bool | true | Enable the recording subsystem. When false, no recording data is captured or written to disk regardless of other recording settings. |
| capture_input | bool | true | Capture pane input bytes (keystrokes sent to pane processes) |
| capture_output | bool | true | Capture pane output bytes (terminal output from pane processes) |
| capture_events | bool | true | Capture lifecycle and server events (pane creation, resize, close, etc.) |
| segment_mb | integer | 64 | Rotate recording segments at approximately this size in MB |
| retention_days | integer | 30 | Retention period for completed recordings in days. Set to 0 to disable automatic pruning and keep recordings indefinitely. |