### Setup Plugin Location Resolution with dev.wezterm in Lua

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

This example shows how to use the `dev.wezterm` library to resolve plugin paths during development and deployment. It covers setting up options like keywords and auto-package path configuration, and then requiring sub-modules.

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

function M.init()
    local opts = {
        keywords = { "https", "owner", "my_plugin" },
        auto = true,  -- Auto-setup package.path
    }
    local plugin_dir = dev.setup(opts)
    
    -- Now sub-modules can be required
    local module1 = require("module1")
end
```

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

### Initialize WezTerm Agent Deck Plugin

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

Basic setup to load and apply the agent deck plugin to the WezTerm configuration.

```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
```

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

### Installing WezTerm Plugins (Lua)

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

Demonstrates how to install and integrate WezTerm plugins using `wezterm.plugin.require()`. This function supports installation from Git URLs (e.g., GitHub, GitLab) and local file paths for development purposes.

```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

```

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

### Basic WezTerm Agent Deck Setup (Lua)

Source: https://context7.com/eric162/wezterm-agent-deck/llms.txt

Applies the WezTerm Agent Deck plugin to your WezTerm configuration using default settings. This is the simplest way to integrate the plugin.

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

-- Apply with default settings
agent_deck.apply_to_config(config)

return config
```

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

### WezTerm Agent Deck Component Examples

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

This Lua code illustrates various component configurations for the WezTerm Agent Deck plugin's status displays. It shows how to use different styles for icons, apply filters to badges, and create custom text labels with dynamic formatting. These components are building blocks for visual feedback in WezTerm.

```lua
-- Icon with different styles
{ type = "icon", style = "nerd" }     -- Nerd font icons
{ type = "icon", style = "unicode" }  -- Unicode symbols (●◐○)
{ type = "icon", style = "emoji" }    -- Emoji (🟢🟡🔵⚫)

-- Badge with filters
{ type = "badge", filter = "waiting", label = "!" }
{ type = "badge", filter = "all" }  -- Shows total agent count

-- Custom label
{ type = "label", format = "Agent: {agent_name} ({status})" }

```

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

### Access Wezterm Agent Deck Configuration (Lua)

Source: https://context7.com/eric162/wezterm-agent-deck/llms.txt

This example demonstrates how to retrieve the merged plugin configuration from Wezterm Agent Deck using the agent_deck.get_config() function. It applies custom settings and then accesses the final configuration to log the update interval, useful for debugging and custom event handling.

```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, {
    colors = { working = '#00ff00' },
    notifications = { timeout_ms = 5000 },
})

-- Access merged configuration
wezterm.on('gui-startup', function()
    local plugin_config = agent_deck.get_config()

    -- plugin_config.colors.working == '#00ff00'
    -- plugin_config.colors.idle == 'blue' (default)
    -- plugin_config.notifications.timeout_ms == 5000
    -- plugin_config.update_interval == 5000 (default)

    wezterm.log_info('Agent Deck update interval: ' .. plugin_config.update_interval)
end)

return config
```

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

### Configure Notifications with Sound

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

Enables sound notifications on macOS by installing terminal-notifier and configuring the plugin backend.

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

```lua
agent_deck.apply_to_config(config, {
    notifications = {
        enabled = true,
        on_waiting = true,
        backend = 'terminal-notifier',
        terminal_notifier = {
            sound = 'default',
            title = 'WezTerm Agent Deck',
            activate = true,
        },
    },
})
```

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

### Install terminal-notifier for macOS Notifications (Bash)

Source: https://context7.com/eric162/wezterm-agent-deck/llms.txt

Installs the terminal-notifier utility using Homebrew, which is required for advanced macOS desktop notifications with sound support from the WezTerm Agent Deck plugin.

```bash
# Install terminal-notifier
brew install terminal-notifier
```

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

### Register for WezTerm Events using Lua

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

This snippet demonstrates how to register callback functions for WezTerm events. It shows examples for the 'update-status' event, which allows setting the left and right status bars, and the 'format-tab-title' event, which customizes the appearance of tab titles.

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

wezterm.on('update-status', function(window, pane) 
    -- Set left/right status
    window:set_left_status('Left Status')
    window:set_right_status('Right Status')
end)

wezterm.on('format-tab-title', function(tab, tabs, panes, config, hover, max_width)
    return {
        { Text = ' Tab ' .. tab.tab_index + 1 .. ' ' },
    }
end)
```

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

### Configure macOS Notifications with Sound (Lua)

Source: https://context7.com/eric162/wezterm-agent-deck/llms.txt

Configures the WezTerm Agent Deck plugin to use the 'terminal-notifier' backend for desktop notifications on macOS, enabling sound and other customization options. This requires terminal-notifier to be installed.

```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, {
    notifications = {
        enabled = true,
        on_waiting = true,
        backend = 'terminal-notifier',
        terminal_notifier = {
            path = nil,  -- uses terminal-notifier from PATH
            sound = 'default',  -- 'Ping', 'Glass', 'Funk', 'Pop', etc.
            group = 'wezterm-agent-deck',
            title = 'WezTerm Agent Deck',
            activate = true,  -- focus WezTerm when notification clicked
        },
    },
})

return config
```

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

### Update All Plugins in WezTerm using Lua

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

This code snippet shows how to trigger an update for all installed WezTerm plugins. It can be executed either from the debug overlay or through a defined action. Alternatively, users can manually delete the plugin directory to force a re-clone on the next launch.

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

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

### Set up a WezTerm Plugin Locally in Lua

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

This section outlines the steps for local WezTerm plugin development. It includes creating the plugin directory structure, writing a basic `init.lua` file, referencing the plugin using a file URL in `wezterm.lua`, and updating the plugin during development.

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

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

### Apply WezTerm Configuration with Type Annotations in Lua

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

This Lua code demonstrates how to use type annotations for WezTerm configurations and functions. It imports the `wezterm` module with a specific type (`WezTerm`) and uses type hints for configuration objects (`Config`) and function parameters, enabling better IDE support.

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

---@param config Config
---@param opts? { enabled: boolean, color: string }
function M.apply_to_config(config, opts)
    -- IDE now provides autocomplete and type checking
end
```

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

### Unit Testing WezTerm Plugins with Busted

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

Demonstrates how to write unit tests for WezTerm plugins using the Busted framework. It shows the structure of a describe/it block to verify plugin logic like option merging.

```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)
```

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

### Minimal WezTerm Plugin Template (Lua)

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

A basic template for a WezTerm plugin, demonstrating the required `plugin/init.lua` structure and the `apply_to_config` function. This function is responsible for merging user options with default settings and applying configuration changes to WezTerm.

```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

```

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

### Basic WezTerm Plugin Initialization

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

This Lua code represents the `plugin/init.lua` file for a WezTerm plugin. It requires the `wezterm` module and defines a function `apply_to_config` that logs a message when the plugin is loaded.

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

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

return M
```

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

### Configure WezTerm Agent Deck Plugin

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

This Lua code snippet demonstrates how to configure the WezTerm Agent Deck plugin. It allows customization of polling intervals, agent detection patterns, tab title formats, status bar components, colors, and notifications. The configuration is applied using `agent_deck.setup()` and `agent_deck.apply_to_config(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)

```

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

### Load Local WezTerm Agent Deck Plugin for Development (Lua)

Source: https://context7.com/eric162/wezterm-agent-deck/llms.txt

This Lua code snippet demonstrates how to load the WezTerm Agent Deck plugin from a local directory instead of a remote repository. It configures the plugin with faster update intervals for development and sets up a debug log to display agent states. This is useful for iterative development and testing of the plugin.

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

-- Load from local directory instead of GitHub
local agent_deck = dofile('/path/to/wezterm-agent-deck/plugin/init.lua')

agent_deck.apply_to_config(config, {
    -- Development settings
    update_interval = 1000,  -- Faster updates for testing
})

-- Debug logging
wezterm.on('update-status', function(window, pane)
    local all_states = agent_deck.get_all_agent_states()
    for pane_id, state in pairs(all_states) do
        wezterm.log_info(string.format(
            '[DEBUG] Pane %d: agent=%s status=%s',
            pane_id,
            state.agent_type,
            state.status
        ))
    end
end)

return config

```

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

### Common WezTerm Objects and Methods

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

Reference for interacting with Window, Pane, and Tab objects within the WezTerm environment.

```lua
-- Window object (GuiWindow)
window:set_left_status(text)
window:set_right_status(text)
window:perform_action(action, pane)
window:active_workspace()
window:effective_config()
window:toast_notification(title, msg, url, timeout)

-- Pane object
pane:get_foreground_process_name()
pane:get_current_working_dir()
pane:tab()
pane:window()

-- Tab object
tab.tab_index
tab.is_active
tab:panes()
tab:panes_with_info()
```

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

### WezTerm API Quick Reference

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

A collection of essential WezTerm API functions for plugin management, configuration, event handling, and UI actions.

```lua
-- Plugin system
wezterm.plugin.require(url)
wezterm.plugin.update_all()
wezterm.plugin.list()

-- Configuration
wezterm.config_builder()
wezterm.color.get_builtin_schemes()

-- Events
wezterm.on(event_name, callback)
wezterm.emit(event_name, ...)

-- Actions
wezterm.action_callback(fn)
wezterm.action.ActivateKeyTable({})
wezterm.action.InputSelector({})

-- Utility
wezterm.log_info/warn/error(msg)
wezterm.format({})
wezterm.nerdfonts.xxx
```

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

### Configure WezTerm Keybindings with Lua

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

This snippet demonstrates how to add custom keybindings to WezTerm configuration using Lua. It shows how to insert a new key binding with a specific key, modifier, and action, and also how to define a reusable action function.

```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
```

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

### Implement Smart Workspace Switcher with Input Selector in Lua

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

This Lua function, `switch_workspace`, integrates with WezTerm's `InputSelector` to provide a fuzzy-finder experience for switching workspaces. It emits events before and after the selection process and handles the logic for switching to the chosen workspace.

```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
```

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

### Implementing Robust Error Handling

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

Shows how to wrap risky operations in a pcall block to prevent plugin crashes. It includes logging the error and emitting a custom event to notify the system of the failure.

```lua
local success, result = pcall(function()
    return some_risky_operation()
end)

if not success then
    wezterm.log_error('Operation failed:', result)
    wezterm.emit('my_plugin.error', result)
    return nil
end

wezterm.emit('my_plugin.operation.failed', error_details)
```

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

### Configure Agent Deck Settings

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

Customizes the plugin behavior, including update intervals, status colors, icon styles, and notification settings.

```lua
agent_deck.apply_to_config(config, {
    update_interval = 500,

    colors = {
        working = '#A6E22E',
        waiting = '#E6DB74',
        idle = '#66D9EF',
        inactive = '#888888',
    },

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

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

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

### Reference Local WezTerm Plugin via File URL

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

This Lua code snippet shows how to load a local WezTerm plugin using a `file://` URL in your `wezterm.lua` configuration. This allows for direct development and testing of plugins without publishing them.

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

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

### Subscribe to Agent Lifecycle Events

Source: https://context7.com/eric162/wezterm-agent-deck/llms.txt

Demonstrates how to hook into custom events emitted by the plugin to perform logging or trigger external actions when agents are detected, finish, or change status.

```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)

-- Fired when an agent is first detected in a pane
wezterm.on('agent_deck.agent_detected', function(window, pane, agent_type)
    wezterm.log_info('Agent detected: ' .. agent_type)
end)

-- Fired when an agent process exits
wezterm.on('agent_deck.agent_finished', function(window, pane, agent_type)
    wezterm.log_info('Agent finished: ' .. agent_type)
end)

-- Fired on any status change
wezterm.on('agent_deck.status_changed', function(window, pane, old_status, new_status, agent_type)
    wezterm.log_info(string.format(
        '%s: %s -> %s',
        agent_type or 'unknown',
        old_status,
        new_status
    ))
end)

-- Fired when agent needs user attention (waiting status)
wezterm.on('agent_deck.attention_needed', function(window, pane, agent_type, reason)
    -- reason is 'waiting_for_input'
    -- Could trigger external notification, sound, etc.
    wezterm.log_warn(agent_type .. ' needs attention: ' .. reason)
end)

return config
```

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

### Integrate WezTerm Color Schemes into Configuration using Lua

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

This Lua function demonstrates how to read colors from WezTerm's built-in color schemes and apply them to configuration settings. It accesses various color properties like background, foreground, ANSI, and bright colors from the selected color scheme to customize UI elements.

```lua
function M.apply_to_config(config, opts)
    local scheme = wezterm.color.get_builtin_schemes()[config.color_scheme]
    if scheme then
        -- Access colors
        local bg = scheme.background
        local fg = scheme.foreground
        local ansi = scheme.ansi      -- Array of 8 ANSI colors
        local brights = scheme.brights -- Array of 8 bright colors
        
        -- Use in configuration
        config.colors = config.colors or {}
        config.colors.tab_bar = {
            background = 'transparent',
            active_tab = {
                bg_color = 'transparent',
                fg_color = ansi[5], -- Blue
            },
        }
    end
end
```

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

### Detect Prompts and User Input States in Go

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

Provides lists of strings representing various prompts that indicate user interaction or system state. This includes permission prompts (allow/deny), a simple '>' character for input waiting, and common 'Y/n' confirmation questions. These are used to determine if the agent is waiting for user input or confirmation.

```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]",
}
```

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

### Utilize lib.wezterm Utility Library in Lua

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

This code demonstrates how to require and use the `lib.wezterm` utility library for WezTerm plugin development. It showcases the usage of string manipulation functions like `hash` and file I/O operations such as `read_file`.

```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")
```

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

### Retrieve status icons and colors in Lua

Source: https://context7.com/eric162/wezterm-agent-deck/llms.txt

Fetches the configured icon and color for a specific status. This ensures UI elements remain consistent with the user's plugin configuration settings.

```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, {
    icons = { style = 'nerd' },
    colors = { working = '#00ff00', waiting = '#ffff00' },
})

wezterm.on('format-tab-title', function(tab, tabs, panes, config, hover, max_width)
    local pane_id = tab.active_pane.pane_id
    local state = agent_deck.get_agent_state(pane_id)

    if state then
        local icon = agent_deck.get_status_icon(state.status)
        local color = agent_deck.get_status_color(state.status)

        return wezterm.format({
            { Foreground = { Color = color } },
            { Text = ' ' .. icon .. ' ' },
            { Attribute = { Intensity = 'Normal' } },
            { Text = tab.active_pane.title or 'Terminal' },
            { Text = ' ' },
        })
    end

    return nil
end)

return config
```

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

### Determine Operating System Path Separator in Lua

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

This Lua code snippet determines the appropriate path separator ('\' for Windows, '/' for others) based on `wezterm.target_triple`. An alternative method using `package.config` is also shown.

```lua
local is_windows = wezterm.target_triple == "x86_64-pc-windows-msvc"
    or string.match(wezterm.target_triple, 'windows') ~= nil
local separator = is_windows and '\\' or '/'

-- Alternative using package.config
local separator = package.config:sub(1, 1)
```

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

### Agent-Deck: Detect AI Tool Content Pattern Matching (Go)

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

This Go code snippet illustrates agent-deck's fallback method for detecting AI tools using regular expressions. It defines a map where keys are tool names and values are slices of compiled regex patterns. This allows for more flexible detection based on keywords and phrases within terminal output, such as 'claude' or 'anthropic' for the Claude tool.

```go
package main

import (
	"regexp"
)

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`),
	},
}
```

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

### Emit and Listen for Custom Events in WezTerm using Lua

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

This code illustrates how to implement custom event handling in WezTerm for inter-plugin communication. It shows how to emit a custom event with associated data and how to register a listener to receive and process these events, logging received data to the console.

```lua
-- Emit an event
wezterm.emit('my_plugin.some_event', window, pane, custom_data)

-- Listen for events
wezterm.on('my_plugin.some_event', function(window, pane, custom_data)
    wezterm.log_info('Event received:', custom_data)
end)
```

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

### Agent-Deck: Detect AI Tool Command String Matching (Go)

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

This Go code snippet from agent-deck's session.go file demonstrates how it detects AI tools by directly matching command strings. It converts the command to lowercase and checks for keywords like 'claude', 'gemini', 'opencode', or 'codex'. This is the primary and most reliable method for tool detection.

```go
package main

import (
	"strings"
)

func DetectTool(s struct {
	Command string
}) string {
	if s.Command != "" {
		cmdLower := strings.ToLower(s.Command)
		if strings.Contains(cmdLower, "claude") {
			return "claude"
		} else if strings.Contains(cmdLower, "gemini") {
			return "gemini"
		} else if strings.Contains(cmdLower, "opencode") {
			return "opencode"
		} else if strings.Contains(cmdLower, "codex") {
			return "codex"
		}
	}
	return ""
}
```

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

### Configure WezTerm State Directory for Windows

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

This Lua code snippet provides a Windows-specific configuration for WezTerm, setting an explicit state directory with write access. This is recommended to address potential issues with default state directory permissions on Windows.

```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 Custom Agent Detection Patterns in Wezterm Agent Deck (Lua)

Source: https://context7.com/eric162/wezterm-agent-deck/llms.txt

This snippet illustrates how to define custom agent detection patterns for Wezterm Agent Deck. It shows how to add a new agent ('my_agent') with various pattern types (executable, argv, title, status) and how to override patterns for an existing agent ('claude').

```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, {
    agents = {
        -- Add a new custom agent
        my_agent = {
            patterns = { 'my%-agent' },  -- Generic fallback pattern
            executable_patterns = {
                '/my%-agent$',
                'my%-agent%-cli',
            },
            argv_patterns = {
                'npx%s+my%-agent',
                'my%-agent%s+run',
            },
            title_patterns = {
                'my agent',
                'MyAgent',
            },
            -- Custom status patterns (optional, uses defaults if nil)
            status_patterns = {
                working = { 'processing', 'computing', 'AI thinking' },
                waiting = { 'confirm%?', 'input needed', 'waiting for user' },
                idle = { '^%$%s*$', '^>>>' },  -- Custom prompt patterns
            },
        },

        -- Override patterns for existing agent
        claude = {
            patterns = { 'claude', 'anthropic' },
            executable_patterns = {
                '@anthropic%-ai/claude%-code',
                '/claude$',
                'claude%-desktop',  -- Add desktop app detection
            },
        },
    },
})

return config
```

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

### Cross-Platform Agent Status Detection Patterns

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

Comparison of how Agent-Deck (Go) and Code-Squad (TypeScript) detect agent activity, waiting states, and completion status using regex and string matching.

```go
busyIndicators := []string{"esc to interrupt"}
permissionPrompts := []string{"Yes, allow once", "(Y/n)", "[Y/n]"}
```

```typescript
{ status: 'working', patterns: [/Esc to interrupt/i] }
{ status: 'waiting', patterns: [/\(y\/n\)/i, /Do you want to proceed\?/i] }
```

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

### Define Custom Agents

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

Extends the plugin to support additional AI agents by defining regex patterns for identification and status tracking.

```lua
agents = {
    my_agent = {
        patterns = { 'my%-agent' },
        status_patterns = {
            working = { 'thinking' },
            waiting = { 'y/n' },
        },
    },
}
```

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

### Advanced WezTerm Agent Deck Configuration (Lua)

Source: https://context7.com/eric162/wezterm-agent-deck/llms.txt

Configures WezTerm Agent Deck with custom options for update intervals, cooldown, agent detection, colors, icons, tab titles, status bars, and notifications. This function allows fine-grained control over plugin behavior.

```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, {
    -- Status check interval in milliseconds
    update_interval = 500,

    -- Anti-flicker delay before transitioning from working to idle
    cooldown_ms = 2000,

    -- Maximum terminal lines to scan for status patterns
    max_lines = 100,

    -- Whitelist specific agents (nil = all enabled)
    enabled_agents = { 'claude', 'opencode', 'aider' },

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

    -- Icon configuration
    icons = {
        style = 'unicode',  -- 'unicode', 'nerd', or 'emoji'
        unicode = { working = '●', waiting = '◔', idle = '○', inactive = '◌' },
        nerd = { working = '', waiting = '', idle = '', inactive = '' },
        emoji = { working = '🟢', waiting = '🟡', idle = '🔵', inactive = '⚪' },
    },

    -- Tab title settings
    tab_title = {
        enabled = true,
        position = 'left',  -- 'left' or 'right' of title
        components = {
            { type = 'icon' },
            { type = 'separator', text = ' ' },
        },
    },

    -- Right status bar (aggregate view)
    right_status = {
        enabled = true,
        components = {
            { type = 'badge', filter = 'waiting', label = 'waiting' },
            { type = 'separator', text = ' | ' },
            { type = 'badge', filter = 'working', label = 'working' },
        },
    },

    -- Notification settings
    notifications = {
        enabled = true,
        on_waiting = true,
        timeout_ms = 4000,
        backend = 'native',  -- or 'terminal-notifier'
    },
})

return config
```

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

### Implement Custom Rendering

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

Disables default plugin UI elements to implement custom tab titles and status bar indicators using the plugin's internal state methods.

```lua
agent_deck.apply_to_config(config, {
    tab_title = { enabled = false },
    right_status = { enabled = false },
    colors = { ... },
})

wezterm.on('format-tab-title', function(tab)
    local formatted = {}
    for _, pane_info in ipairs(tab.panes or {}) do
        local state = agent_deck.get_agent_state(pane_info.pane_id)
        if state then
            table.insert(formatted, { Foreground = { Color = agent_deck.get_status_color(state.status) } })
            table.insert(formatted, { Text = agent_deck.get_status_icon(state.status) .. ' ' })
        end
    end
    table.insert(formatted, { Text = tab.tab_title or 'Terminal' })
    return wezterm.format(formatted)
end)

wezterm.on('update-status', function(window, pane)
    for _, tab in ipairs(window:mux_window():tabs()) do
        for _, p in ipairs(tab:panes()) do
            agent_deck.update_pane(p)
        end
    end

    local counts = agent_deck.count_agents_by_status()
    local cfg = agent_deck.get_config()
    local items = {}

    if counts.waiting > 0 then
        table.insert(items, { Foreground = { Color = cfg.colors.waiting } })
        table.insert(items, { Text = counts.waiting .. ' waiting ' })
    end

    window:set_right_status(wezterm.format(items))
end)
```

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

### Manage Sub-modules by Updating package.path in Lua

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

This snippet demonstrates how to update the `package.path` in Lua to include sub-modules. It determines the correct path separator based on the operating system and constructs the path to the plugin's directory. It also includes a helper function to check if a directory exists before updating `package.path`.

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

local M = {}

-- Determine platform-specific separator
local is_windows = string.match(wezterm.target_triple, 'windows') ~= nil
local separator = is_windows and '\\' or '/'

-- Get plugin directory from plugin list
local plugin_dir = wezterm.plugin.list()[1].plugin_dir:gsub(separator .. '[^' .. separator .. ']*$', '')

-- Helper to check if directory exists
local function directory_exists(path)
    local success, result = pcall(wezterm.read_dir, plugin_dir .. path)
    return success and result
end

-- Determine the encoded path name
local function get_require_path()
    local https_path = 'httpssCssZssZsgithubsDscomsZsownersZsrepo'
    local https_path_slash = 'httpssCssZssZsgithubsDscomsZsownersZsreposZs'
    
    if directory_exists(https_path_slash) then
        return https_path_slash
    end
    return https_path
end

-- Update package.path
package.path = package.path
    .. ';'
    .. plugin_dir
    .. separator
    .. get_require_path()
    .. separator
    .. 'plugin'
    .. separator
    .. '?.lua'

-- Now sub-modules can be required
local submodule = require('my_submodule')

return M
```

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

### Detect Platform in Lua using WezTerm Target Triple

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

This Lua function `get_platform` identifies the operating system (Windows, macOS, or Linux) by analyzing the `wezterm.target_triple` string.

```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
```

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

### Configure Enhanced Event Listeners with listeners.wezterm in Lua

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

This Lua snippet illustrates the usage of the `listeners.wezterm` plugin for managing event listeners and persistent state. It demonstrates configuring event listeners, setting toast notifications, and managing state flags and counters.

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

local event_listeners = {
    ["window-resized"] = {
        toast_message = "Window resized to %dx%d",
    },
    ["key-pressed"] = {
        fn = function(args)
            wezterm.log_info("Key pressed!")
        end,
    },
}

listeners.config(event_listeners, { toast_timeout = 2000 })

-- State management
listeners.state.flags.set("dark_mode", true)
listeners.state.counters.increment("windows_opened")
```

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

### Configure Lua Language Server for WezTerm Development

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

This JSON configuration file sets up the Lua Language Server (LuaLS) for WezTerm development. It specifies the runtime version, adds a workspace library path for plugins, and declares `wezterm` as a global variable for diagnostics.

```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"]
}
```

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

### Implement Session Management (resurrect.wezterm) in Lua

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

This Lua snippet demonstrates a pattern for session management plugins like `resurrect.wezterm`. It utilizes `dev.wezterm` for plugin path resolution and configures a custom state save directory for session data.

```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
```

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

### Implement Tab Bar Plugins (tabline.wez, bar.wezterm) in Lua

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

This Lua code provides a pattern for creating tab bar plugins in WezTerm. It shows how to hook into `update-status` and `format-tab-title` events and configure tab bar specific settings.

```lua
function M.setup(opts)
    require('plugin.config').set(opts)
    
    wezterm.on('update-status', function(window)
        require('plugin.component').set_status(window)
    end)
    
    wezterm.on('format-tab-title', function(tab, _, _, _, hover, _)
        return require('plugin.tabs').set_title(tab, hover)
    end)
end

function M.apply_to_config(config)
    config.use_fancy_tab_bar = false
    config.show_new_tab_button_in_tab_bar = false
    config.tab_max_width = 32
    config.status_update_interval = 500
end
```