> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# Tabs and Panes

> Multiplex your terminal with tabs and split panes for efficient workflow management

WezTerm provides powerful multiplexing capabilities that allow you to work with multiple terminal sessions in a single window using tabs and panes.

## Tabs

Tabs allow you to organize multiple terminal sessions within a single window. Each tab can contain one or more panes.

### Default Tab Keybindings

| Action        | Keybinding (macOS)      | Keybinding (Linux/Windows)        |
| ------------- | ----------------------- | --------------------------------- |
| New tab       | `Cmd+T`                 | `Ctrl+Shift+T`                    |
| Close tab     | `Cmd+W`                 | `Ctrl+Shift+W`                    |
| Next tab      | `Cmd+Shift+]`           | `Ctrl+PageDown`                   |
| Previous tab  | `Cmd+Shift+[`           | `Ctrl+PageUp`                     |
| Go to tab 1-8 | `Cmd+1` through `Cmd+8` | `Ctrl+Alt+1` through `Ctrl+Alt+8` |
| Go to tab 9   | `Cmd+9`                 | `Ctrl+Alt+9`                      |

### Creating Tabs Programmatically

<CodeGroup>
  ```lua Simple Tab theme={null}
  local wezterm = require 'wezterm'
  local act = wezterm.action
  local config = {}

  config.keys = {
    -- Create a new tab in the same domain as the current pane
    {
      key = 't',
      mods = 'SHIFT|ALT',
      action = act.SpawnTab 'CurrentPaneDomain',
    },
  }

  return config
  ```

  ```lua Tab with Specific Command theme={null}
  config.keys = {
    -- Spawn a new tab running htop
    {
      key = 'h',
      mods = 'SHIFT|ALT',
      action = act.SpawnCommandInNewTab {
        args = { 'htop' },
      },
    },
  }
  ```
</CodeGroup>

### Navigating Between Tabs

```lua Activate Specific Tab theme={null}
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {}
for i = 1, 8 do
  -- CTRL+ALT + number to activate that tab
  table.insert(config.keys, {
    key = tostring(i),
    mods = 'CTRL|ALT',
    action = act.ActivateTab(i - 1),
  })
end

return config
```

## Panes

Panes allow you to split a single tab into multiple terminal sessions. You can split both horizontally and vertically.

### Default Pane Keybindings

| Action                        | Keybinding              |
| ----------------------------- | ----------------------- |
| Split horizontal (left/right) | `Ctrl+Shift+Alt+%`      |
| Split vertical (top/bottom)   | `Ctrl+Shift+Alt+"`      |
| Move to pane (Left)           | `Ctrl+Shift+LeftArrow`  |
| Move to pane (Right)          | `Ctrl+Shift+RightArrow` |
| Move to pane (Up)             | `Ctrl+Shift+UpArrow`    |
| Move to pane (Down)           | `Ctrl+Shift+DownArrow`  |
| Close current pane            | `Ctrl+Shift+W`          |

### Splitting Panes

<CodeGroup>
  ```lua Horizontal Split theme={null}
  local wezterm = require 'wezterm'
  local act = wezterm.action
  local config = {}

  config.keys = {
    {
      key = '%',
      mods = 'CTRL|SHIFT|ALT',
      action = act.SplitHorizontal { domain = 'CurrentPaneDomain' },
    },
  }

  return config
  ```

  ```lua Vertical Split theme={null}
  config.keys = {
    {
      key = '"',
      mods = 'CTRL|SHIFT|ALT',
      action = act.SplitVertical { domain = 'CurrentPaneDomain' },
    },
  }
  ```

  ```lua Split with Custom Command theme={null}
  config.keys = {
    -- Split horizontally and run 'top'
    {
      key = '%',
      mods = 'CTRL|SHIFT|ALT',
      action = act.SplitHorizontal {
        args = { 'top' },
      },
    },
  }
  ```
</CodeGroup>

### Navigating Between Panes

```lua Pane Navigation theme={null}
local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

config.keys = {
  {
    key = 'LeftArrow',
    mods = 'CTRL|SHIFT',
    action = act.ActivatePaneDirection 'Left',
  },
  {
    key = 'RightArrow',
    mods = 'CTRL|SHIFT',
    action = act.ActivatePaneDirection 'Right',
  },
  {
    key = 'UpArrow',
    mods = 'CTRL|SHIFT',
    action = act.ActivatePaneDirection 'Up',
  },
  {
    key = 'DownArrow',
    mods = 'CTRL|SHIFT',
    action = act.ActivatePaneDirection 'Down',
  },
}

return config
```

<Note>
  You can also use `"Next"` and `"Prev"` as directions to cycle through panes according to their position in the pane tree.
</Note>

### Resizing Panes

```lua Pane Resizing theme={null}
config.keys = {
  {
    key = 'LeftArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Left', 5 },
  },
  {
    key = 'RightArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Right', 5 },
  },
  {
    key = 'UpArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Up', 5 },
  },
  {
    key = 'DownArrow',
    mods = 'CTRL|SHIFT|ALT',
    action = act.AdjustPaneSize { 'Down', 5 },
  },
}
```

## Tab Bar Customization

### Hiding the Tab Bar

```lua Hide Tab Bar theme={null}
-- Always show the tab bar
config.enable_tab_bar = true

-- Hide tab bar when there's only one tab
config.hide_tab_bar_if_only_one_tab = true
```

### Tab Bar Position

```lua Tab Bar at Bottom theme={null}
config.tab_bar_at_bottom = true
```

## Multiplexing Domains

WezTerm's multiplexing is based on *domains* - distinct sets of windows and tabs. You can:

* Use the default local domain for standard terminal sessions
* Connect to remote multiplexing servers via SSH or TLS
* Persist sessions across network interruptions
* Share tabs between different WezTerm instances

For advanced multiplexing features including remote sessions, see the SSH documentation.

## Best Practices

<Steps>
  <Step title="Use tabs for different projects">
    Keep each project or task in its own tab for better organization.
  </Step>

  <Step title="Split panes for related tasks">
    Use panes to keep related terminals visible simultaneously (e.g., editor in one pane, tests in another).
  </Step>

  <Step title="Customize your keybindings">
    Modify default keybindings to match your workflow and avoid conflicts with other applications.
  </Step>
</Steps>