feat: support function for external_terminal_cmd configuration

Allow external_terminal_cmd to be either a string template with %s placeholder
or a function that receives (cmd, env) and returns the command to execute.
This enables more dynamic terminal command generation based on environment
or runtime conditions.

Examples:
- String: "alacritty -e %s"
- Function: function(cmd, env) return { "osascript", "-e", ... } end

Author: jdurand

README.md

@@ -263,7 +263,10 @@ For deep technical details, see [ARCHITECTURE.md](./ARCHITECTURE.md).
 
       -- Provider-specific options
       provider_opts = {
-        external_terminal_cmd = nil, -- Command template for external terminal provider (e.g., "alacritty -e %s")
+        -- Command for external terminal provider. Can be:
+        -- 1. String with %s placeholder: "alacritty -e %s"
+        -- 2. Function returning command: function(cmd, env) return "alacritty -e " .. cmd end
+        external_terminal_cmd = nil,
       },
     },
 
@@ -452,13 +455,34 @@ For complete configuration options, see:
 Run Claude Code in a separate terminal application outside of Neovim:
 
 ```lua
+-- Using a string template (simple)
 {
   "coder/claudecode.nvim",
   opts = {
     terminal = {
       provider = "external",
       provider_opts = {
-        external_terminal_cmd = "alacritty -e %s", -- Replace with your preferred terminal program. %s is replaced with claude command
+        external_terminal_cmd = "alacritty -e %s", -- %s is replaced with claude command
+      },
+    },
+  },
+}
+
+-- Using a function for dynamic command generation (advanced)
+{
+  "coder/claudecode.nvim",
+  opts = {
+    terminal = {
+      provider = "external",
+      provider_opts = {
+        external_terminal_cmd = function(cmd, env)
+          -- You can build complex commands based on environment or conditions
+          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,
       },
     },
   },

lua/claudecode/config.lua

@@ -61,11 +61,13 @@ function M.validate(config)
 
     -- Validate external_terminal_cmd in provider_opts
     if config.terminal.provider_opts.external_terminal_cmd then
+      local cmd_type = type(config.terminal.provider_opts.external_terminal_cmd)
       assert(
-        type(config.terminal.provider_opts.external_terminal_cmd) == "string",
-        "terminal.provider_opts.external_terminal_cmd must be a string"
+        cmd_type == "string" or cmd_type == "function",
+        "terminal.provider_opts.external_terminal_cmd must be a string or function"
       )
-      if config.terminal.provider_opts.external_terminal_cmd ~= "" then
+      -- Only validate %s placeholder for strings
+      if cmd_type == "string" and config.terminal.provider_opts.external_terminal_cmd ~= "" then
         assert(
           config.terminal.provider_opts.external_terminal_cmd:find("%%s"),
           "terminal.provider_opts.external_terminal_cmd must contain '%s' placeholder for the Claude command"

lua/claudecode/terminal.lua

@@ -143,7 +143,13 @@ local function get_provider()
       -- Check availability based on our config instead of provider's internal state
       local external_cmd = defaults.provider_opts and defaults.provider_opts.external_terminal_cmd
 
-      local has_external_cmd = external_cmd and external_cmd ~= "" and external_cmd:find("%%s")
+      local has_external_cmd = false
+      if type(external_cmd) == "function" then
+        has_external_cmd = true
+      elseif type(external_cmd) == "string" and external_cmd ~= "" and external_cmd:find("%%s") then
+        has_external_cmd = true
+      end
+      
       if has_external_cmd then
         return external_provider
       else
@@ -328,7 +334,7 @@ function M.setup(user_term_config, p_terminal_cmd, p_env)
         defaults[k] = defaults[k] or {}
         for opt_k, opt_v in pairs(v) do
           if opt_k == "external_terminal_cmd" then
-            if opt_v == nil or type(opt_v) == "string" then
+            if opt_v == nil or type(opt_v) == "string" or type(opt_v) == "function" then
               defaults[k][opt_k] = opt_v
             else
               vim.notify(

lua/claudecode/terminal/external.lua

@@ -39,24 +39,65 @@ function M.open(cmd_string, env_table)
   -- Get external terminal command from provider_opts
   local external_cmd = config.provider_opts and config.provider_opts.external_terminal_cmd
 
-  if not external_cmd or external_cmd == "" then
+  if not external_cmd then
     vim.notify(
       "external_terminal_cmd not configured. Please set terminal.provider_opts.external_terminal_cmd in your config.",
       vim.log.levels.ERROR
     )
     return
   end
 
-  -- Replace %s in the template with the Claude command
-  if not external_cmd:find("%%s") then
-    vim.notify("external_terminal_cmd must contain '%s' placeholder for the Claude command.", vim.log.levels.ERROR)
+  local cmd_parts
+  local full_command
+
+  -- Handle both string and function types
+  if type(external_cmd) == "function" then
+    -- Call the function with the Claude command and env table
+    local result = external_cmd(cmd_string, env_table)
+    if not result then
+      vim.notify("external_terminal_cmd function returned nil or false", vim.log.levels.ERROR)
+      return
+    end
+    
+    -- Result can be either a string or a table
+    if type(result) == "string" then
+      -- Parse the string into command parts
+      cmd_parts = vim.split(result, " ")
+      full_command = result
+    elseif type(result) == "table" then
+      -- Use the table directly as command parts
+      cmd_parts = result
+      full_command = table.concat(result, " ")
+    else
+      vim.notify(
+        "external_terminal_cmd function must return a string or table, got: " .. type(result),
+        vim.log.levels.ERROR
+      )
+      return
+    end
+  elseif type(external_cmd) == "string" then
+    if external_cmd == "" then
+      vim.notify("external_terminal_cmd string cannot be empty", vim.log.levels.ERROR)
+      return
+    end
+
+    -- Replace %s in the template with the Claude command
+    if not external_cmd:find("%%s") then
+      vim.notify("external_terminal_cmd must contain '%s' placeholder for the Claude command.", vim.log.levels.ERROR)
+      return
+    end
+
+    -- Build command by replacing %s with Claude command and splitting
+    full_command = string.format(external_cmd, cmd_string)
+    cmd_parts = vim.split(full_command, " ")
+  else
+    vim.notify(
+      "external_terminal_cmd must be a string or function, got: " .. type(external_cmd),
+      vim.log.levels.ERROR
+    )
     return
   end
 
-  -- Build command by replacing %s with Claude command and splitting
-  local full_command = string.format(external_cmd, cmd_string)
-  local cmd_parts = vim.split(full_command, " ")
-
   -- Start the external terminal as a detached process
   jobid = vim.fn.jobstart(cmd_parts, {
     detach = true,

tests/unit/config_spec.lua

@@ -196,5 +196,113 @@ describe("Configuration", function()
     expect(success).to_be_false()
   end)
 
+  it("should accept function for external_terminal_cmd", function()
+    local valid_config = {
+      port_range = { min = 10000, max = 65535 },
+      auto_start = true,
+      log_level = "info",
+      track_selection = true,
+      visual_demotion_delay_ms = 50,
+      connection_wait_delay = 200,
+      connection_timeout = 10000,
+      queue_timeout = 5000,
+      diff_opts = {
+        auto_close_on_accept = true,
+        show_diff_stats = true,
+        vertical_split = true,
+        open_in_current_tab = true,
+      },
+      env = {},
+      models = {
+        { name = "Test Model", value = "test" },
+      },
+      terminal = {
+        provider = "external",
+        provider_opts = {
+          external_terminal_cmd = function(cmd, env)
+            return "terminal " .. cmd
+          end,
+        },
+      },
+    }
+
+    local success, _ = pcall(function()
+      config.validate(valid_config)
+    end)
+
+    expect(success).to_be_true()
+  end)
+
+  it("should accept string for external_terminal_cmd", function()
+    local valid_config = {
+      port_range = { min = 10000, max = 65535 },
+      auto_start = true,
+      log_level = "info",
+      track_selection = true,
+      visual_demotion_delay_ms = 50,
+      connection_wait_delay = 200,
+      connection_timeout = 10000,
+      queue_timeout = 5000,
+      diff_opts = {
+        auto_close_on_accept = true,
+        show_diff_stats = true,
+        vertical_split = true,
+        open_in_current_tab = true,
+      },
+      env = {},
+      models = {
+        { name = "Test Model", value = "test" },
+      },
+      terminal = {
+        provider = "external",
+        provider_opts = {
+          external_terminal_cmd = "alacritty -e %s",
+        },
+      },
+    }
+
+    local success, _ = pcall(function()
+      config.validate(valid_config)
+    end)
+
+    expect(success).to_be_true()
+  end)
+
+  it("should reject invalid type for external_terminal_cmd", function()
+    local invalid_config = {
+      port_range = { min = 10000, max = 65535 },
+      auto_start = true,
+      log_level = "info",
+      track_selection = true,
+      visual_demotion_delay_ms = 50,
+      connection_wait_delay = 200,
+      connection_timeout = 10000,
+      queue_timeout = 5000,
+      diff_opts = {
+        auto_close_on_accept = true,
+        show_diff_stats = true,
+        vertical_split = true,
+        open_in_current_tab = true,
+      },
+      env = {},
+      models = {
+        { name = "Test Model", value = "test" },
+      },
+      terminal = {
+        provider = "external",
+        provider_opts = {
+          external_terminal_cmd = 123, -- Invalid: number
+        },
+      },
+    }
+
+    local success, err = pcall(function()
+      config.validate(invalid_config)
+    end)
+
+    expect(success).to_be_false()
+    expect(err).to_match("must be a string or function")
+  end)
+
   teardown()
 end)