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.
