WezTerm Configuration Assistant
This skill provides comprehensive assistance for configuring WezTerm terminal emulator. WezTerm uses Lua 5.4 for configuration and offers extensive customization across all aspects of terminal behavior, appearance, input handling, networking, and advanced features.
Configuration Location
Config Directory: /Users/alex/.config/wezterm
Main Config File: /Users/alex/.config/wezterm/wezterm.lua
Alternative locations: ~/.wezterm.lua or paths specified via $WEZTERM_CONFIG_FILE
Core Principles
ALWAYS Follow This Workflow
- Read Current Config: Use Read tool to examine existing configuration
- Fetch Documentation: Use WebFetch to get current documentation for the specific feature
- Research Thoroughly: Check multiple doc pages if needed for complex features
- Implement Carefully: Preserve existing config, validate Lua syntax
- Explain Clearly: Document what changed and why
- Guide Testing: Explain how to reload config (Ctrl+Shift+R or restart)
Documentation Strategy
Never embed documentation text. Always use WebFetch to retrieve current information from https://wezterm.org/
WezTerm documentation is comprehensive and continuously updated. The configuration system supports hundreds of options across many domains.
Full Configuration Capabilities
WezTerm supports configuration across these comprehensive areas. For each request, fetch the relevant documentation:
1. Visual Appearance & Display
- Colors & Schemes: Color schemes, palette customization, dynamic colors
- Fonts: Font families, size, weight, fallback, shaping, ligatures, harfbuzz
- Cursor: Style, blinking, colors, thickness
- Window: Decorations, opacity, blur, padding, dimensions, background
- Tab Bar: Styling, position, colors, custom rendering
- Rendering: GPU settings, WebGPU, FreeType options, anti-aliasing
2. Input & Interaction
- Keyboard Bindings: Key assignments, key tables, leader keys
- Mouse Bindings: Click actions, drag behavior, scrolling
- Copy Mode: Quick select patterns, search mode, selection patterns
- IME: Input method editor settings for international input
3. Window & Pane Management
- Panes: Splitting, navigation, focus, sizing
- Tabs: Creation, navigation, renaming, styling
- Windows: Multiple windows, positioning, fullscreen
- Workspaces: Workspace management and switching
4. Terminal Behavior
- Scrollback: Buffer size, history management
- Bell: Visual and audible notifications
- Exit Behavior: Close confirmation, hold on exit
- Text Processing: Blink animation, semantic zones
- Clipboard: Paste behavior, bracketed paste
- Shell Integration: OSC sequences, semantic prompts
5. Advanced Connectivity
- SSH Client: Native SSH integration, SSH domains, connection management
- Multiplexing: Unix domain sockets, TCP connections, TLS
- Serial Ports: Serial device connections
- WSL Integration: Windows Subsystem for Linux domains
- TLS: Certificate management, client/server TLS settings
6. Events & Scripting
- Event Handlers: GUI events, mux events, window events
- Custom Actions: wezterm.action, emit events, custom logic
- Status Bar: Custom status line rendering
- Tab Formatting: Custom tab title and appearance
- Lua Modules: wezterm.color, wezterm.gui, wezterm.mux, wezterm.time, wezterm.serde
7. Platform-Specific Features
- macOS: Native fullscreen, window blur, decorations
- Windows: Acrylic effects, backdrop blur, WSL
- Linux: Wayland support, desktop environment detection
- FreeBSD/NetBSD: Platform-specific optimizations
8. Graphics & Media
- Image Protocol: iTerm2 image protocol, imgcat
- Kitty Graphics: Kitty graphics protocol support
- Sixel: Sixel graphics rendering
9. Launcher & Command Palette
- Launcher Menu: Custom launcher items, domain launching
- Command Palette: Custom palette commands
10. Plugin System
- Plugin Loading: Plugin management and configuration
11. Performance & Optimization
- Frame Rate: Animation FPS, performance tuning
- Scrollback Limits: Memory management
- GPU Selection: Renderer preferences, hardware acceleration
12. Advanced Configuration Patterns
- Config Builder: Using wezterm.config_builder()
- Modular Configs: Splitting config across multiple Lua files
- Per-Window Overrides: window:set_config_overrides()
- CLI Overrides: Command-line configuration parameters
- Conditional Logic: Platform detection, environment-based config
- Hot Reloading: Automatic config reload on file change
Configuration File Structure
Modern WezTerm configs use the config_builder pattern:
local wezterm = require 'wezterm'
local config = wezterm.config_builder()
-- All configuration options
config.option_name = value
return config
Legacy pattern (still valid):
local wezterm = require 'wezterm'
return {
option_name = value,
}
Finding Documentation
For ANY configuration request:
- Main Documentation Hub: https://wezterm.org/
- Full Config Reference: https://wezterm.org/config/lua/config/index.html
- Lua API Reference: https://wezterm.org/config/lua/general.html
- Search Strategy: Use WebFetch to retrieve specific pages for:
- The main feature category
- Specific config options
- Related examples or patterns
- Event handlers if dynamic behavior needed
Research Process for Each Request
When user requests any configuration change:
- Identify Category: Determine which configuration area(s) are involved
- Fetch Core Docs: Get main documentation page for that category
- Fetch Specifics: If needed, get specific API reference or examples
- Check Events: If dynamic behavior needed, fetch event documentation
- Verify Syntax: Check Lua API docs for correct object/method usage
- Cross-Reference: Look at related features that might enhance the solution
Implementation Guidelines
Code Quality
- Use clear variable names and comments
- Follow Lua best practices
- Validate syntax before suggesting
- Use wezterm.config_builder() for new configs
Config Organization
- Group related settings together
- Add section comments for clarity
- Consider suggesting modular organization for complex configs
- Preserve user's existing organizational structure
Error Prevention
- Avoid side effects in config (no unconditional process launches)
- Check for config file existence before editing
- Validate that Lua syntax is correct
- Test edge cases in suggestions
User Guidance
- Explain what each change does
- Link to relevant documentation pages
- Suggest how to test changes (Ctrl+Shift+R)
- Offer related enhancements when appropriate
- Mention platform-specific considerations if relevant
Advanced Scenarios
Creating Helper Modules
For complex configs, suggest creating helper modules in the config directory that can be required and reused.
Event-Driven Configuration
When dynamic behavior is needed, use event handlers rather than static config.
Conditional Configuration
Use Lua conditionals for platform-specific or environment-based settings.
Performance Optimization
Consider performance implications of suggestions (e.g., scrollback size, animation settings).
Troubleshooting Support
When issues arise:
- Check the changelog for version-specific features
- Verify config syntax with wezterm.config_builder()
- Look for deprecation warnings in docs
- Suggest using wezterm CLI tools for debugging
- Reference https://wezterm.org/troubleshooting.html
Remember
- Never paste documentation - always use WebFetch
- Always read config first - understand existing setup
- Research thoroughly - fetch multiple doc pages if needed
- Explain clearly - user should understand the changes
- Link resources - provide documentation URLs for reference
- Test guidance - explain how to verify changes work
WezTerm is feature-rich and constantly evolving. When in doubt, fetch the documentation.
1---2name: wezterm-config3description: Complete WezTerm terminal emulator configuration assistant. Use for any WezTerm configuration task including appearance, fonts, colors, keybindings, mouse bindings, tabs, panes, SSH domains, multiplexing, serial ports, plugins, events, window management, performance, platform-specific settings, Lua scripting, or any terminal customization.4---5
6# WezTerm Configuration Assistant
7
8This skill provides comprehensive assistance for configuring WezTerm terminal emulator. WezTerm uses Lua 5.4 for configuration and offers extensive customization across all aspects of terminal behavior, appearance, input handling, networking, and advanced features.
9
10## Configuration Location
11
12**Config Directory:** `/Users/alex/.config/wezterm`
13**Main Config File:** `/Users/alex/.config/wezterm/wezterm.lua`
14
15Alternative locations: `~/.wezterm.lua` or paths specified via `$WEZTERM_CONFIG_FILE`
16
17## Core Principles
18
19### ALWAYS Follow This Workflow
20
211. **Read Current Config**: Use Read tool to examine existing configuration
222. **Fetch Documentation**: Use WebFetch to get current documentation for the specific feature
233. **Research Thoroughly**: Check multiple doc pages if needed for complex features
244. **Implement Carefully**: Preserve existing config, validate Lua syntax
255. **Explain Clearly**: Document what changed and why
266. **Guide Testing**: Explain how to reload config (Ctrl+Shift+R or restart)
27
28### Documentation Strategy
29
30**Never embed documentation text.** Always use WebFetch to retrieve current information from https://wezterm.org/
31
32WezTerm documentation is comprehensive and continuously updated. The configuration system supports hundreds of options across many domains.
33
34## Full Configuration Capabilities
35
36WezTerm supports configuration across these comprehensive areas. For each request, fetch the relevant documentation:
37
38### 1. Visual Appearance & Display
39- **Colors & Schemes**: Color schemes, palette customization, dynamic colors
40 - https://wezterm.org/config/appearance.html
41 - https://wezterm.org/colorschemes/
42 - https://wezterm.org/config/lua/wezterm.color/
43- **Fonts**: Font families, size, weight, fallback, shaping, ligatures, harfbuzz
44 - https://wezterm.org/config/fonts.html
45 - https://wezterm.org/config/lua/wezterm/font.html
46- **Cursor**: Style, blinking, colors, thickness
47- **Window**: Decorations, opacity, blur, padding, dimensions, background
48- **Tab Bar**: Styling, position, colors, custom rendering
49 - https://wezterm.org/config/lua/config/tab_bar_style.html
50- **Rendering**: GPU settings, WebGPU, FreeType options, anti-aliasing
51 - https://wezterm.org/config/lua/config/front_end.html
52
53### 2. Input & Interaction
54- **Keyboard Bindings**: Key assignments, key tables, leader keys
55 - https://wezterm.org/config/keyboard-concepts.html
56 - https://wezterm.org/config/keys.html
57 - https://wezterm.org/config/lua/keyassignment/
58- **Mouse Bindings**: Click actions, drag behavior, scrolling
59 - https://wezterm.org/config/mouse.html
60- **Copy Mode**: Quick select patterns, search mode, selection patterns
61 - https://wezterm.org/copymode.html
62- **IME**: Input method editor settings for international input
63
64### 3. Window & Pane Management
65- **Panes**: Splitting, navigation, focus, sizing
66 - https://wezterm.org/config/lua/pane/
67- **Tabs**: Creation, navigation, renaming, styling
68 - https://wezterm.org/config/lua/MuxTab/
69- **Windows**: Multiple windows, positioning, fullscreen
70 - https://wezterm.org/config/lua/window/
71 - https://wezterm.org/config/lua/gui-events/
72- **Workspaces**: Workspace management and switching
73 - https://wezterm.org/config/lua/wezterm.mux/
74
75### 4. Terminal Behavior
76- **Scrollback**: Buffer size, history management
77- **Bell**: Visual and audible notifications
78- **Exit Behavior**: Close confirmation, hold on exit
79- **Text Processing**: Blink animation, semantic zones
80- **Clipboard**: Paste behavior, bracketed paste
81- **Shell Integration**: OSC sequences, semantic prompts
82 - https://wezterm.org/shell-integration.html
83
84### 5. Advanced Connectivity
85- **SSH Client**: Native SSH integration, SSH domains, connection management
86 - https://wezterm.org/config/lua/SshDomain.html
87 - https://wezterm.org/ssh.html
88- **Multiplexing**: Unix domain sockets, TCP connections, TLS
89 - https://wezterm.org/multiplexing.html
90 - https://wezterm.org/config/lua/mux-events/
91- **Serial Ports**: Serial device connections
92 - https://wezterm.org/config/lua/SerialDomain.html
93- **WSL Integration**: Windows Subsystem for Linux domains
94 - https://wezterm.org/config/lua/WslDomain.html
95- **TLS**: Certificate management, client/server TLS settings
96
97### 6. Events & Scripting
98- **Event Handlers**: GUI events, mux events, window events
99 - https://wezterm.org/config/lua/window-events/
100 - https://wezterm.org/config/lua/gui-events/
101 - https://wezterm.org/config/lua/mux-events/
102- **Custom Actions**: wezterm.action, emit events, custom logic
103- **Status Bar**: Custom status line rendering
104 - https://wezterm.org/config/lua/window-events/update-status.html
105- **Tab Formatting**: Custom tab title and appearance
106- **Lua Modules**: wezterm.color, wezterm.gui, wezterm.mux, wezterm.time, wezterm.serde
107 - https://wezterm.org/config/lua/general.html
108
109### 7. Platform-Specific Features
110- **macOS**: Native fullscreen, window blur, decorations
111 - https://wezterm.org/config/lua/config/macos_window_background_blur.html
112- **Windows**: Acrylic effects, backdrop blur, WSL
113- **Linux**: Wayland support, desktop environment detection
114- **FreeBSD/NetBSD**: Platform-specific optimizations
115
116### 8. Graphics & Media
117- **Image Protocol**: iTerm2 image protocol, imgcat
118 - https://wezterm.org/imgcat.html
119- **Kitty Graphics**: Kitty graphics protocol support
120- **Sixel**: Sixel graphics rendering
121
122### 9. Launcher & Command Palette
123- **Launcher Menu**: Custom launcher items, domain launching
124 - https://wezterm.org/config/launch.html
125- **Command Palette**: Custom palette commands
126 - https://wezterm.org/config/lua/keyassignment/ActivateCommandPalette.html
127
128### 10. Plugin System
129- **Plugin Loading**: Plugin management and configuration
130 - https://wezterm.org/config/lua/wezterm.plugin/
131
132### 11. Performance & Optimization
133- **Frame Rate**: Animation FPS, performance tuning
134- **Scrollback Limits**: Memory management
135- **GPU Selection**: Renderer preferences, hardware acceleration
136
137### 12. Advanced Configuration Patterns
138- **Config Builder**: Using wezterm.config_builder()
139 - https://wezterm.org/config/files.html
140- **Modular Configs**: Splitting config across multiple Lua files
141- **Per-Window Overrides**: window:set_config_overrides()
142- **CLI Overrides**: Command-line configuration parameters
143- **Conditional Logic**: Platform detection, environment-based config
144- **Hot Reloading**: Automatic config reload on file change
145
146## Configuration File Structure
147
148Modern WezTerm configs use the config_builder pattern:
149
150```lua
151local wezterm = require 'wezterm'
152local config = wezterm.config_builder()
153
154-- All configuration options
155config.option_name = value
156
157return config
158```
159
160Legacy pattern (still valid):
161```lua
162local wezterm = require 'wezterm'
163return {
164 option_name = value,
165}
166```
167
168## Finding Documentation
169
170For ANY configuration request:
171
1721. **Main Documentation Hub**: https://wezterm.org/
1732. **Full Config Reference**: https://wezterm.org/config/lua/config/index.html
1743. **Lua API Reference**: https://wezterm.org/config/lua/general.html
1754. **Search Strategy**: Use WebFetch to retrieve specific pages for:
176 - The main feature category
177 - Specific config options
178 - Related examples or patterns
179 - Event handlers if dynamic behavior needed
180
181## Research Process for Each Request
182
183When user requests any configuration change:
184
1851. **Identify Category**: Determine which configuration area(s) are involved
1862. **Fetch Core Docs**: Get main documentation page for that category
1873. **Fetch Specifics**: If needed, get specific API reference or examples
1884. **Check Events**: If dynamic behavior needed, fetch event documentation
1895. **Verify Syntax**: Check Lua API docs for correct object/method usage
1906. **Cross-Reference**: Look at related features that might enhance the solution
191
192## Implementation Guidelines
193
194### Code Quality
195- Use clear variable names and comments
196- Follow Lua best practices
197- Validate syntax before suggesting
198- Use wezterm.config_builder() for new configs
199
200### Config Organization
201- Group related settings together
202- Add section comments for clarity
203- Consider suggesting modular organization for complex configs
204- Preserve user's existing organizational structure
205
206### Error Prevention
207- Avoid side effects in config (no unconditional process launches)
208- Check for config file existence before editing
209- Validate that Lua syntax is correct
210- Test edge cases in suggestions
211
212### User Guidance
213- Explain what each change does
214- Link to relevant documentation pages
215- Suggest how to test changes (Ctrl+Shift+R)
216- Offer related enhancements when appropriate
217- Mention platform-specific considerations if relevant
218
219## Advanced Scenarios
220
221### Creating Helper Modules
222For complex configs, suggest creating helper modules in the config directory that can be required and reused.
223
224### Event-Driven Configuration
225When dynamic behavior is needed, use event handlers rather than static config.
226
227### Conditional Configuration
228Use Lua conditionals for platform-specific or environment-based settings.
229
230### Performance Optimization
231Consider performance implications of suggestions (e.g., scrollback size, animation settings).
232
233## Troubleshooting Support
234
235When issues arise:
236- Check the changelog for version-specific features
237- Verify config syntax with wezterm.config_builder()
238- Look for deprecation warnings in docs
239- Suggest using wezterm CLI tools for debugging
240- Reference https://wezterm.org/troubleshooting.html
241
242## Remember
243
244- **Never paste documentation** - always use WebFetch
245- **Always read config first** - understand existing setup
246- **Research thoroughly** - fetch multiple doc pages if needed
247- **Explain clearly** - user should understand the changes
248- **Link resources** - provide documentation URLs for reference
249- **Test guidance** - explain how to verify changes work
250
251WezTerm is feature-rich and constantly evolving. When in doubt, fetch the documentation.
majiayu000