---
title: "WezTerm Workspaces (Sessions)"
aliases: [wezterm-sessions, wezterm-workspaces]
tags: [wezterm, terminal, workspaces, sessions, tmux]
sources: [raw/Sessions - Wez's Terminal Emulator.md]
created: 2026-04-17
updated: 2026-04-17
---

## What Are Workspaces?

Workspaces are WezTerm's equivalent of **tmux sessions** — named groups of windows (MuxWindows) that can be switched between without closing anything.

- Every `MuxWindow` carries a **workspace label**
- The GUI renders only the windows in the **active workspace**
- Switching workspaces swaps all visible GUI windows simultaneously
- Windows in other workspaces are hidden but still running

## Switching Workspaces

| Key Assignment | Action |
|---|---|
| `SwitchToWorkspace` | Jump to a named workspace |
| `SwitchWorkspaceRelative` | Cycle forward/backward through workspaces |
| `ShowLauncher` / `ShowLauncherArgs` | Interactive list of all workspaces to pick from |

Any spawn command (new window, new tab) can also accept a `workspace` argument to open into a non-active workspace immediately.

## Pre-defining Layouts at Startup

Use startup events to build a workspace layout automatically when WezTerm launches:

- **`gui-startup`** — fires when the GUI starts; use `mux.spawn_window { workspace = "name" }` to create named workspaces with pre-arranged tabs/panes
- **`mux-startup`** — fires for the multiplexer daemon; useful for headless / server setups

```lua
-- Example: gui-startup pre-built workspaces
local mux = wezterm.mux
wezterm.on("gui-startup", function()
  local _, _, window = mux.spawn_window { workspace = "work" }
  window:gui_window():set_right_status("work")

  mux.spawn_window { workspace = "personal" }
  mux.set_active_workspace("work")
end)
```

## Comparison with tmux Sessions

| Concept | tmux | WezTerm |
|---|---|---|
| Session | `tmux new-session -s name` | Workspace label |
| Switch session | `tmux switch-client -t name` | `SwitchToWorkspace` |
| List sessions | `tmux ls` | `ShowLauncher` |
| Pre-define layout | `.tmux.conf` + scripting | `gui-startup` event |

## Key Takeaways

- Workspaces are **labels on MuxWindows** — no separate process or socket like tmux sessions
- The GUI shows **only the active workspace**; background workspaces are hidden but alive
- Use `ShowLauncher` as the interactive workspace picker (bind it to a convenient key)
- Pre-built layouts go in the **`gui-startup`** event handler in `wezterm.lua`
- Any spawn call can target a non-active workspace by name — useful for background task windows

## Related

- [[wiki/dotfiles/wezterm-config|WezTerm Config]] — Lua config structure and file locations
- [[wiki/dotfiles/wezterm-key-bindings|WezTerm Key Bindings]] — how to bind SwitchToWorkspace
- [[wiki/dotfiles/wezterm-key-tables|WezTerm Key Tables]] — modal layers for workspace switching
- [[wiki/dotfiles/wezterm-launching-programs|WezTerm Launching Programs]] — spawn options and CWD

## Sources

- [wezterm.org/recipes/workspaces.html](https://wezterm.org/recipes/workspaces.html)