### Install pre-commit hooks

Source: https://github.com/drkjeff16/wezterm-types/blob/main/CONTRIBUTING.md

Run this command to install the pre-commit hooks defined in .pre-commit-config.yaml. After installation, hooks run automatically on every git commit.

```bash
pre-commit install
```

--------------------------------

### Install wezterm-types via LuaRocks

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types.txt

Install wezterm-types globally or locally using LuaRocks. The local install is useful for user-level configurations.

```bash
luarocks install wezterm-types # Global install
luarocks install --local wezterm-types # Local install
```

--------------------------------

### Import wez-tmux locally

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.wez-tmux.txt

Use this snippet if you have installed the wez-tmux plugin locally.

```lua
---@type WezTmux
local wez_tmux = require("wez-tmux.plugin")
```

--------------------------------

### Configure lazydev.nvim for wez-tmux

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.wez-tmux.txt

Add this configuration to your lazydev.nvim setup to ensure the editor recognizes the wezterm and wez-tmux types.

```lua
{
  'folke/lazydev.nvim',
  ft = 'lua',
  dependencies = { 'DrKJeff16/wezterm-types' },
  opts = {
    library = {
      -- Other library configs...
      { path = 'wezterm-types', mods = { 'wezterm' } },
      { path = 'wez-tmux', mods = { 'wez-tmux' } },
    },
  },
}
```

--------------------------------

### lazydev.nvim setup with custom directory name

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types.txt

Alternative lazydev.nvim configuration when the wezterm-types repository is downloaded under a different directory name. The path in the library table must match the custom directory name exactly.

```lua
{
  'folke/lazydev.nvim',
  ft = 'lua',
  dependencies = {
    {
      'DrKJeff16/wezterm-types',
      name = '<my_custom_name>', -- CUSTOM DIRECTORY NAME
    },
  },
  opts = {
    library = {
      -- MAKE SURE TO MATCH THE PLUGIN DIRECTORY'S NAME
      { path = '<my_custom_name>', mods = { 'wezterm' } },
    },
  },
}
```

--------------------------------

### Configure lazydev.nvim with wezterm-types and wez-pain-control

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.wez-pain-control.txt

Add this to your lazydev.nvim setup to include the wezterm-types and wez-pain-control libraries. This enables type annotations for both wezterm and wez-pain-control modules when using lazydev.nvim.

```lua
{
  'folke/lazydev.nvim',
  ft = 'lua',
  dependencies = { 'DrKJeff16/wezterm-types' },
  opts = {
    library = {
      -- Other library configs...
      { path = 'wezterm-types', mods = { 'wezterm' } },
      { path = 'wez-pain-control', mods = { 'wez-pain-control' } },
    },
  },
}
```

--------------------------------

### Import Quick_Select type from quickselect.wezterm

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.quickselect.txt

Use this Lua snippet to import the Quick_Select type annotation for the quickselect.wezterm plugin. It requires the plugin to be installed and available via wezterm.plugin.require.

```lua
---@type Quick_Select
local quickselect = wezterm.plugin.require("https://github.com/quantonganh/quickselect.wezterm")
```

--------------------------------

### Install wezterm-types with lazy.nvim

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types.txt

Add wezterm-types as a lazy.nvim plugin in Neovim. The version is set to false to always fetch the latest version.

```lua
{
  'DrKJeff16/wezterm-types',
  version = false, -- Get the latest version
},
```

--------------------------------

### lua_ls workspace library configuration

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types.txt

Neovim LSP configuration for lua-language-server to include the wezterm-types install path in the workspace library. Add the path to the Lua.workspace.library table to enable type checking and autocompletion for WezTerm configuration files.

```lua
return {
  cmd = { 'lua-language-server' },
  filetypes = { 'lua' },
  settings = {
    Lua = {
      workspace = {
        library = {
          -- Other library paths...
          '</path/to/wezterm-types>',
        },
      },
    },
  },
}
```

--------------------------------

### lazydev.nvim setup with wezterm-types

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types.txt

Configuration for folke/lazydev.nvim to use wezterm-types as a library for the wezterm module. Add this to your Neovim plugin configuration to enable type checking and autocompletion for WezTerm configuration files.

```lua
{
  'folke/lazydev.nvim',
  ft = 'lua',
  dependencies = { 'DrKJeff16/wezterm-types' },
  opts = {
    library = {
      -- Other library configs...
      { path = 'wezterm-types', mods = { 'wezterm' } },
    },
  },
}
```

--------------------------------

### Import AICommander type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.ai-commander.txt

Use this snippet to import the AICommander type annotation for the dimao/ai-commander.wezterm plugin. It requires the plugin to be installed and accessible via wezterm.plugin.require.

```lua
---@type AICommander
local ai_commander = wezterm.plugin.require("https://github.com/dimao/ai-commander.wezterm")
```

--------------------------------

### WezTerm configuration with type annotations

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types.txt

Example of a WezTerm Lua configuration file that uses the wezterm-types annotations. It requires the wezterm module and sets the window_decorations option. The annotations enable the Lua Language Server to provide type checking and autocompletion for WezTerm configuration options.

```lua
-- WezTerm configuration
local wezterm = require("wezterm") ---@type Wezterm
local config = wezterm.config_builder()

config.window_decorations = "RESIZE|MACOS_FORCE_DISABLE_SHADOW"

return config
```

--------------------------------

### Example commit message for plugin annotations

Source: https://github.com/drkjeff16/wezterm-types/blob/main/CONTRIBUTING.md

Commit message format for adding type annotations to a plugin. Use the conventional commit style with the plugin name in the scope.

```text
feat(plugins.PLUGIN-NAME): add type annotations
```

--------------------------------

### Import SyncPanes type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.sync-panes.txt

Import the SyncPanes type annotation for the sync-panes.wez plugin. Use this to get type checking and autocompletion for the plugin's API in your WezTerm configuration.

```lua
---@type SyncPanes
local sync_panes = wezterm.plugin.require("https://github.com/annie444/sync-panes.wez")
```

--------------------------------

### Import PinnedTabs type annotations

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.pinned-tabs.txt

Import type annotations for the pinned-tabs.wezterm plugin. Use this to get type checking for the plugin's API in your WezTerm configuration.

```lua
---@type PinnedTabs
local pinned_tabs = wezterm.plugin.require("https://github.com/selectnull/pinned-tabs.wezterm")
```

--------------------------------

### Alias with multiple types using newlines

Source: https://github.com/drkjeff16/wezterm-types/blob/main/CONTRIBUTING.md

Shows how to define an alias with multiple types using newlines with ---| separators. This example lists choices from "0" to "33".

```lua
---@alias MyChoices
---|"0"
---|"1"
---|"2"
---|"3"
---|"4"
---|"5"
---|"6"
---|"7"
---|"8"
---|"9"
---|"10"
---|"11"
---|"12"
---|"13"
---|"14"
---|"15"
---|"16"
---|"17"
---|"18"
---|"19"
---|"20"
---|"21"
---|"22"
---|"23"
---|"24"
---|"25"
---|"26"
---|"27"
---|"28"
---|"29"
---|"30"
---|"31"
---|"32"
---|"33"
```

--------------------------------

### Import WeztermAttention type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.attention.txt

Import the WeztermAttention type annotation for the pro-vi/wezterm-attention plugin. Use this to get type checking and autocompletion for the attention plugin in your Wezterm Lua configuration.

```lua
---@type WeztermAttention
local attention = wezterm.plugin.require("https://github.com/pro-vi/wezterm-attention")
```

--------------------------------

### Run new-plugin.sh helper script

Source: https://github.com/drkjeff16/wezterm-types/blob/main/CONTRIBUTING.md

Execute the new-plugin.sh script to scaffold files for a new plugin. The script creates Lua, Markdown, and Vimdoc files and inserts a placeholder in metadata/plugins.json.

```bash
./scripts/new-plugin.sh PLUGIN-NAME # ONLY DASHES `-` ALLOWED!
```

--------------------------------

### Import QuickDomains type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.quick-domains.txt

Use this snippet to annotate the result of wezterm.plugin.require for the quick_domains.wezterm plugin. The type annotation is QuickDomains.

```lua
---@type QuickDomains
local quick_domains = wezterm.plugin.require("https://github.com/DavidRR-F/quick_domains.wezterm")
```

--------------------------------

### Import wezterm-config.nvim type annotations

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.wezterm-config.txt

Use the wezterm.plugin.require function to import the type annotations for the wezterm-config.nvim plugin.

```lua
---@type weztermConfig
local wezterm_config_nvim = wezterm.plugin.require('https://github.com/winter-again/wezterm-config.nvim')
```

--------------------------------

### Require smart_workspace_switcher.wezterm with SWS type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.smart-workspace-switcher.txt

Use to load the plugin and enable type hints. Requires wezterm.plugin environment.

```lua
---@type SWS
local sws = wezterm.plugin.require("https://github.com/MLFlexer/smart_workspace_switcher.wezterm")
```

--------------------------------

### Avoid redundant aliases

Source: https://github.com/drkjeff16/wezterm-types/blob/main/CONTRIBUTING.md

Discourages creating redundant aliases. The first block shows an example of what not to do; the second block shows redundant aliases that should be avoided.

```lua
---PLEASE DON'T DO THIS!

---WRONG
---@alias StringArr string[]
---@alias StringArrDict table<string, StringArr>

---Redundant...
---@alias Foo { foo: 'bar' }
---@alias FooList Foo[]
---...
```

```lua
---DON'T DO THIS OH GOD
---@alias MyTable table

---I've seen these types in other projects,
---way more than what my soul can handle...
---@alias Int integer
---@alias Bool boolean
---@alias Str string
```

--------------------------------

### Import StackWez type from stack.wez plugin

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.stack.txt

Use this snippet to import the StackWez type annotation from the stack.wez plugin. It requires the plugin to be installed and available via wezterm.plugin.require().

```lua
---@type StackWez
local stack_wez = wezterm.plugin.require("https://github.com/bad-noodles/stack.wez")
```

--------------------------------

### Import wezterm-sync with Sync type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.sync.txt

Use this snippet to import the wezterm-sync plugin and annotate it with the Sync type. The annotation is applied to the local variable returned by wezterm.plugin.require.

```lua
---@type Sync
local sync = wezterm.plugin.require("https://github.com/dfsramos/wezterm-sync")
```

--------------------------------

### Regenerate plugin indexes and panvimdoc workflow

Source: https://github.com/drkjeff16/wezterm-types/blob/main/CONTRIBUTING.md

Run this command to regenerate the plugin indexes and the panvimdoc workflow. It updates generated sections in README.md and docs/README.md, plus .github/workflows/panvimdoc_plugins.yml. Do not edit those generated sections by hand.

```bash
./scripts/plugin-maintenance.sh generate
```

--------------------------------

### Import Sessionizer type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.sessionizer.txt

Import the Sessionizer type annotation for the mikkasendke/sessionizer.wezterm plugin. Use this to get type checking and autocompletion for the plugin's API in your WezTerm configuration.

```lua
---@type Sessionizer
local sessionizer = wezterm.plugin.require("https://github.com/mikkasendke/sessionizer.wezterm")
```

--------------------------------

### Import WezPainControl type for local plugin

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.wez-pain-control.txt

Use this snippet to import the WezPainControl type annotation when the plugin is installed locally and required directly. This is an alternative to the remote require method.

```lua
---@type WezPainControl
local wez_pain_control = require("wez-pain-control.plugin")
```

--------------------------------

### Import log.wz plugin with type annotations

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.log.txt

Use this snippet to import the sravioli/log.wz plugin with type annotations. The `---@type Log.API` annotation provides type checking for the plugin API.

```lua
---@type Log.API
local log = wezterm.plugin.require("https://github.com/sravioli/log.wz")
```

--------------------------------

### Run local validation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/CONTRIBUTING.md

Run this command to validate the maintenance configuration, manifest schema and order, plugin inventory, and generated files for freshness.

```bash
./scripts/plugin-maintenance.sh validate
```

--------------------------------

### Create a new branch for plugin annotations

Source: https://github.com/drkjeff16/wezterm-types/blob/main/CONTRIBUTING.md

Create a new branch for adding type annotations to a plugin. Use a branch name prefixed with 'feat/' and the plugin name.

```bash
git checkout -b feat/PLUGIN-NAME
```

--------------------------------

### Importing AgentDeck types

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.agent-deck.txt

Use this snippet to import the AgentDeck plugin and apply the type annotation for proper IDE autocompletion.

```lua
---@type AgentDeck
local agent_deck = wezterm.plugin.require("https://github.com/Eric162/wezterm-agent-deck")
```

--------------------------------

### Class definition with public fields

Source: https://github.com/drkjeff16/wezterm-types/blob/main/CONTRIBUTING.md

Shows how to define a class with all public elements using ---@class and ---@field annotations.

```lua
---@class MyClass
---@field foo string
---@field bar? boolean
```

--------------------------------

### Import type annotations from a GitHub repository with wezterm.plugin.require

Source: https://github.com/drkjeff16/wezterm-types/blob/main/scripts/template.md

Use this Lua snippet to import type annotations for a GitHub repository. The repository is specified as a URL in the format https://github.com/username/repository. The wezterm.plugin.require function loads the plugin and assigns it to a local variable annotated with ---@type Template.

```lua
---@type Template
local template = wezterm.plugin.require("https://github.com/username/repository")
```

--------------------------------

### Import Ribbon.Api type for ribbon.wz plugin

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.ribbon.txt

Use this Lua snippet to import the Ribbon.Api type annotation for the ribbon.wz plugin. The type is provided by wezterm-types and should be used with wezterm.plugin.require.

```lua
---@type Ribbon.Api
local ribbon = wezterm.plugin.require("https://github.com/sravioli/ribbon.wz")
```

--------------------------------

### Import wsinit.wezterm type annotations

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.wsinit.txt

Use this Lua snippet to import type annotations for the wsinit.wezterm plugin. It declares the variable as WsInit and requires the plugin from its GitHub repository.

```lua
---@type WsInit
local wsinit = wezterm.plugin.require("https://github.com/JuanraCM/wsinit.wezterm")
```

--------------------------------

### Import CmdPicker type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.cmdpicker.txt

Use this snippet to load the wezterm-cmdpicker plugin and annotate the returned object with the CmdPicker type. The annotation is provided by the wezterm-types package.

```lua
---@type CmdPicker
local picker = wezterm.plugin.require("https://github.com/abidibo/wezterm-cmdpicker")
```

--------------------------------

### Import ModalWezterm type for MLFlexer/modal.wezterm

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.modal.txt

Use this Lua snippet to require the MLFlexer/modal.wezterm plugin with the ModalWezterm type annotation, enabling type checking in editors that support Lua language servers.

```lua
---@type ModalWezterm
local modal = wezterm.plugin.require("https://github.com/MLFlexer/modal.wezterm")
```

--------------------------------

### Import AIHelper type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.ai-helper.txt

Use this snippet to import the AIHelper type from the ai-helper.wezterm plugin. The type annotation is applied to the result of wezterm.plugin.require.

```lua
---@type AIHelper
local ai_helper = wezterm.plugin.require("https://github.com/Michal1993r/ai-helper.wezterm")
```

--------------------------------

### Import SmartSplitsWezterm type

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.smart-splits.txt

Use this Lua type annotation to import the SmartSplitsWezterm type for the smart-splits.nvim plugin. The annotation is placed before the require call.

```lua
---@type SmartSplitsWezterm
local smart_splits = wezterm.plugin.require("https://github.com/mrjones2014/smart-splits.nvim")
```

--------------------------------

### Import battery.wez plugin with type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.battery.txt

Use this snippet to load the rootiest/battery.wez plugin with a type annotation for the battery module. The annotation enables type checking for the battery object in Lua.

```lua
---@type BatteryWez
local battery = wezterm.plugin.require("https://github.com/rootiest/battery.wez")
```

--------------------------------

### Import Pivot type from pivot_panes.wezterm

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.pivot-panes.txt

Use this snippet to import the Pivot type annotation for the pivot_panes.wezterm plugin. The plugin is required via wezterm.plugin.require with the GitHub URL.

```lua
---@type Pivot
local pivot = wezterm.plugin.require("https://github.com/ChrisGVE/pivot_panes.wezterm")
```

--------------------------------

### Import Replay type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.replay.txt

Use this Lua snippet to import the Replay type annotation for the btrachey/wezterm-replay plugin. It requires the plugin via wezterm.plugin.require and assigns it to a local variable typed as Replay.

```lua
---@type Replay
local replay = wezterm.plugin.require("https://github.com/btrachey/wezterm-replay")
```

--------------------------------

### Import lib.wezterm type annotations

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.lib.txt

Import type annotations for the ChrisGVE/lib.wezterm plugin. The @type annotation enables IDE type checking for the lib variable.

```lua
---@type LibWezterm
local lib = wezterm.plugin.require("https://github.com/ChrisGVE/lib.wezterm")
```

--------------------------------

### Import QuotaLimit type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.quota-limit.txt

Use this Lua code to import the `QuotaLimit` type annotation from the wezterm-types plugin. It requires the `EdenGibson/wezterm-quota-limit` plugin and assigns the result to a local variable `ql`.

```lua
---@type QuotaLimit
local ql = wezterm.plugin.require("https://github.com/EdenGibson/wezterm-quota-limit")
```

--------------------------------

### Import PresentationWez type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.presentation.txt

Use this Lua snippet to require the xarvex/presentation.wez plugin and annotate the local variable with the PresentationWez type. This enables type checking and autocompletion for the plugin's API.

```lua
---@type PresentationWez
local presentation = wezterm.plugin.require("https://github.com/xarvex/presentation.wez")
```

--------------------------------

### Import Chord type from chord.wz

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.chord.txt

Use this Lua snippet to import the Chord type annotation from the sravioli/chord.wz plugin. It requires the wezterm plugin system and the plugin URL.

```lua
---@type Chord
local chord = wezterm.plugin.require("https://github.com/sravioli/chord.wz")
```

--------------------------------

### Import ThemeRotator type annotation

Source: https://github.com/drkjeff16/wezterm-types/blob/main/doc/wezterm-types-plugin.wezterm-theme-rotator.txt

Use this Lua snippet to annotate the theme rotator plugin as ThemeRotator when requiring it via wezterm.plugin.require.

```lua
---@type ThemeRotator
local theme_rotator = wezterm.plugin.require("https://github.com/koh-sh/wezterm-theme-rotator")
```