> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# 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()`:

```lua theme={null}
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

```lua theme={null}
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

```bash theme={null}
rm -rf ~/.cache/wezterm/plugins/
```

## Creating Plugins

A basic plugin structure:

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

### plugin/init.lua

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
-- 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

```lua theme={null}
-- 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

<Tip>
  **Version Your Plugins**: Use Git tags to version your plugins for stability.
</Tip>

<Tip>
  **Document Configuration**: Provide clear documentation for plugin configuration options.
</Tip>

<Warning>
  Plugins execute arbitrary Lua code. Only install plugins from trusted sources.
</Warning>

### Plugin Documentation Template

````markdown theme={null}
# 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

```lua theme={null}
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:

```lua theme={null}
config.debug_key_events = true
```

Check the WezTerm log for plugin errors:

```bash theme={null}
tail -f ~/.local/share/wezterm/wezterm.log
```

## Advanced Plugin Features

### Event Handlers

```lua theme={null}
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

```lua theme={null}
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](/lua/config/overview)
* [Event System](/lua/events/overview)
* [Key Bindings](/config/keys)