# Tabs
par-term provides a multi-tab interface for managing multiple shells within a single window.
## Table of Contents
- [Overview](#overview)
- [Creating and Closing Tabs](#creating-and-closing-tabs)
- [Profile Selection on New Tab](#profile-selection-on-new-tab)
- [New Tab Position](#new-tab-position)
- [Reopening Closed Tabs](#reopening-closed-tabs)
- [Switching Tabs](#switching-tabs)
- [Reordering Tabs](#reordering-tabs)
- [Drag-and-Drop Reordering](#drag-and-drop-reordering)
- [Keyboard Reordering](#keyboard-reordering)
- [Duplicating Tabs](#duplicating-tabs)
- [Moving tabs between windows](#moving-tabs-between-windows)
- [Panes](#panes)
- [Promoting and Demoting Panes](#promoting-and-demoting-panes)
- [Selecting a Pane by Letter](#selecting-a-pane-by-letter)
- [Tab Icons](#tab-icons)
- [Tab Bar](#tab-bar)
- [Tab Bar Position](#tab-bar-position)
- [Visibility Modes](#visibility-modes)
- [Tab Style Variants](#tab-style-variants)
- [Tab Stretch](#tab-stretch)
- [HTML Titles](#html-titles)
- [Inactive Tab Outline-Only Mode](#inactive-tab-outline-only-mode)
- [Tab Title Mode](#tab-title-mode)
- [Per-Pane Title Tracking](#per-pane-title-tracking)
- [Remote Tab Title Format](#remote-tab-title-format)
- [Renaming Tabs](#renaming-tabs)
- [Restoring Tab Names and Colors](#restoring-tab-names-and-colors)
- [Tab Appearance](#tab-appearance)
- [Known Fixes](#known-fixes)
- [Configuration](#configuration)
- [Related Documentation](#related-documentation)
## Overview
The tab system manages multiple shells:
```mermaid
graph TD
TabManager[Tab Manager]
TabBar[Tab Bar UI]
Tabs[Terminal Tabs]
Sessions[Shells]
TabManager --> TabBar
TabManager --> Tabs
Tabs --> Sessions
TabBar --> Visibility[Visibility Mode]
TabBar --> Stretch[Tab Stretch]
TabBar --> Colors[Tab Colors]
TabBar --> Icons[Tab Icons]
TabBar --> HTML[HTML Titles]
class TabManager primary
class TabBar active
class Tabs data
class Sessions external
class Visibility,Stretch,Colors,Icons,HTML neutral
classDef primary fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
classDef active fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
classDef data fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
classDef external fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
classDef neutral fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
```
## Creating and Closing Tabs
| New tab | `Cmd+T` | `Ctrl+Shift+T` |
| Close (pane, then tab, then window) | `Cmd+W` | `Ctrl+Shift+W` |
| Close tab | `Cmd+Opt+W` | `Ctrl+Alt+W` |
`Close` follows iTerm2: it closes the focused split pane, falls through to closing the tab when that was the tab's only pane, and closes the window when that was the last tab. `Close tab` closes every pane in the current tab at once, and closing the last tab closes the window, whether it runs from the menu, a chord, or the palette. The previous Linux/Windows pane-close chord `Ctrl+Shift+X` still works as an alias.
With the mouse, **middle-click** a tab to close it, and **double-click** empty space in the horizontal tab bar (right of the `+` button) to open a new tab.
A new tab with no title of its own is named **Tab N**, where N is the lowest number no other tab in the window holds. The number stays with the tab: closing or moving other tabs never renumbers it.
New tabs inherit the working directory from the current tab (if shell integration is installed) or start in the configured startup directory.
### Profile Selection on New Tab
The new tab button (`+`) on the tab bar is a split button:
- **Left portion** (`+`): Creates a default tab (existing behavior)
- **Right portion** (`▾`): Opens [Open Profiles](PROFILES.md#open-profiles), the profile launcher
The launcher lists **Default** (a tab using the global terminal config) and every profile; type to filter, `Enter` opens a new tab, `Shift+Enter` a new window, `Cmd+D` / `Cmd+Shift+D` a split. `Escape` closes it.
> **Note:** The chevron appears when one or more profiles exist. Works in both horizontal and vertical tab bar layouts.
>
**Configuration:**
To make the new tab shortcut (`Cmd+T` / `Ctrl+Shift+T`) open Open Profiles instead of immediately creating a default tab:
```yaml
new_tab_shortcut_shows_profiles: true # default: false
```
**Settings UI:** Settings > Windows & Tabs > Tab Bar > "New tab shortcut shows profile picker"
### New Tab Position
Control where new tabs are inserted in the tab bar:
```yaml
new_tab_position: end # default — append to the end of the tab bar
new_tab_position: after_active # insert immediately to the right of the active tab
```
`after_active` applies to all user-initiated new-tab actions: `Cmd+T` / `+` button / profile picker / custom `NewTab` actions. Reopen closed tab and arrangement restore always restore tabs to their original positions regardless of this setting.
**Settings UI:** Settings > Windows & Tabs > Tab Bar > "New tab position"
## Reopening Closed Tabs
Accidentally closed tabs can be recovered using reopen closed tab:
| Reopen closed tab | `Cmd + Shift + T` (alias `Cmd + Z`) | `Ctrl + Shift + Z` |
A toast notification appears after closing a tab, with an **Undo** button, the time left to undo, and your current reopen chord (left out when `reopen_closed_tab` is unbound). Undo restores the tab at its original position with its title, custom color, and split pane layout.
For full details on reopen closed tab configuration and keeping the shell running, see [Restoring Windows and Reopening Tabs](SESSION_MANAGEMENT.md).
## Switching Tabs
| Next tab | `Cmd+Shift+]` (macOS) / `Ctrl+Shift+]` or `Ctrl+Tab` |
| Previous tab | `Cmd+Shift+[` (macOS) / `Ctrl+Shift+[` or `Ctrl+Shift+Tab` |
| Go to tab 1-9 | `Cmd+1` through `Cmd+9` (macOS) / `Alt+1` through `Alt+9` |
| Last-used tab | `last_tab` (no default chord) |
| Rightmost tab | `go_to_last_tab` (no default chord) |
| Any window, tab, or pane | Open Quickly: `Cmd+Shift+O` (macOS) / `Ctrl+Alt+O` |
When the tab bar scrolls, switching tabs by keyboard or picker scrolls the newly active tab into view. A tab whose title is cut short shows the full title on hover.
`rename_tab` opens the inline rename on the active tab from the keyboard (the same field a double-click opens), and it works with the tab bar hidden. `close_other_tabs` and `close_tabs_to_right` close tabs in bulk; each tab keeps its own running-job confirmation, and a dialog stops the batch there.
## Reordering Tabs
Tabs can be reordered using drag-and-drop or keyboard shortcuts. A default **Tab N** title keeps its number when the tab moves.
### Drag-and-Drop Reordering
Click and drag any tab in the tab bar to move it to a new position:
1. **Press and hold** the mouse button on a tab to begin dragging
2. **Drag the tab** left or right to the desired position
3. **Release the mouse button** to drop the tab into place
**Visual Feedback:**
- A floating ghost tab follows the cursor during the drag with a semi-transparent preview of the tab being moved
- A blue insertion indicator line with a glow effect marks the drop target between tabs
- The dragged tab dims in its original position to indicate it is being moved
**Behavior Notes:**
- Press `Escape` to cancel a drag operation and return the tab to its original position
- Drag initiation is suppressed when only one tab exists in the window
- Dropping a tab on its original position has no effect
### Keyboard Reordering
| Move tab left | `Cmd+Opt+Shift+[` or `Cmd+Shift+Left` (macOS) / `Ctrl+Shift+Left` |
| Move tab right | `Cmd+Opt+Shift+]` or `Cmd+Shift+Right` (macOS) / `Ctrl+Shift+Right` |
A tab already at the left or right end stays put; the move does not wrap around to the other end.
A par-mux tab's move is sent to the daemon (`move-window`), so the new order is the session's window order: it survives reattach and other attached clients see it.
## Duplicating Tabs
Any tab can be duplicated via the context menu:
1. **Right-click** on any tab in the tab bar to open the context menu and select **Duplicate Tab**
Bound to `Cmd+Shift+J` (`Ctrl+Shift+J` on Linux and Windows) by default, and rebindable as the `duplicate_tab` action in Settings > Keys > Key Bindings.
**Behavior:**
- The duplicated tab inherits the working directory of the source tab
- A tab with split panes is duplicated with the same layout: split directions, divider positions, and each pane's working directory and user-set title. A par-mux or tmux tab copies only its working directory, since its panes live on the server
- Any custom tab color set on the source tab carries over to the new tab
- Any custom tab icon set on the source tab carries over to the new tab
- Duplication works on any tab via context menu, not just the currently active tab
- The new tab starts a fresh shell in the inherited directory (one per pane)
> **📝 Note:** The duplicated tab launches a new shell process. Running commands and shell state from the original tab are not carried over.
## Moving tabs between windows
A tab (including its PTY, scrollback, running processes, split panes, output
recorder) can be moved to a different window without being
restarted.
**Context menu:**
- Right-click a tab → **Move Tab to New Window** spawns a new par-term window
with the tab as its only occupant. The new window matches the source window's
size and is placed 30 pixels down-and-right from the source, clamped to the
source monitor's bounds. Disabled when the source window has only one tab
(the operation would be a no-op) or when the source window is hosting a tmux
gateway.
- Right-click a tab → **Move Tab to Window →** opens a submenu listing every
other par-term window, labeled `Window N - <active tab title>`. Selecting a
window transfers the tab there. If the source window becomes empty as a
result, it closes. Disabled for tmux-gateway windows; hidden entirely when no
other par-term windows exist.
**Keybinding:** Bind the `move_tab_to_new_window` action in
Settings → Keys → Key Bindings. There is no default chord. The keybinding only covers
the "new window" case; the "move to existing window" case is menu-only because
keybindings cannot parameterize on a specific target window.
**Limitations:**
- Tmux gateway tabs and tmux display tabs cannot be moved — both would break
the gateway/display link inside the source window.
- Per-window state (custom shader, assistant panel, window-level settings)
does not travel with the tab. The moved tab adopts the destination window's
settings.
## Panes
A tab holds one or more **panes**, split regions that each run their own shell. The default chords below are the shipped bindings; the **F1** help panel lists your current ones.
| Split right (new pane to the right) | `Cmd+D` | `Ctrl+Shift+E` |
| Split down (new pane below) | `Cmd+Shift+D` | `Ctrl+Shift+O` (alias `Ctrl+Shift+D`) |
| Close pane (then tab, then window) | `Cmd+W` | `Ctrl+Shift+W` |
| Focus pane in a direction | `Cmd+Opt+Arrow` | `Ctrl+Alt+Arrow` |
| Resize pane | `Cmd+Ctrl+Arrow` | `Ctrl+Alt+Shift+Arrow` |
| Swap with the neighbor in a direction | `Cmd+Opt+Shift+Arrow` | unbound |
| Select pane by letter | `Cmd+Opt+P` | `Ctrl+Alt+P` |
| Broadcast input to every pane | `Cmd+Opt+I` | `Ctrl+Alt+I` |
| Rename pane | unbound (`rename_pane`) | unbound |
**How each operation behaves today:**
- **Split** names describe where the new pane goes. The new pane takes half of the focused pane's space, and a tab holds at most `max_panes` panes (default 16).
- **Resize** moves the innermost divider around the focused pane by 5% of its split per keypress. Right and Down grow the focused pane and Left and Up shrink it, whatever the divider's axis. Dragging a divider with the mouse resizes it directly.
- **Swap** exchanges the focused pane's place in the layout with its neighbor in that direction; each pane keeps its shell and scrollback.
- **Broadcast input** sends every keystroke to all panes of the active tab until toggled off. The on/off switch belongs to the window, so it stays on when you switch tabs and then applies to the new active tab. A toast confirms each toggle.
- **Close** follows the cascade described in [Creating and Closing Tabs](#creating-and-closing-tabs).
Pane title bars, divider styles, and dimming of inactive panes are configured under **Settings ▸ Panes ▸ Layout & Dividers** and **Appearance**; see [Window Management](WINDOW_MANAGEMENT.md#pane-title-bars).
## Promoting and Demoting Panes
Panes can be moved between tabs while preserving all running processes (shells, vim sessions, builds, SSH connections, etc.). Only the terminal grid dimensions change via a resize event.
### Promote Pane to Tab
The focused pane in the current tab is extracted and wrapped in a new tab. The new tab is inserted immediately after the source tab and receives focus.
**Context menu:** Right-click a tab → **Promote Pane to Tab** (enabled only when the tab has multiple panes).
**Keybinding:** Bind the `promote_pane_to_tab` action in Settings → Keys → Key Bindings. There is no default shortcut.
**Behavior:**
- If the source tab has multiple panes, the focused pane is extracted and the remaining panes stay in the source tab
- If the source tab has a single pane, the new tab is created and the source tab is removed (equivalent to repositioning the tab)
- All processes in the promoted pane continue running uninterrupted
- In a par-mux tab the pane moves daemon-side into a new daemon window (`break-pane`); see [par-mux](MUX.md#working-in-a-mux-pane)
### Demote Tab to Pane
The current tab's entire pane tree is merged into another tab as new split panes. This is a multi-step pick-mode operation:
1. **Pick target tab** — a toast shows "Demote: Click a tab to merge into" (with an "Esc to cancel" hint). Click a different tab in the tab bar.
2. **Pick target pane** — switches to the target tab. A hint shows "Click a pane to merge into (Esc to cancel)". Click a pane within that tab.
3. **Choose direction** — an inline overlay appears near the clicked pane with **Horizontal** and **Vertical** buttons. Click to complete the merge.
Press **Escape** or right-click at any step to cancel.
**Context menu:** Right-click a tab → **Demote Tab to Pane** (enabled only when the window has 2+ tabs).
**Keybinding:** Bind the `demote_tab_to_pane` action in Settings → Keys → Key Bindings. There is no default shortcut.
**Behavior:**
- The source tab's pane tree (including all splits and running processes) is grafted into the target tab at the chosen split point
- The source tab is removed after the merge
- All `is_active` flags on transplanted panes are updated to match the target tab's state
- The merge is rejected if it would exceed the configured `max_panes` limit
- For par-mux tabs only a single-pane mux tab can be demoted, into another mux tab (`join-pane`); a split mux tab and mux/local mixes are refused (see [par-mux](MUX.md#working-in-a-mux-pane))
## Selecting a Pane by Letter
A tmux `display-panes` style pick mode for quickly focusing a pane in a split tab.
**Keybinding:** `Cmd + Alt + P` (macOS) / `Ctrl + Alt + P` (Linux/Windows), action name `select_pane_hint`.
**Behavior:**
- Invoking the binding draws a letter badge (a letter on a circle background) centered in every pane of the focused tab; the letters come from a home-row set assigned in pane-tree order, so the same layout always yields the same letters
- Typing a pane's letter focuses that pane and exits the mode; letters match case-insensitively
- A tab with more than 26 panes (`max_panes` allows 32, or unlimited) gets a two-letter label on every pane instead. The first letter keeps the mode armed and leaves only the badges it starts on screen; the second picks the pane
- To see pane numbers all the time, turn on `show_pane_numbers` with `show_pane_titles`: each title bar then starts with the pane's number in layout order (Settings > Panes > Appearance > "Show pane numbers in titles")
- Any other key, including `Escape`, cancels the mode without changing focus
- Switching tabs or closing the pane-hint tab cancels the mode
- Tabs with a single pane do not arm the mode — there is nothing to choose
- While active the mode sits at the top of the mode stack: badges render above all plugin overlays and the mode owns the key stream regardless of overlay focus (see the [overlay plugin design](../plans/2026-09-24-overlay-plugin-design.md) mode-stack contract)
## Tab Icons
Custom icons can be assigned to individual tabs for quick visual identification.
**Setting an Icon:**
1. **Right-click** on any tab in the tab bar to open the context menu
2. Select **Set Icon**
3. Choose an icon from the Nerd Font grid, or type any character or emoji into the text field
**Clearing an Icon:**
Right-click the tab and select **Clear Icon** to remove the custom icon and revert to the profile-assigned icon (if any) or no icon.
**Icon Precedence:**
```mermaid
graph LR
Custom[Custom Icon<br/>via context menu]
Profile[Profile Icon<br/>from profile config]
None[No Icon]
Custom -->|if cleared| Profile
Profile -->|if none set| None
class Custom primary
class Profile data
class None neutral
classDef primary fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
classDef data fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
classDef neutral fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
```
A custom icon set via the context menu takes precedence over any profile-assigned icon. When the custom icon is cleared, the tab falls back to the profile icon or displays no icon.
**Persistence:**
- Custom icons are kept when windows are restored on launch
- Custom icons are preserved in saved window arrangements (layouts)
- Custom icons carry over when duplicating a tab
## Tab Bar
### Tab Bar Position
The tab bar can be placed in three positions:
| **Top** | Horizontal tab bar at the top of the window (default) |
| **Bottom** | Horizontal tab bar below terminal content |
| **Left** | Vertical sidebar with scrollable tab list |
The **Left** position renders a vertical sidebar with:
- Scrollable tab list with active indicator
- Drag-and-drop reordering support
- Configurable sidebar width (default 160px, range 100–300px)
```yaml
# Tab bar position: "top", "bottom", or "left"
tab_bar_position: top
# Sidebar width for left position (pixels)
tab_bar_width: 160.0
```
**Settings UI:** Settings > Windows & Tabs > Tab Bar > "Position"
Switching between positions takes effect immediately without restart.
### Visibility Modes
Control when the tab bar appears:
| `always` | Tab bar always visible (default) |
| `when_multiple` | Show only when 2+ visible tabs exist (hidden tabs such as the tmux gateway tab do not count) |
| `never` | Tab bar never shown |
```yaml
tab_bar_mode: "always"
```
### Tab Style Variants
par-term includes 6 built-in tab style presets that apply coordinated color, size, and spacing adjustments:
| **Dark** | Default dark theme with subtle contrast (default) |
| **Light** | Light background with darker text |
| **Compact** | Reduced height and spacing for minimal footprint |
| **Minimal** | Understated design with muted colors |
| **High Contrast** | Bold colors for maximum readability |
| **Automatic** | Switches between light/dark based on system theme |
```yaml
# Tab style preset
tab_style: dark # dark, light, compact, minimal, high_contrast, automatic
```
**Settings UI:** Settings > Windows & Tabs > Tab Bar > "Tab style"
Each preset adjusts the tab bar background, active/inactive colors, height, and spacing as a coordinated set. Individual settings can still be overridden after selecting a preset.
### Tab Stretch
By default, tabs stretch to fill the available tab bar width while respecting minimum width constraints.
**Behavior:**
- Tabs expand equally to fill the bar
- Each tab respects the `tab_min_width` setting
- When too many tabs exist, they compress to minimum width
```yaml
# Enable/disable tab stretching (default: true)
tab_stretch_to_fill: true
# Minimum tab width in pixels
tab_min_width: 120.0
```
### HTML Titles
Tab titles support limited HTML markup for styling:
**Supported Tags:**
- `<b>` - Bold text
- `<i>` - Italic text
- `<u>` - Underlined text
- `<span style="color:...">` - Colored text
**Examples:**
```bash
# Set tab title with bold text (OSC 0 or OSC 2)
printf "\033]0;<b>Important</b> Server\007"
# Colored text
printf "\033]0;<span style=\"color:red\">Production</span>\007"
# Combined formatting
printf "\033]0;<b><span style=\"color:green\">✓</span></b> Tests Passing\007"
```
**Enabling HTML Titles:**
```yaml
tab_html_titles: true
```
> **⚠️ Note:** When `tab_html_titles` is disabled, HTML tags are stripped from titles.
### Inactive Tab Outline-Only Mode
The `tab_inactive_outline_only` option renders inactive tabs with just a border stroke and no background fill. This produces a cleaner, more minimal look where only the active tab has a solid background. Hovered inactive tabs brighten the outline for visual feedback.
```yaml
tab_inactive_outline_only: true # default: true
```
**Settings UI:** Settings > Windows & Tabs > Tab Bar Colors > "Inactive tabs outline only"
```mermaid
graph LR
Active["Active Tab<br/>(solid fill)"]
Inactive1["Inactive Tab<br/>(outline only)"]
Inactive2["Inactive Tab<br/>(outline only)"]
Hovered["Hovered Tab<br/>(bright outline)"]
class Active active
class Inactive1,Inactive2 neutral
class Hovered warning
classDef active fill:#0d47a1,stroke:#2196f3,stroke-width:3px,color:#ffffff
classDef neutral fill:#1E1E1E,stroke:#78909c,stroke-width:2px,color:#B0B0B0
classDef warning fill:#1E1E1E,stroke:#E0E0E0,stroke-width:3px,color:#ffffff
```
When enabled (the default), inactive tabs show only the border stroke, and hovered inactive tabs increase the outline brightness instead of adding a fill. When disabled, inactive tabs render with a dimmed background fill matching their assigned tab color.
## Tab Title Mode
Control how tab titles are automatically updated:
| `auto` | OSC title first, then working directory from shell integration, then keep default "Tab N" (default) |
| `osc_only` | Only update from explicit OSC escape sequences; never auto-set from CWD |
```yaml
tab_title_mode: auto
```
**Settings UI:** Settings > Windows & Tabs > Tab Bar > "Tab title mode:"
### Per-Pane Title Tracking
When a tab contains split panes, each pane tracks its own title independently. The tab bar displays the title of the currently focused pane.
**How it works:**
- Each pane stores its own last-known title from OSC sequences and shell-integration CWD
- `Tab::update_title()` iterates all panes each frame and updates each pane's title from its terminal
- Switching focus between split panes instantly reflects the correct title in the tab bar without waiting for new terminal output
- Local hostname and home-directory lookups are performed once per frame (not once per pane) to avoid redundant syscalls
### Remote Tab Title Format
When shell integration detects that the terminal is connected to a remote host (via SSH or similar), the tab title can automatically reflect the remote context. Control the format with `remote_tab_title_format`:
| `user_at_host` (default) | `user@hostname` | `deploy@prod.example.com` |
| `host` | hostname only | `prod.example.com` |
| `host_and_cwd` | `hostname:~/cwd` | `prod.example.com:~/app` |
```yaml
remote_tab_title_format: user_at_host # user_at_host | host | host_and_cwd
# When true (default), explicit OSC title sequences override this format.
remote_tab_title_osc_priority: true
```
**Settings UI:** Settings > Windows & Tabs > Tab Bar > "Remote tab title format:"
> **📝 Note:** Requires shell integration on the remote host to emit OSC 7 or OSC 1337 RemoteHost sequences. See [Integrations](INTEGRATIONS.md).
### Renaming Tabs
Double-click a tab, or right-click it and select **Rename Tab**, to set a custom name. Press **Enter** to save; **Escape** or a click anywhere else cancels. Manually named tabs are static — they are never auto-updated regardless of the title mode setting.
To revert a renamed tab to automatic title updates, right-click and rename with a blank name.
### Restoring Tab Names and Colors
User-set tab names and custom tab colors are preserved across:
- **Restore windows on launch** -- closing and reopening par-term restores custom names and colors
- **Window arrangements** -- saved layouts retain per-tab names and colors
- **Tab duplication** -- duplicated tabs inherit the source tab's custom color and icon, but not its custom name
This persistence also applies to custom tab icons (see [Tab Icons](#tab-icons)).
## Tab Appearance
Customize the visual style of tabs:
### Layout
| `tab_bar_height` | Height in pixels | `28.0` |
| `tab_bar_width` | Sidebar width for left position (pixels) | `160.0` |
| `tab_min_width` | Minimum tab width | `120.0` |
| `max_tabs` | Maximum tabs per window (0 = unlimited) | `0` |
| `tab_stretch_to_fill` | Stretch tabs to fill bar width | `true` |
| `tab_show_close_button` | Show close button on tabs | `true` |
| `tab_show_index` | Show tab index numbers | `false` |
| `tab_border_width` | Tab border width in pixels | varies |
### Colors (RGB arrays)
| `tab_bar_background` | Tab bar background |
| `tab_active_background` | Active tab background |
| `tab_inactive_background` | Inactive tab background |
| `tab_hover_background` | Hovered tab background |
| `tab_active_text` | Active tab text color |
| `tab_inactive_text` | Inactive tab text color |
| `tab_active_indicator` | Active tab underline/indicator |
| `tab_activity_indicator` | Activity dot color |
| `tab_bell_indicator` | Bell indicator color |
| `tab_close_button` | Close button color |
| `tab_close_button_hover` | Close button hover color |
| `tab_border_color` | Tab border color |
### Inactive Tab Styling
| `tab_inactive_outline_only` | Outline-only mode (no fill) | `true` |
| `dim_inactive_tabs` | Dim inactive tabs with reduced opacity | `true` |
| `inactive_tab_opacity` | Opacity for dimmed inactive tabs (0.0-1.0) | `0.6` |
### Automatic Style Sub-Styles
When `tab_style` is set to `automatic`, the light and dark sub-styles can be overridden:
```yaml
tab_style: automatic
light_tab_style: light # Style used in light mode
dark_tab_style: dark # Style used in dark mode
```
### Behavior
| `tab_inherit_cwd` | New tab inherits working directory from active tab | `true` |
| `tab_html_titles` | Render limited HTML in tab titles | `false` |
**Example Configuration:**
```yaml
tab_bar_height: 32.0
tab_bar_background: [40, 40, 40]
tab_active_background: [60, 60, 60]
tab_inactive_background: [40, 40, 40]
tab_stretch_to_fill: true
tab_min_width: 120.0
tab_html_titles: true
tab_inactive_outline_only: true
dim_inactive_tabs: true
tab_border_color: [80, 80, 80]
tab_border_width: 1.0
```
## Known Fixes
The following tab bar rendering issues have been resolved:
- **Rounded Corner Stroke Thickness** -- Tab bar rounded corners now render with consistent stroke thickness, eliminating visual artifacts at corner boundaries
- **First Tab Border Clipping** -- The leftmost tab no longer clips its left border against the tab bar edge
- **Progress Bar Overlapping Tab Bar** -- Terminal progress bars no longer visually overlap or bleed into the tab bar region
- **New Tab Button Clipped Off Right Edge** -- A width budget miscalculation caused the new-tab button (and chevron) to be clipped past the right edge of the tab bar; the layout now correctly accounts for padding in its width budget
- **Assistant Panel Overlapping Tab Bar** -- When the assistant panel was open, tab bar content could render underneath the overlay; the tab bar now reserves the assistant panel width so tabs and buttons shrink to fit
- **Rounded Tab Border Consistency** -- Tab pill draw rects are snapped to pixel boundaries with a centered stroke so rounded and straight border segments render with uniform thickness
## Configuration
Complete tab configuration reference:
```yaml
# Tab bar position: "top", "bottom", "left"
tab_bar_position: top
# Tab bar visibility: "always", "when_multiple", "never"
tab_bar_mode: "always"
# Tab title mode: "auto", "osc_only"
tab_title_mode: auto
# Remote tab title format: "user_at_host", "host", "host_and_cwd"
remote_tab_title_format: user_at_host
# When true (default), explicit OSC titles override remote_tab_title_format
remote_tab_title_osc_priority: true
# Tab style preset: "dark", "light", "compact", "minimal", "high_contrast", "automatic"
tab_style: dark
# Sub-styles for automatic mode
light_tab_style: light
dark_tab_style: dark
# Tab bar dimensions
tab_bar_height: 28.0
tab_bar_background: [40, 40, 40]
tab_bar_width: 160.0 # Sidebar width for left position
# Tab colors (RGB arrays)
tab_active_background: [60, 60, 60]
tab_inactive_background: [40, 40, 40]
tab_hover_background: [50, 50, 50]
tab_active_text: [255, 255, 255]
tab_inactive_text: [180, 180, 180]
tab_active_indicator: [100, 150, 255]
tab_activity_indicator: [100, 180, 255]
tab_bell_indicator: [255, 200, 100]
tab_close_button: [150, 150, 150]
tab_close_button_hover: [255, 100, 100]
tab_border_color: [80, 80, 80]
tab_border_width: 1.0
# Inactive tab rendering
tab_inactive_outline_only: true
dim_inactive_tabs: true
inactive_tab_opacity: 0.6
# Tab sizing and layout
tab_stretch_to_fill: true
tab_min_width: 120.0
tab_show_close_button: true
tab_show_index: false
max_tabs: 0 # 0 = unlimited
# Tab titles
tab_html_titles: false
tab_inherit_cwd: true
# Profile selection
show_profile_drawer_button: false
new_tab_shortcut_shows_profiles: false # Open Profiles on Cmd+T
new_tab_position: end # "end" or "after_active"
```
## Related Documentation
- [Keyboard Shortcuts](../guides/KEYBOARD_SHORTCUTS.md) - Tab navigation shortcuts
- [Restoring Windows and Reopening Tabs](SESSION_MANAGEMENT.md) - Reopen closed tabs and restore windows on launch
- [Profiles](PROFILES.md) - Open profiles in new tabs
- [SSH Host Management](SSH.md) - SSH profile-based tab creation
- [Window Management](WINDOW_MANAGEMENT.md) - Window and tab interaction
- [Integrations](INTEGRATIONS.md) - Shell integration for directory inheritance