74 lines
3 KiB
Markdown
74 lines
3 KiB
Markdown
---
|
|
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)
|