| title |
aliases |
tags |
sources |
created |
updated |
| WezTerm Workspaces (Sessions) |
| wezterm-sessions |
| wezterm-workspaces |
|
| wezterm |
| terminal |
| workspaces |
| sessions |
| tmux |
|
| raw/Sessions - Wez's Terminal Emulator.md |
|
2026-04-17 |
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/panesmux-startup — fires for the multiplexer daemon; useful for headless / server setups
-- 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
Sources
