Summary

• Enhanced external terminal provider to support both string and function for external_terminal_cmd
• Added comprehensive test coverage for the new functionality
• Updated documentation with examples of both usage patterns

Changes

1. Enhanced External Terminal Provider

The external_terminal_cmd option can now be:

• String template (existing): "alacritty -e %s" where %s is replaced with the Claude command
• Function (new): function(cmd, env) that returns either:
  • A string command to execute
  • A table of command arguments

2. Use Cases for Function Support

• Dynamic terminal selection based on OS or environment
• Complex command construction with proper escaping
• Conditional terminal behavior based on environment variables
• Integration with terminal multiplexers or custom launchers

3. Example Configurations

-- Function returning a different command based on window dimensions
external_terminal_cmd = function(cmd)
  -- Get current Neovim window dimensions
  local width = vim.api.nvim_win_get_width(0)
  local height = vim.api.nvim_win_get_height(0)

  -- Choose split direction based on window aspect ratio
  -- Typical terminal is ~2:1 aspect ratio (80 cols × 40 rows)
  if aspect_ratio > 2.4 then
    return "tmux-run --width 30 " .. cmd -- Horizontal split for wider windows
  else
    return "tmux-run --height 40 " .. cmd -- Vertical split for taller windows
  end
end

-- Function returning different commands per OS
external_terminal_cmd = function(cmd, env)
  if vim.fn.has("mac") == 1 then
    return { "osascript", "-e", string.format('tell app "Terminal" to do script "%s"', cmd) }
  else
    return "alacritty -e " .. cmd
  end
end

-- Function with environment-based logic
external_terminal_cmd = function(cmd, env)
  if env.CLAUDE_CODE_SSE_PORT then
    return string.format("kitty --title 'Claude Code (Port %s)' %s", env.CLAUDE_CODE_SSE_PORT, cmd)
  else
    return "kitty " .. cmd
  end
end

Test Coverage

Added comprehensive test suite in tests/unit/terminal/external_spec.lua covering:

• String template with %s placeholder
• Function returning string
• Function returning table
• Error handling for invalid configurations
• Function receiving correct parameters (cmd, env)

Checklist

• Code follows project conventions
• Tests added and passing
• Documentation updated
• No breaking changes to existing API