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

Simple Tab

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

Navigating Between Tabs

Activate Specific Tab

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

Horizontal Split

local wezterm = require 'wezterm'
local act = wezterm.action
local config = {}

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

return config

Navigating Between Panes

Pane Navigation

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

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

Resizing Panes

Pane Resizing

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

Hide Tab Bar

-- 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

Tab Bar at Bottom

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

1. Use tabs for different projects

   Keep each project or task in its own tab for better organization.

2. Split panes for related tasks

   Use panes to keep related terminals visible simultaneously (e.g., editor in one pane, tests in another).

3. Customize your keybindings

   Modify default keybindings to match your workflow and avoid conflicts with other applications.