WezTerm Best Practices Guide

gistfile0.txt

# WezTerm Best Practices Guide

## Installation

```bash
# macOS
brew install --cask wezterm

# Linux (native packages recommended over Flatpak for power users)
# See distro-specific instructions at wezterm.org/install/linux.html
```

## Configuration File Setup

**Location**: `~/.wezterm.lua` (recommended for simplicity)

For complex multi-file configs: `~/.config/wezterm/wezterm.lua`

**Basic structure**:
```lua
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Your settings here

return config
```

WezTerm **automatically reloads** on save. Force reload: `CTRL+SHIFT+R`

---

## Essential Settings

```lua
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Font (install a Nerd Font first)
config.font = wezterm.font("MesloLGS Nerd Font Mono")
config.font_size = 14
config.line_height = 1.2

-- Window
config.window_decorations = "RESIZE"
config.hide_tab_bar_if_only_one_tab = true
config.tab_bar_at_bottom = true
config.window_background_opacity = 0.9
config.macos_window_background_blur = 10  -- macOS only

-- Scrollback
config.scrollback_lines = 5000

-- Color scheme (735 built-in options)
config.color_scheme = 'Hardcore'

return config
```

---

## Keybindings Best Practices

### Leader Key (tmux-style)
```lua
config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 2000 }

config.keys = {
  -- Tabs
  { key = 'c', mods = 'LEADER', action = act.SpawnTab 'CurrentPaneDomain' },
  { key = 'n', mods = 'LEADER', action = act.ActivateTabRelative(1) },
  { key = 'p', mods = 'LEADER', action = act.ActivateTabRelative(-1) },
  { key = '&', mods = 'LEADER', action = act.CloseCurrentTab{ confirm = true } },
  
  -- Panes
  { key = '|', mods = 'LEADER', action = act.SplitHorizontal{ domain = 'CurrentPaneDomain' } },
  { key = '-', mods = 'LEADER', action = act.SplitVertical{ domain = 'CurrentPaneDomain' } },
  { key = 'z', mods = 'LEADER', action = act.TogglePaneZoomState },
  { key = 'x', mods = 'LEADER', action = act.CloseCurrentPane{ confirm = true } },
  
  -- Vim-style pane navigation
  { key = 'h', mods = 'CTRL', action = act.ActivatePaneDirection 'Left' },
  { key = 'j', mods = 'CTRL', action = act.ActivatePaneDirection 'Down' },
  { key = 'k', mods = 'CTRL', action = act.ActivatePaneDirection 'Up' },
  { key = 'l', mods = 'CTRL', action = act.ActivatePaneDirection 'Right' },
  
  -- Pane resizing
  { key = 'h', mods = 'ALT', action = act.AdjustPaneSize{ 'Left', 5 } },
  { key = 'j', mods = 'ALT', action = act.AdjustPaneSize{ 'Down', 5 } },
  { key = 'k', mods = 'ALT', action = act.AdjustPaneSize{ 'Up', 5 } },
  { key = 'l', mods = 'ALT', action = act.AdjustPaneSize{ 'Right', 5 } },
  
  -- Copy mode
  { key = '[', mods = 'LEADER', action = act.ActivateCopyMode },
}
```

---

## Multiplexing & Session Persistence

### Local Unix Domain (for persistent sessions)
```lua
config.unix_domains = {
  { name = 'unix' },
}

-- Auto-attach on startup (optional)
config.default_gui_startup_args = { 'connect', 'unix' }
```

### SSH Domains
SSH hosts auto-populate from `~/.ssh/config`:
- `SSH:hostname` - Plain SSH
- `SSHMUX:hostname` - Multiplexed SSH (persistent tabs)

```bash
# Connect via CLI
wezterm connect SSHMUX:my.server

# Spawn tab in existing session
wezterm cli spawn --domain-name SSHMUX:my.server
```

### Workspace keybindings
```lua
{ key = 's', mods = 'LEADER', action = act.ShowLauncherArgs{ flags = 'FUZZY|WORKSPACES' } },
{ key = 'a', mods = 'LEADER', action = act.AttachDomain 'unix' },
{ key = 'd', mods = 'LEADER', action = act.DetachDomain{ DomainName = 'unix' } },
```

---

## Performance Optimization

```lua
-- GPU frontend (WebGpu, OpenGL, or Software)
config.front_end = "WebGpu"

-- Reduce animation FPS if GPU issues
config.animation_fps = 60

-- Dim inactive panes
config.inactive_pane_hsb = {
  saturation = 0.8,
  brightness = 0.7,
}
```

---

## Advanced: Maximize on Startup

```lua
wezterm.on('gui-startup', function(cmd)
  local tab, pane, window = wezterm.mux.spawn_window(cmd or {})
  window:gui_window():maximize()
end)
```

---

## Custom Color Scheme Example

```lua
config.colors = {
  foreground = "#CBE0F0",
  background = "#011423",
  cursor_bg = "#47FF9C",
  cursor_border = "#47FF9C",
  cursor_fg = "#011423",
  selection_bg = "#033259",
  selection_fg = "#CBE0F0",
  ansi = { "#214969", "#E52E2E", "#44FFB1", "#FFE073",
           "#0FC5ED", "#a277ff", "#24EAF7", "#24EAF7" },
  brights = { "#214969", "#E52E2E", "#44FFB1", "#FFE073",
              "#0FC5ED", "#a277ff", "#24EAF7", "#24EAF7" },
}
```

---

## Key Takeaways

| Practice | Recommendation |
|----------|----------------|
| Config location | `~/.wezterm.lua` for simple, `~/.config/wezterm/` for multi-file |
| Font | Use a Nerd Font (MesloLGS, JetBrainsMono) |
| Leader key | `Ctrl-A` matches tmux muscle memory |
| Persistence | Use unix domains for session recovery |
| SSH | Use `SSHMUX:` prefix for multiplexed connections |
| Performance | WebGpu frontend, adjust `animation_fps` as needed |

---

## Sources

- [Official Configuration Guide](https://wezterm.org/config/files.html)
- [Config Options Reference](https://wezterm.org/config/lua/config/index.html)
- [How To Setup WezTerm - Josean](https://www.josean.com/posts/how-to-setup-wezterm-terminal)
- [How I Use WezTerm - mwop.net](https://mwop.net/blog/2024-07-04-how-i-use-wezterm.html)
- [Ultimate WezTerm Configuration Guide](https://www.technicalexplore.com/tech/mastering-your-terminal-the-ultimate-guide-to-wezterm-configuration)
- [Multiplexing Documentation](https://wezterm.org/multiplexing.html)
- [SSH Documentation](https://wezterm.org/ssh.html)
- [Switch from Tmux to WezTerm](https://www.florianbellmann.com/blog/switch-from-tmux-to-wezterm)