Plugins

Extend WezTerm functionality with Lua plugins

Overview

WezTerm’s plugin system allows you to extend functionality by loading Lua modules from external sources. Plugins can provide color schemes, custom key bindings, status bar widgets, and more.

Installing Plugins

Plugins are loaded using wezterm.plugin.require():

local wezterm = require 'wezterm'
local plugin = wezterm.plugin

local status = plugin.require('https://github.com/username/plugin-name')

Plugin Sources

Plugins can be loaded from:

• GitHub repositories: https://github.com/username/repo
• Git URLs: https://gitlab.com/username/repo.git
• Local paths: file:///home/user/my-plugin

Example: Loading from GitHub

local wezterm = require 'wezterm'
local smart_splits = wezterm.plugin.require('https://github.com/mrjones2014/smart-splits.nvim')

Plugin Cache

Plugins are cached locally to avoid repeated downloads:

• Linux/macOS: ~/.cache/wezterm/plugins/
• Windows: %LOCALAPPDATA%\wezterm\plugins\

Clearing Plugin Cache

rm -rf ~/.cache/wezterm/plugins/

Creating Plugins

A basic plugin structure:

my-plugin/
├── plugin/
│   └── init.lua
└── README.md

plugin/init.lua

local wezterm = require 'wezterm'

local M = {}

function M.apply_to_config(config)
  config.color_scheme = 'MyCustomScheme'
  
  config.colors = {
    foreground = '#e0e0e0',
    background = '#1a1a1a',
  }
end

return M

Using the Plugin

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

local my_plugin = wezterm.plugin.require('https://github.com/username/my-plugin')
my_plugin.apply_to_config(config)

return config

Example Plugins

Status Bar Plugin

-- plugin/init.lua
local wezterm = require 'wezterm'

local M = {}

function M.setup(config)
  wezterm.on('update-status', function(window, pane)
    local date = wezterm.strftime '%Y-%m-%d %H:%M:%S'
    window:set_right_status(wezterm.format {
      { Attribute = { Intensity = 'Bold' } },
      { Foreground = { Color = '#74c7ec' } },
      { Text = date },
    })
  end)
end

return M

Color Scheme Plugin

-- plugin/init.lua
local M = {}

M.colors = {
  nord = {
    foreground = '#d8dee9',
    background = '#2e3440',
    cursor_bg = '#d8dee9',
    cursor_border = '#d8dee9',
    cursor_fg = '#2e3440',
    selection_bg = '#4c566a',
    selection_fg = '#d8dee9',
    ansi = {
      '#3b4252', '#bf616a', '#a3be8c', '#ebcb8b',
      '#81a1c1', '#b48ead', '#88c0d0', '#e5e9f0',
    },
    brights = {
      '#4c566a', '#bf616a', '#a3be8c', '#ebcb8b',
      '#81a1c1', '#b48ead', '#8fbcbb', '#eceff4',
    },
  },
}

function M.apply_to_config(config, scheme_name)
  if M.colors[scheme_name] then
    config.colors = M.colors[scheme_name]
  end
end

return M

Plugin Best Practices

Version Your Plugins: Use Git tags to version your plugins for stability.

Document Configuration: Provide clear documentation for plugin configuration options.

Plugins execute arbitrary Lua code. Only install plugins from trusted sources.

Plugin Documentation Template

# My WezTerm Plugin

Description of what the plugin does.

## Installation

```lua
local wezterm = require 'wezterm'
local my_plugin = wezterm.plugin.require('https://github.com/username/my-plugin')

Configuration

my_plugin.setup({
  option1 = 'value1',
  option2 = 'value2',
})

Options

• option1 - Description
• option2 - Description

## Plugin Distribution

### Publishing on GitHub

1. Create a repository with the plugin structure
2. Add documentation in README.md
3. Tag releases with semantic versioning
4. Share the repository URL

### Loading Specific Versions

```lua
local plugin = wezterm.plugin.require('https://github.com/username/plugin@v1.0.0')

Debugging Plugins

Enable debug logging:

config.debug_key_events = true

Check the WezTerm log for plugin errors:

tail -f ~/.local/share/wezterm/wezterm.log

Advanced Plugin Features

Event Handlers

local M = {}

function M.setup()
  wezterm.on('window-config-reloaded', function(window, pane)
    window:toast_notification('WezTerm', 'Configuration reloaded!', nil, 3000)
  end)
end

return M

Custom Key Bindings

local M = {}

function M.apply_to_config(config)
  table.insert(config.keys, {
    key = 'Space',
    mods = 'LEADER',
    action = wezterm.action.ShowLauncher,
  })
end

return M

See Also

• Lua Configuration Overview
• Event System
• Key Bindings