Tab Presentations
Tab presentation plugins
BMUX ships two independent tab presentation plugins for normal bmux attach:
- bmux.tab_bar is enabled by default and owns the full horizontal status/tab row at the bottom.
- bmux.sidebar is bundled but opt-in and reserves a bounded vertical region at the left or right.
Both consume the authoritative ordered tab state from bmux.tabs; presentation enablement does not change tab lifecycle or ordering.
Enablement combinations
The default is the full tab/status bar without the sidebar.
# Enable the optional sidebar as well
[plugins]
enabled = ["bmux.sidebar"]
# Sidebar only
[plugins]
enabled = ["bmux.sidebar"]
disabled = ["bmux.tab_bar"]
# Neither presentation; baseline attach remains available
[plugins]
disabled = ["bmux.tab_bar", "bmux.sidebar"]
Full tab/status bar
[plugins.settings."bmux.tab_bar"]
placement = "bottom" # "top" or "bottom"
# height = 1 # legacy fixed-height single-row mode
order = 100 # lower layout order allocates first
preset = "tab_rail" # "minimal" or "classic"
tab_label_max_width = "unlimited" # default; or 1..=65535 terminal cells
tab_template = "{name}"
show_session_name = false
show_context_name = false
show_mode = true
show_role = true
show_follow = true
show_hint = true
hover_highlight = true
hint_policy = "scroll_only" # "always" or "never"
[plugins.settings."bmux.tab_bar".layout]
wrap = true
min_rows = 1
max_rows = 3
density = "cozy" # or "compact"
left_padding = 1
right_padding = 1
tab_gap = 1
module_gap = 1
overflow_style = "arrows" # or "count"
align_active = "keep_visible" # or "focus_bias"
[plugins.settings."bmux.tab_bar".style]
separator_set = "angled_segments" # "plain" or "ascii"
prefer_unicode = true
force_ascii = false
dim_inactive = true
bold_active = true
underline_active = false
# Status items contributed by other plugins (bmux.tab_bar status-items service)
[plugins.settings."bmux.tab_bar".status_items]
show_external = true
max_items = 6 # 0..=32; highest priority first
max_item_width = 32 # 1..=128 terminal cells per item
# Toasts raised by plugins (bmux.tab_bar notifications service)
[plugins.settings."bmux.tab_bar".notifications]
enabled = true
max_visible = 3 # 1..=8
width = 44 # 16..=120 terminal cells
Tabs wrap between labels in authoritative order, left-to-right then top-to-bottom, for either placement. The bar grows and shrinks from layout.min_rows to layout.max_rows (defaults 1 and 3; valid range 1 <= min_rows <= max_rows <= 16). Workspace and status modules appear only on the first row. Oversized labels clip to one row; overflow navigation remains available at the ceiling and selection reveals the active tab. Terminal allocation can reduce the visible row count. Set layout.wrap = false for one row. An explicit legacy height retains its fixed-height, single-text-row behavior; combining it with wrap, min_rows, or max_rows is rejected. Remove height when migrating to adaptive rows.
The bar composes width-packed tabs with right-aligned mode, role, follow, and conditional hint/message modules. Optional session/context modules occupy the left side after tabs. Templates support {name}, {index}, {index0}, {session}, {marker}, {id}, and {active} with Unicode-cell-safe width limits and literal double braces. Tab names have no explicit width cap by default (or with tab_label_max_width = "unlimited"); the strip still clips to available terminal space. Set a positive integer such as 300 to cap names in terminal cells.
Optional color keys under [plugins.settings."bmux.tab_bar".colors] cover the bar, active/inactive/hover tabs, modules, and overflow using #RRGGBB values. Use tab_template, tab_label_max_width, max_tabs, show_tab_index, and show_facts; former aliases are rejected with an explicit error.
Interactions include click switching, hover, drag reorder, wheel navigation, middle-click inline rename, and a right-click Switch/Rename/Close menu. Domain mutations use generated bmux.tabs service clients.
Other plugins, including dynamically loaded native plugins, can add right-side status modules and raise toasts through the typed bmux.tab_bar services in bmux_tab_bar_plugin_api. Contributed items render to the left of the built-in modules in priority order, use the module colors (tinted by severity), take at most half the bar, and drop lowest-priority-first when space runs out. See plugins/tab-bar-plugin/README.md#plugin-contributions for the API.
Sidebar
[plugins.settings."bmux.sidebar"]
placement = "left" # "left" or "right"
width = 28
minimum_width = 16
maximum_width = 60
order = 200
show_index = true
heading = "Tabs"
title_template = "{marker} {index}{name}"
description_template = ""
status_template = ""
maximum_visible_items = 20
content_height = false
collapse_below_width = 80
collapsed_width = 8
Sidebar templates support {marker}, {index}, {name}, {id}, {active}, {fact}, {fact_detail}, and {fact_icon}. The generic layout resolver composes it with the bar when enabled.
Legacy configuration
Legacy appearance.status_position and [status_bar] are rejected with migration diagnostics. Move those values into plugins.settings."bmux.tab_bar" using the equivalent fields above.