### Example FormatItem Implementation

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

A complete example showing how to combine colors, attributes, and text in a return statement.

```lua
return {
    { Foreground = { Color = '#FF0000' } },
    { Background = { Color = '#000000' } },
    { Attribute = { Intensity = 'Bold' } },
    { Text = 'ERROR' },
    { Attribute = { Intensity = 'Normal' } },  -- Reset
}
```

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

### Execute setup function

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Configures the plugin without attaching to WezTerm events.

```lua
agent_deck.setup({ update_interval = 1000 })
```

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

### Install plugin via configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Usage of wezterm.plugin.require to load and apply a plugin.

```lua
local wezterm = require('wezterm')
local my_plugin = wezterm.plugin.require('https://github.com/owner/repo')

local config = wezterm.config_builder()
my_plugin.apply_to_config(config)

return config
```

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

### setup(opts)

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Alternative initialization function. Sets configuration without registering event handlers.

```APIDOC
## setup(opts)

### Description
Alternative initialization function. Sets configuration without registering event handlers.

### Parameters
- **opts** (table|nil) - Optional - Configuration options

### Return
None.
```

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

### Define setup function signature

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Alternative initialization method that does not register event handlers.

```lua
function M.setup(opts)
```

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

### Get configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/internal-modules.md

Defines the signature for retrieving the current configuration.

```lua
function M.get()
```

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

### Example Icon Configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/configuration.md

Demonstrates how to set the active style and provide custom overrides for specific icons.

```lua
icons = {
    style = 'emoji',
    emoji = {
        working = '🔴',
        waiting = '🟠',
    },
}
```

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

### Retrieve configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Example usage of get_config to access and print configuration values.

```lua
local config = agent_deck.get_config()
print('Update interval: ' .. config.update_interval .. 'ms')
```

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

### Configuration Merge Example

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/GUIDE.md

Demonstrates how user-provided options override specific keys while retaining default values for the remaining configuration.

```lua
-- User provides:
{ colors = { working = '#FF0000' } }

-- Merged with defaults to become:
{ 
    update_interval = 5000,  -- from default
    colors = {
        working = '#FF0000',    -- from user (overridden)
        waiting = '#E6DB74',    -- from default
        idle = '#66D9EF',       -- from default
        inactive = '#888888',   -- from default
    },
    -- ... rest of default config
}
```

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

### Set configuration overrides

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Example usage of set_config to apply configuration overrides.

```lua
agent_deck.set_config({
    colors = { waiting = '#FF0000' }
})
```

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

### Configure notification settings

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/notifications.md

Example configuration table for customizing notification behavior, backend, and display options.

```lua
notifications = {
    enabled = true,
    on_waiting = true,
    on_finished = false,
    timeout_ms = 5000,
    backend = 'terminal-notifier',
    terminal_notifier = {
        sound = 'Glass',
        title = 'Agent Alert',
        activate = true,
    },
}
```

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

### Get default configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/internal-modules.md

Defines the signature for retrieving the default configuration.

```lua
function M.get_defaults()
```

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

### Initialize WezTerm Agent Deck

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/README.md

Basic setup to load the plugin and apply default configurations to the WezTerm config builder.

```lua
local wezterm = require('wezterm')
local agent_deck = wezterm.plugin.require('https://github.com/Eric162/wezterm-agent-deck')
local config = wezterm.config_builder()

agent_deck.apply_to_config(config)

return config
```

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

### Example Notification Configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/configuration.md

Configures notification triggers and backend-specific settings for terminal-notifier on macOS.

```lua
notifications = {
    enabled = true,
    on_waiting = true,
    backend = 'terminal-notifier',
    terminal_notifier = {
        sound = 'Glass',
        title = 'Agent Alert',
        activate = true,
    },
}
```

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

### Agent Deck Configuration Structure

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/00-START-HERE.md

Example configuration object defining update intervals, colors, icons, and agent patterns.

```lua
{
    update_interval = 5000,        -- ms between checks
    colors = { working = '...', }, -- Status colors
    icons = { style = 'unicode' }, -- Icon style
    notifications = { ... },       -- Alert settings
    agents = { ... },              -- Agent patterns
    tab_title = { ... },           -- Tab display
    right_status = { ... },        -- Status bar
}
```

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

### Configure WezTerm Agent Deck

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/plans/001-wezterm-agent-deck.md

Initializes the plugin and defines agent detection patterns, UI components, and status colors. Ensure the plugin is required correctly before calling setup and apply_to_config.

```lua
local wezterm = require 'wezterm'
local agent_deck = wezterm.plugin.require('https://github.com/user/wezterm-agent-deck')

agent_deck.setup({
  -- Polling interval (ms) - default 5 seconds
  update_interval = 5000,
  
  -- Agent detection via process name matching
  agents = {
    opencode = { 
      patterns = { 'opencode' },
      -- Optional: override status detection patterns
      status_patterns = {
        working = { "Esc to interrupt", "[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]" },
        waiting = { "Esc to cancel", "Yes, allow once", "%(Y/n%)" },
        idle = { "^%s*>%s*$" }
      }
    },
    claude = { patterns = { 'claude', 'claude%-code' } },
    -- Extensible for other agents
  },
  
  -- Tab title format (composable)
  tab_title = {
    enabled = true,
    position = "left",  -- "left" or "right" of existing title
    components = {
      { type = "icon" },
      { type = "separator", text = " " },
    },
  },
  
  -- Right status (aggregate view)
  right_status = {
    enabled = true,
    components = {
      { type = "badge", filter = "waiting", label = "waiting" },
      { type = "separator", text = " | " },
      { type = "badge", filter = "working", label = "working" },
    },
  },
  
  -- Colors (auto-derived from theme if not specified)
  colors = {
    working = "green",
    waiting = "yellow", 
    idle = "blue",
    inactive = "gray",
  },
  
  -- Notifications
  notifications = {
    enabled = true,
    on_waiting = true,  -- Notify when agent needs input
    timeout_ms = 4000,
  },
  
  -- Advanced options
  cooldown_ms = 2000,  -- Anti-flicker delay
  max_lines = 100,     -- Max lines to scan for patterns
})

-- Apply to WezTerm config
agent_deck.apply_to_config(config)
```

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

### Install terminal-notifier for macOS

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/README.md

Install the external dependency required for sound notifications on macOS.

```bash
brew install terminal-notifier
```

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

### Test Plugin Logic

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Example test case using the busted framework.

```lua
-- tests/my_test.lua
describe('My Plugin', function()
    it('should merge options correctly', function()
        local result = merge_options({a = 1}, {b = 2})
        assert.are.same({a = 1, b = 2}, result)
    end)
end)
```

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

### Configure and use badge component

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

Defines the badge component for status filtering and shows a multi-component example.

```lua
{ type = 'badge', filter = 'waiting', label = 'waiting' }
```

```lua
{
    { Foreground = { Color = '#E6DB74' } },  -- waiting color
    { Text = '2 waiting' },
    { Attribute = { Intensity = 'Normal' } },
}
```

```lua
right_status = {
    components = {
        { type = 'badge', filter = 'waiting', label = 'waiting' },
        { type = 'separator', text = ' | ' },
        { type = 'badge', filter = 'working', label = 'working' },
    },
}
```

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

### Accessing Agent States

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/types.md

Examples of retrieving individual agent states or iterating through all active agent states.

```lua
local state = agent_deck.get_agent_state(123)
if state and state.status == 'waiting' then
    print('Agent ' .. state.agent_type .. ' is waiting')
end

local all = agent_deck.get_all_agent_states()
for pane_id, agent_state in pairs(all) do
    if agent_state.status == 'working' then
        print('Pane ' .. pane_id .. ' is busy')
    end
end
```

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

### Display encoded plugin path

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Example of the encoded directory name format used by WezTerm.

```text
httpssCssZssZsgithubsDscomsZsownersZsrepo
```

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

### agent_deck.setup(opts)

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/INDEX.md

Initializes the plugin with the provided configuration options.

```APIDOC
## agent_deck.setup(opts)

### Description
Initializes the plugin with the provided configuration options.

### Parameters
- **opts** (table) - Required - Configuration table containing settings like update_interval, colors, icons, and notifications.
```

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

### Update plugins manually

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Command to trigger a manual update of all installed plugins.

```lua
-- In Debug Overlay (Ctrl+Shift+L) or via action:
wezterm.plugin.update_all()
```

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

### Apply Basic Configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/00-START-HERE.md

Initializes the agent deck with custom update intervals and status colors.

```lua
agent_deck.apply_to_config(config, {
    update_interval = 500,
    colors = { working = '#A6E22E', waiting = '#E6DB74' },
})
```

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

### Implement minimal plugin entry point

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

The required structure for plugin/init.lua to expose configuration settings.

```lua
-- plugin/init.lua
local wezterm = require('wezterm')

local M = {}

--- Apply plugin configuration to WezTerm config
---@param config table WezTerm config builder
---@param opts? table Optional plugin configuration
function M.apply_to_config(config, opts)
    -- Merge user options with defaults
    opts = opts or {}
    
    -- Apply configuration changes
    config.some_setting = opts.some_setting or "default"
end

return M
```

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

### Initialize Plugin Directory Structure

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Commands to create the necessary directory structure for a new WezTerm plugin.

```bash
mkdir -p my-plugin.wezterm/plugin
cd my-plugin.wezterm
```

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

### Update pane status

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Example usage of update_pane to refresh the state of all panes in a tab.

```lua
for _, pane in ipairs(tab:panes()) do
    agent_deck.update_pane(pane)
end
```

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

### agent_deck.setup(options)

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/plans/001-wezterm-agent-deck.md

Configures the agent deck plugin with polling intervals, agent detection patterns, UI components, and notification settings.

```APIDOC
## agent_deck.setup(options)

### Description
Initializes the agent deck plugin with user-defined settings for agent detection, status monitoring, and UI presentation.

### Parameters
- **update_interval** (number) - Optional - Polling interval in milliseconds (default: 5000).
- **agents** (table) - Required - A map of agent configurations, where each key is an agent name and the value contains `patterns` (list of strings) and optional `status_patterns` (table).
- **tab_title** (table) - Optional - Configuration for the tab title display, including `enabled`, `position`, and `components`.
- **right_status** (table) - Optional - Configuration for the right status bar, including `enabled` and `components`.
- **colors** (table) - Optional - Color overrides for status states (working, waiting, idle, inactive).
- **notifications** (table) - Optional - Notification settings including `enabled`, `on_waiting`, and `timeout_ms`.
- **cooldown_ms** (number) - Optional - Anti-flicker delay in milliseconds (default: 2000).
- **max_lines** (number) - Optional - Maximum number of lines to scan for patterns.
```

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

### Get Default Patterns Function

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/internal-modules.md

Signature for the get_default_patterns function to retrieve pattern definitions.

```lua
function M.get_default_patterns()
```

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

### Initialize plugin in WezTerm config

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Standard implementation for loading the plugin and applying configuration overrides.

```lua
local wezterm = require('wezterm')
local agent_deck = wezterm.plugin.require('https://github.com/Eric162/wezterm-agent-deck')
local config = wezterm.config_builder()

agent_deck.apply_to_config(config, {
    update_interval = 500,
    colors = {
        working = '#A6E22E',
        waiting = '#E6DB74',
    },
})

return config
```

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

### Get a component renderer

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

Retrieve a registered component's renderer function by its name.

```lua
local icon_renderer = components.get('icon')
```

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

### Define Plugin Entry Point

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Basic structure for a plugin's init.lua file using the apply_to_config function.

```lua
local wezterm = require('wezterm')
local M = {}

function M.apply_to_config(config, opts)
    wezterm.log_info('My plugin loaded!')
end

return M
```

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

### Get Cached Agents Function

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/internal-modules.md

Signature for the get_cached_agents function to retrieve current cache mappings.

```lua
function M.get_cached_agents()
```

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

### agent_deck.apply_to_config(config, options)

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/README.md

Initializes the plugin and applies configuration settings to the WezTerm configuration object.

```APIDOC
## agent_deck.apply_to_config(config, options)

### Description
Applies the agent deck plugin configuration to the provided WezTerm configuration object. This is required to enable status monitoring and notifications.

### Parameters
- **config** (table) - Required - The WezTerm configuration builder object.
- **options** (table) - Optional - Configuration table containing `update_interval`, `colors`, `icons`, and `notifications` settings.
```

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

### apply_to_config(config, opts)

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Initializes the plugin and hooks into WezTerm configuration. This must be called from the WezTerm configuration file.

```APIDOC
## apply_to_config(config, opts)

### Description
Initializes the plugin and hooks into WezTerm configuration. This must be called from the WezTerm configuration file.

### Parameters
- **config** (table) - Required - WezTerm config object (from `wezterm.config_builder()`)
- **opts** (table|nil) - Optional - Configuration overrides

### Return
None. Modifies `config.status_update_interval` and registers event handlers.
```

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

### Apply full plugin configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/configuration.md

Demonstrates the complete configuration structure for the agent_deck plugin, including performance settings, agent definitions, display components, colors, icons, and notifications.

```lua
local wezterm = require('wezterm')
local agent_deck = wezterm.plugin.require('https://github.com/Eric162/wezterm-agent-deck')
local config = wezterm.config_builder()

agent_deck.apply_to_config(config, {
    -- Performance
    update_interval = 500,
    cooldown_ms = 1500,
    max_lines = 80,
    
    -- Agent detection
    enabled_agents = { 'claude', 'opencode' },
    agents = {
        custom_bot = {
            patterns = { 'custom%-bot' },
            status_patterns = {
                working = { 'computing' },
                waiting = { 'awaiting user' },
            },
        },
    },
    
    -- Display
    tab_title = {
        enabled = true,
        position = 'left',
        components = {
            { type = 'icon' },
            { type = 'separator', text = ' ' },
        },
    },
    
    right_status = {
        enabled = true,
        components = {
            { type = 'badge', filter = 'waiting', label = 'waiting' },
            { type = 'separator', text = ' | ' },
            { type = 'badge', filter = 'working', label = 'working' },
        },
    },
    
    -- Colors
    colors = {
        working = '#A6E22E',
        waiting = '#E6DB74',
        idle = '#66D9EF',
        inactive = '#888888',
    },
    
    -- Icons
    icons = {
        style = 'unicode',
        unicode = {
            working = '●',
            waiting = '◔',
            idle = '○',
            inactive = '◌',
        },
    },
    
    -- Notifications
    notifications = {
        enabled = true,
        on_waiting = true,
        on_finished = false,
        backend = 'native',
        timeout_ms = 5000,
    },
})

return config
```

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

### ANSI escape code stripping example

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/detection.md

Demonstrates the transformation of raw terminal output into clean text.

```text
Input:  "\27[32mthinking\27[0m"  (green text "thinking")
Output: "thinking"
```

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

### M.render_all(component_list, context)

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

Renders a sequence of components in order.

```APIDOC
## M.render_all(component_list, context)

### Description
Processes a list of component configurations and concatenates their rendered output.

### Parameters
- **component_list** (table) - Required - Array of component config tables
- **context** (table) - Required - Rendering context shared across components

### Returns
- **FormatItem[]** - Concatenated FormatItem array.
```

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

### Retrieve status icon

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Example usage of get_status_icon to fetch a status icon based on the status name.

```lua
local icon = agent_deck.get_status_icon('working')
-- Returns '●' (unicode), '' (nerd), or '🟢' (emoji)
```

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

### Apply Minimal Configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/INDEX.md

Applies the default configuration settings for the agent-deck plugin.

```lua
agent_deck.apply_to_config(config)  -- Uses all defaults
```

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

### Get Agent Display Name

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/notifications.md

Maps internal agent type keys to human-readable display names.

```lua
local function get_agent_display_name(agent_type)
    local agent_names = {
        opencode = 'OpenCode',
        claude = 'Claude',
        gemini = 'Gemini',
        codex = 'Codex',
        aider = 'Aider',
    }
    return agent_names[agent_type] or agent_type
end
```

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

### notify_waiting Usage Example

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/notifications.md

Trigger a notification within a status_changed event handler when an agent enters the waiting state.

```lua
wezterm.on('agent_deck.status_changed', function(window, pane, old, new, agent)
    if new == 'waiting' then
        notify_waiting(pane, agent, config)
    end
end)
```

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

### Configure and use icon component

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

Defines the icon component configuration and shows its resulting output structure.

```lua
{ type = 'icon' }
```

```lua
{
    { Foreground = { Color = '#A6E22E' } },  -- working color
    { Text = '●' },                          -- icon
    { Attribute = { Intensity = 'Normal' } },
}
```

```lua
tab_title = {
    components = {
        { type = 'icon' },
    },
}
```

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

### Apply Terminal-Notifier Configuration with Sound

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/notifications.md

Demonstrates applying the terminal-notifier configuration using the agent_deck helper function.

```lua
agent_deck.apply_to_config(config, {
    notifications = {
        enabled = true,
        backend = 'terminal-notifier',
        terminal_notifier = {
            sound = 'Glass',
            activate = true,
        },
    },
})
```

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

### Test Configuration at Runtime

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/integration-guide.md

Updates plugin configuration and triggers a refresh without requiring a full WezTerm restart.

```lua
-- In WezTerm console (Ctrl+Shift+L):
local agent_deck = wezterm.plugin.require('https://github.com/Eric162/wezterm-agent-deck')
agent_deck.set_config({ colors = { working = '#FF0000' } })

-- Then trigger update
wezterm.emit_signal('update-config')
```

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

### Manage Plugin Sessions

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Handles state serialization and file I/O by initializing plugin paths and exporting state management submodules.

```lua
local pub = {}

local function init()
    local dev = wezterm.plugin.require("https://github.com/chrisgve/dev.wezterm")
    local opts = {
        auto = true,
        keywords = { "github", "owner", "resurrect", "wezterm" },
    }
    local plugin_path = dev.setup(opts)
    
    -- Set state directory
    require("resurrect.state_manager").change_state_save_dir(
        plugin_path .. separator .. "state" .. separator
    )
    
    -- Export submodules
    pub.workspace_state = require("resurrect.workspace_state")
    pub.window_state = require("resurrect.window_state")
    pub.state_manager = require("resurrect.state_manager")
end

init()
return pub
```

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

### Apply Standard Configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/INDEX.md

Applies a custom configuration with specific update intervals, color schemes, and notification settings.

```lua
agent_deck.apply_to_config(config, {
    update_interval = 500,
    colors = { working = '#A6E22E', waiting = '#E6DB74' },
    notifications = { enabled = true, on_waiting = true },
})
```

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

### M.render(name, context, opts)

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

Renders a single component by name using the provided context and options.

```APIDOC
## M.render(name, context, opts)

### Description
Executes the render function for a specific component.

### Parameters
- **name** (string) - Required - Component type name
- **context** (table) - Required - Rendering context
- **opts** (table) - Required - Component options

### Returns
- **FormatItem[]** - Array of FormatItem tables (empty array if component not found).
```

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

### Configure Agent Deck Settings

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/README.md

Customize status check intervals, colors, icons, and notification behavior.

```lua
agent_deck.apply_to_config(config, {
    update_interval = 500,  -- ms between status checks

    colors = {
        working = '#A6E22E',   -- green: agent processing
        waiting = '#E6DB74',   -- yellow: needs input
        idle = '#66D9EF',      -- blue: ready
        inactive = '#888888',  -- gray: no agent
    },

    icons = {
        style = 'unicode',  -- or 'nerd', 'emoji'
        unicode = { working = '●', waiting = '◔', idle = '○', inactive = '◌' },
    },

    notifications = { enabled = true, on_waiting = true },
})
```

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

### Configure Plugin Options

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/INDEX.md

Override default colors and icon styles by passing a configuration table to apply_to_config.

```lua
agent_deck.apply_to_config(config, {
    colors = { working = '#A6E22E' },
    icons = { style = 'emoji' },
})
```

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

### Registering and Configuring Custom Components

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

Register custom components using the components module and apply them within the agent_deck configuration.

```lua
local components = require('components')

-- Register custom component
components.register('percentage', function(context, opts)
    local total = (context.counts.working or 0) + 
                  (context.counts.waiting or 0) + 
                  (context.counts.idle or 0)
    
    if total == 0 then return {} end
    
    local percent = math.floor((context.counts.waiting or 0) / total * 100)
    
    return {
        { Text = percent .. '%' },
    }
end)

-- Use in configuration
agent_deck.apply_to_config(config, {
    right_status = {
        components = {
            { type = 'percentage' },
        },
    },
})
```

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

### Set configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/internal-modules.md

Defines the signature for setting configuration options.

```lua
function M.set(opts)
```

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

### Reference Local Plugin

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Load a local plugin using a file URL in the main wezterm.lua configuration.

```lua
local my_plugin = wezterm.plugin.require('file:///home/user/projects/my-plugin.wezterm')
```

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

### Create Modal Keybindings

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Defines key tables and status indicators to manage modal input states within WezTerm.

```lua
local M = {}

function M.add_mode(name, key_table, status_text)
    M.key_tables[name .. '_mode'] = key_table
    M.modes[name] = { status_text = status_text }
end

function M.activate_mode(name)
    return wezterm.action.ActivateKeyTable({
        name = name .. '_mode',
        one_shot = false,
    })
end

function M.exit_mode(name)
    return wezterm.action_callback(function(window, pane)
        window:perform_action(wezterm.action.PopKeyTable, pane)
        wezterm.emit('modal.exit', name, window, pane)
    end)
end

function M.set_right_status(window, mode_name)
    local status = M.modes[mode_name].status_text
    window:set_right_status(status)
end
```

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

### M.list()

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

Returns a list of all registered component names.

```APIDOC
## M.list()

### Description
Retrieves the names of all currently registered components.

### Returns
- **table** - Array of strings representing component names.
```

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

### Load Plugin for Development

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/README.md

Manually load the plugin from a local file path during development.

```lua
-- Load locally for development
local agent_deck = dofile('/path/to/wezterm-agent-deck/plugin/init.lua')
```

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

### Define plugin configuration structure

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/types.md

Outlines the schema for the plugin configuration, including performance, detection, display, and notification settings.

```lua
{
    -- Performance
    update_interval = number,    -- ms between updates
    cooldown_ms = number,        -- anti-flicker delay
    max_lines = number,          -- max pane lines to scan
    
    -- Agent detection
    enabled_agents = table|nil,  -- whitelist of agents
    agents = {                   -- agent definitions
        [agent_name] = {
            patterns = table,
            executable_patterns = table|nil,
            argv_patterns = table|nil,
            title_patterns = table|nil,
            status_patterns = {
                working = table,
                waiting = table,
                idle = table,
            }|nil,
        }
    },
    
    -- Display
    tab_title = {
        enabled = boolean,
        position = string,    -- 'left' or 'right'
        components = table,   -- component list
    },
    
    right_status = {
        enabled = boolean,
        components = table,   -- component list
    },
    
    -- Colors
    colors = {
        working = string,   -- color name or hex
        waiting = string,
        idle = string,
        inactive = string,
    },
    
    -- Icons
    icons = {
        style = string,      -- 'unicode', 'nerd', or 'emoji'
        unicode = { ... },
        nerd = { ... },
        emoji = { ... },
    },
    
    -- Notifications
    notifications = {
        enabled = boolean,
        on_waiting = boolean,
        on_finished = boolean,
        suppress_osc_notifications = boolean,
        timeout_ms = number,
        backend = string,    -- 'native' or 'terminal-notifier'
        terminal_notifier = {
            path = string|nil,
            sound = string,
            group = string,
            title = string,
            activate = boolean,
        },
    },
}
```

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

### Agent Deck Main API Functions

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/00-START-HERE.md

Core Lua functions for initializing the plugin, querying agent states, and managing configuration.

```lua
-- Initialization
agent_deck.apply_to_config(config, opts)

-- Query state
agent_deck.get_agent_state(pane_id)           -- Single pane
agent_deck.get_all_agent_states()             -- All panes
agent_deck.count_agents_by_status()           -- Summary counts

-- Configuration
agent_deck.get_config()                       -- Current config
agent_deck.set_config(opts)                   -- Update config

-- Display
agent_deck.get_status_icon(status)            -- Get icon
agent_deck.get_status_color(status)           -- Get color
agent_deck.update_pane(pane)                  -- Manual update
```

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

### set_config(opts)

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Updates the configuration after initialization.

```APIDOC
## set_config(opts)

### Description
Updates the configuration (after initialization). Typically called before apply_to_config.

### Signature
`function M.set_config(opts)`

### Parameters
- **opts** (table|nil) - Optional - Configuration overrides

### Return Type
- **None**

### Example
```lua
agent_deck.set_config({
    colors = { waiting = '#FF0000' }
})
```
```

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

### Register and Render Components

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/internal-modules.md

The component registry manages custom UI elements. Use M.register to define components and M.render or M.render_all to display them.

```lua
M.register(name, render_fn)      -- Register custom component
M.get(name)                      -- Get component renderer
M.render(name, context, opts)    -- Render component
M.render_all(list, context)      -- Render multiple components
M.list()                         -- List registered components
```

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

### Implement Workspace Switching

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Integrates a fuzzy finder via InputSelector to allow users to switch between workspaces with custom callback actions.

```lua
function M.switch_workspace(opts)
    opts = opts or {}
    return wezterm.action_callback(function(window, pane)
        wezterm.emit('smart_workspace_switcher.workspace_switcher.start', window, pane)
        
        local choices = M.get_choices(opts)
        
        window:perform_action(
            wezterm.action.InputSelector({
                title = 'Switch Workspace',
                choices = choices,
                fuzzy = true,
                action = wezterm.action_callback(function(inner_window, inner_pane, id, label)
                    if not id then
                        wezterm.emit('smart_workspace_switcher.workspace_switcher.canceled', window, pane)
                        return
                    end
                    -- Switch workspace logic...
                    wezterm.emit('smart_workspace_switcher.workspace_switcher.chosen', window, label)
                end),
            }),
            pane
        )
    end)
end
```

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

### Configure Icon Component

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/types.md

Configuration for an icon display component.

```lua
{ type = 'icon' }
```

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

### Configure Agent Deck Conditionally

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/integration-guide.md

Apply different configurations based on the host environment using Lua.

```lua
local hostname = io.popen('hostname'):read('*l')
local enable_agent_deck = hostname:find('work') ~= nil

if enable_agent_deck then
    agent_deck.apply_to_config(config, {
        notifications = { enabled = true },
    })
else
    -- Lightweight configuration for other hosts
    agent_deck.apply_to_config(config, {
        notifications = { enabled = false },
        right_status = { enabled = false },
    })
end
```

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

### Plugin Configuration Schema

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/INDEX.md

Common configuration keys used to customize update intervals, colors, icons, and notification behavior.

```lua
{
    update_interval = 5000,           -- ms between updates
    colors = { working = '...' },     -- status colors
    icons = { style = 'unicode' },    -- icon style
    notifications = {
        enabled = true,
        on_waiting = true,
    },
    tab_title = {
        enabled = true,
        position = 'left',
    },
    agents = { /* agent definitions */ },
}
```

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

### Configure Plugin Keybindings

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Inject custom keybindings into the main configuration or expose actions for user binding.

```lua
function M.apply_to_config(config)
    config.keys = config.keys or {}
    
    table.insert(config.keys, {
        key = 'p',
        mods = 'LEADER',
        action = wezterm.action_callback(function(window, pane)
            -- Custom action
        end),
    })
end

-- Or provide action for user to bind
function M.my_action()
    return wezterm.action_callback(function(window, pane)
        -- Action logic
    end)
end
```

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

### Agent Deck API Reference

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/README.md

Available methods for querying agent states and plugin configuration.

```lua
agent_deck.get_agent_state(pane_id)      -- { agent_type, status }
agent_deck.get_all_agent_states()        -- all pane states
agent_deck.count_agents_by_status()      -- { working=N, waiting=N, ... }
agent_deck.get_status_icon(status)       -- configured icon
agent_deck.get_status_color(status)      -- configured color
agent_deck.update_pane(pane)             -- trigger detection
agent_deck.get_config()                  -- current config
```

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

### Set Windows-specific state directory

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Configure an explicit state directory for Windows to avoid permission issues.

```lua
if is_windows then
    -- Set explicit state directory with write access
    state_manager.change_state_save_dir("C:\\Users\\<user>\\wezterm-state\\")
end
```

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

### Define Component Configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/types.md

Base structure for a display component configuration.

```lua
{
    type = string,           -- component type name
    -- type-specific options follow
}
```

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

### Utilize lib.wezterm utility functions

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Access common string and file I/O utilities provided by the lib.wezterm library.

```lua
local lib = wezterm.plugin.require("https://github.com/chrisgve/lib.wezterm")

-- String utilities
local key = lib.string.hash("my-string")

-- File I/O
local success, content = lib.file_io.read_file("/path/to/file")
```

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

### Plugin Architecture Diagram

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/GUIDE.md

Visual representation of the WezTerm event loop and module hierarchy.

```text
WezTerm Event Loop
    ↓
plugin/init.lua (Main orchestration)
    ├→ Configuration Management (config.lua)
    │   └→ Deep merge, validation
    │
    ├→ Agent Detection (detector.lua)
    │   ├→ Process info inspection
    │   ├→ Pattern matching
    │   └→ Caching (1.5s TTL)
    │
    ├→ Status Detection (status.lua)
    │   ├→ Terminal output analysis
    │   ├→ ANSI stripping
    │   └→ Pattern matching
    │
    ├→ Component Rendering (components/init.lua + renderer.lua)
    │   ├→ Icon component
    │   ├→ Separator component
    │   ├→ Badge component
    │   ├→ Label component
    │   └→ Agent name component
    │
    └→ Notifications (notifications.lua)
        ├→ Native toast (WezTerm)
        └→ terminal-notifier (macOS)

State:
    agent_states[pane_id] → { agent_type, status, ... }
    waiting_notified[pane_id] → true (deduplication)
    detection_cache[pane_id] → { agent_type, timestamp }
    last_notification[pane_id] → timestamp (rate limiting)
```

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

### Project File Structure

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/README.md

Visual representation of the plugin's directory layout and module organization.

```text
plugin/
├── init.lua          # Main plugin module with public API
├── config.lua        # Configuration management
├── detector.lua      # Agent type detection
├── status.lua        # Status detection from terminal output
├── notifications.lua # Notification handling
├── renderer.lua      # Component rendering
└── components/
    └── init.lua      # Composable display components
```

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

### Identify plugin runtime directories

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Platform-specific paths where WezTerm clones plugins.

```text
~/.local/share/wezterm/plugins/  (Linux)
~/Library/Application Support/wezterm/plugins/  (macOS)
%APPDATA%\wezterm\plugins\  (Windows)
```

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

### Render a list of components

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

Process an array of component configurations to generate a concatenated list of FormatItem tables.

```lua
local items = components.render_all({
    { type = 'icon' },
    { type = 'separator', text = ' ' },
    { type = 'badge', filter = 'waiting', label = 'waiting' },
}, context)
```

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

### Detect current platform

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Identify the host operating system using the WezTerm target triple.

```lua
local function get_platform()
    local target = wezterm.target_triple
    if target:find('windows') then
        return 'windows'
    elseif target:find('darwin') then
        return 'macos'
    else
        return 'linux'
    end
end
```

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

### Custom Plugin Configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/integration-guide.md

Applies specific settings for update intervals, icon styles, colors, and notification backends.

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

agent_deck.apply_to_config(config, {
    update_interval = 500,
    icons = { style = 'emoji' },
    colors = {
        working = '#A6E22E',
        waiting = '#E6DB74',
    },
    notifications = {
        enabled = true,
        on_waiting = true,
        backend = 'terminal-notifier',
    },
})
```

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

### Configure Agent Keybindings

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/integration-guide.md

Registers a keybinding to display agent status counts via a toast notification.

```lua
config.keys = {
    -- Show agent status in a tooltip
    {
        key = 'a',
        mods = 'SUPER',
        action = wezterm.action_callback(function(window, pane)
            local counts = agent_deck.count_agents_by_status()
            local msg = string.format(
                'Working: %d | Waiting: %d | Idle: %d',
                counts.working, counts.waiting, counts.idle
            )
            window:toast_notification('Agent Status', msg, nil, 2000)
        end),
    },
}
```

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

### Full Status Bar Configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

A comprehensive status bar configuration displaying multiple badges separated by text.

```lua
right_status = {
    components = {
        { type = 'badge', filter = 'waiting', label = 'waiting' },
        { type = 'separator', text = ' | ' },
        { type = 'badge', filter = 'working', label = 'working' },
        { type = 'separator', text = ' | ' },
        { type = 'badge', filter = 'idle', label = 'idle' },
    },
}
```

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

### Project Directory Structure

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/plans/001-wezterm-agent-deck.md

The file hierarchy for the wezterm-agent-deck plugin, highlighting the separation of configuration, detection logic, and UI components.

```text
wezterm-agent-deck/
├── plugin/
│   ├── init.lua              # Entry point, setup(), apply_to_config()
│   ├── config.lua            # Configuration management & defaults
│   ├── detector.lua          # Agent detection via process info
│   ├── status.lua            # Status detection via pane text patterns
│   ├── components/
│   │   ├── init.lua          # Component registry
│   │   ├── icon.lua          # Status icon (●/◐/○)
│   │   ├── label.lua         # Text label
│   │   ├── badge.lua         # Count badge
│   │   └── separator.lua     # Visual separator
│   ├── renderer.lua          # Composable format string rendering
│   └── notifications.lua     # Toast notification manager
├── .luarc.json              # Lua language server config
├── .stylua.toml             # Lua formatter config
├── README.md                # Usage documentation
└── plans/
    └── 001-wezterm-agent-deck.md  # This document
```

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

### Define plugin directory layout

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Standard directory structure for a WezTerm plugin project.

```text
my-plugin.wezterm/
├── plugin/
│   └── init.lua          # Required entry point
│   └── module1.lua       # Optional sub-modules
│   └── module2.lua
├── examples/             # Optional examples
├── .luarc.json          # Optional LSP config
├── .stylua.toml         # Optional formatter config
├── LICENSE              # Recommended
└── README.md            # Documentation
```

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

### lib.wezterm Utility Functions

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Provides common utility functions for string manipulation, file I/O, table operations, platform detection, and window sizing.

```APIDOC
## lib.wezterm

### Description
Common utility functions for plugin development including string, file I/O, table, and window utilities.

### Usage
```lua
local lib = wezterm.plugin.require("https://github.com/chrisgve/lib.wezterm")

-- String utilities
local key = lib.string.hash("my-string")

-- File I/O
local success, content = lib.file_io.read_file("/path/to/file")
```
```

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

### Configure and use label component

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

Defines the label component with format placeholders and max width constraints.

```lua
{ type = 'label', format = '{status}: {agent_type}', max_width = 20 }
```

```lua
{
    { Foreground = { Color = '#A6E22E' } },  -- status color
    { Text = 'working: claude' },
    { Attribute = { Intensity = 'Normal' } },
}
```

```lua
{ type = 'label', format = '[{agent_type}] {status}', max_width = 15 }
```

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

### Configure .luarc.json for workspace

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/002-wezterm-plugin.md

Set up the Lua Language Server workspace configuration to include WezTerm plugin paths and globals.

```json
{
    "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
    "runtime.version": "Lua 5.4",
    "workspace.library": [
        "~/.local/share/wezterm/plugins"
    ],
    "diagnostics.globals": ["wezterm"]
}
```

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

### Debug Foreground Process Information

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/integration-guide.md

Log process details to verify agent detection.

```lua
wezterm.on('update-status', function(window, pane)
    local success, info = pcall(function()
        return pane:get_foreground_process_info()
    end)
    if success and info then
        wezterm.log_info('Exe: ' .. (info.executable or 'nil'))
        wezterm.log_info('Name: ' .. (info.name or 'nil'))
        wezterm.log_info('Argv: ' .. table.concat(info.argv or {}, ' '))
    end
end)
```

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

### Define regex patterns for tool detection in Go

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/001-code-squad-agent-deck.md

Maps tool names to a slice of compiled regular expressions for fallback content matching.

```go
var toolDetectionPatterns = map[string][]*regexp.Regexp{
    "claude": {
        regexp.MustCompile(`(?i)claude`),
        regexp.MustCompile(`(?i)anthropic`),
    },
    "gemini": {
        regexp.MustCompile(`(?i)gemini`),
        regexp.MustCompile(`(?i)google ai`),
    },
    // ...
}
```

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

### Define waiting patterns

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/detection.md

List of strings indicating the agent requires user input.

```lua
'esc to cancel', 'yes, allow once', 'yes, allow always',
'allow once', 'allow always', 'deny',
'no, and tell', 'do you trust', 'run this command',
'execute this', 'continue?', 'proceed?',
'(y/n)', '(Y/n)', '[y/n]', '[Y/n]',
'(y/N)', '(Y/N)', '[y/N]', '[Y/N]',
'approve this plan', 'do you want to proceed',
'press enter to continue',
'enter confirm', 'esc dismiss', 'type your own answer',  -- Plan mode
```

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

### Define apply_to_config function signature

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

The primary entry point for plugin initialization within the WezTerm configuration.

```lua
function M.apply_to_config(config, opts)
```

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

### Simple Tab Title Configuration

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/components.md

A basic tab title configuration using an icon and a separator.

```lua
tab_title = {
    position = 'left',
    components = {
        { type = 'icon' },
        { type = 'separator', text = ' ' },
    },
}
```

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

### apply_to_config(config, opts)

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/INDEX.md

Applies the agent deck plugin to the provided WezTerm configuration object. Accepts an optional table for custom colors, icons, and agent definitions.

```APIDOC
## apply_to_config(config, opts)

### Description
Integrates the agent deck functionality into the WezTerm configuration. This is the primary entry point for initializing the plugin.

### Parameters
- **config** (table) - Required - The WezTerm configuration object.
- **opts** (table) - Optional - Configuration options including 'colors', 'icons', and 'agents' definitions.

### Example
```lua
local agent_deck = wezterm.plugin.require('https://github.com/Eric162/wezterm-agent-deck')
agent_deck.apply_to_config(config, {
    colors = { working = '#A6E22E' },
    agents = {
        my_agent = {
            patterns = { 'my%-agent' },
            status_patterns = { working = { 'thinking' } },
        },
    }
})
```
```

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

### Configure Package Path

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/internal-modules.md

Configures the Lua module path to include the plugin directory.

```lua
local function setup_package_path()
```

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

### Detect Waiting and Prompt States

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/001-code-squad-agent-deck.md

Checks for permission prompts, input indicators, and confirmation questions to determine if the agent is waiting for user interaction.

```go
// Permission prompts (normal mode)
permissionPrompts := []string{
    "No, and tell Claude what to do differently",  // Most reliable
    "Yes, allow once",
    "Yes, allow always",
    "❯ Yes",
    "❯ No",
    "Do you trust the files in this folder?",
    "Run this command?",
}

// Input prompt (--dangerously-skip-permissions mode)
// Claude shows just ">" when waiting for next input
cleanLastLine := StripANSI(lastLine)
if cleanLastLine == ">" || cleanLastLine == "> " {
    return true  // Waiting for input
}

// Y/n confirmation prompts
questionPrompts := []string{
    "Continue?", "Proceed?",
    "(Y/n)", "(y/N)", "[Y/n]", "[y/N]",
}
```

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

### Define get_config function

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/public-api.md

Function signature for retrieving the current configuration.

```lua
function M.get_config()
```

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

### Implement State Machine Logic

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/research/001-code-squad-agent-deck.md

Manages state transitions using a cooldown-based approach to differentiate between active, idle, and waiting states.

```go
// Cooldown-based state transitions
const activityCooldown = 2 * time.Second

func (s *Session) GetStatus() (string, error) {
    // 1. Check busy indicator first (immediate GREEN)
    if s.hasBusyIndicator(content) {
        return "active", nil
    }
    
    // 2. Check activity timestamp for sustained activity
    if sustainedActivity {
        return "active", nil
    }
    
    // 3. Check cooldown (2 seconds since last change)
    if time.Since(s.stateTracker.lastChangeTime) < activityCooldown {
        return "active", nil
    }
    
    // 4. Cooldown expired → waiting or idle
    if s.stateTracker.acknowledged {
        return "idle", nil   // User has seen it (gray)
    }
    return "waiting", nil    // Needs attention (yellow)
}
```

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

### Configure Native WezTerm Notifications

Source: https://github.com/eric162/wezterm-agent-deck/blob/main/_autodocs/notifications.md

Sets the notification backend to the built-in WezTerm toast system.

```lua
notifications = {
    backend = 'native',
    timeout_ms = 4000,  -- Display duration
}
```