feat(terminal/external): add cwd support and stricter placeholder parsing; set jobstart cwd; update docs/tests

Change-Id: If71a96214bb10d361fccaaeb5415080a5df3125c
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

README.md

@@ -264,8 +264,9 @@ For deep technical details, see [ARCHITECTURE.md](./ARCHITECTURE.md).
       -- Provider-specific options
       provider_opts = {
         -- 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
+        -- 1. String with %s placeholder: "alacritty -e %s" (backward compatible)
+        -- 2. String with two %s placeholders: "alacritty --working-directory %s -e %s" (cwd, command)
+        -- 3. Function returning command: function(cmd, env) return "alacritty -e " .. cmd end
         external_terminal_cmd = nil,
       },
     },
@@ -463,6 +464,7 @@ Run Claude Code in a separate terminal application outside of Neovim:
       provider = "external",
       provider_opts = {
         external_terminal_cmd = "alacritty -e %s", -- %s is replaced with claude command
+        -- Or with working directory: "alacritty --working-directory %s -e %s" (first %s = cwd, second %s = command)
       },
     },
   },
@@ -603,6 +605,8 @@ require("claudecode").setup({
 
 The custom provider will automatically fall back to the native provider if validation fails or `is_available()` returns false.
 
+Note: If your command or working directory may contain spaces or special characters, prefer returning a table of args from a function (e.g., `{ "alacritty", "--working-directory", cwd, "-e", "claude", "--help" }`) to avoid shell-quoting issues.
+
 ## Community Extensions
 
 The following are third-party community extensions that complement claudecode.nvim. **These extensions are not affiliated with Coder and are maintained independently by community members.** We do not ensure that these extensions work correctly or provide support for them.

lua/claudecode/terminal/external.lua

@@ -49,6 +49,7 @@ function M.open(cmd_string, env_table)
 
   local cmd_parts
   local full_command
+  local cwd_for_jobstart = nil
 
   -- Handle both string and function types
   if type(external_cmd) == "function" then
@@ -81,24 +82,47 @@ function M.open(cmd_string, env_table)
       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)
+    -- Count the number of %s placeholders and format accordingly
+    -- 1 placeholder: backward compatible, just command ("alacritty -e %s")
+    -- 2 placeholders: cwd and command ("alacritty --working-directory %s -e %s")
+    local _, placeholder_count = external_cmd:gsub("%%s", "")
+
+    if placeholder_count == 0 then
+      vim.notify("external_terminal_cmd must contain '%s' placeholder(s) for the command.", vim.log.levels.ERROR)
+      return
+    elseif placeholder_count == 1 then
+      -- Backward compatible: just the command
+      full_command = string.format(external_cmd, cmd_string)
+    elseif placeholder_count == 2 then
+      -- New feature: cwd and command
+      local cwd = vim.fn.getcwd()
+      cwd_for_jobstart = cwd
+      full_command = string.format(external_cmd, cwd, cmd_string)
+    else
+      vim.notify(
+        string.format(
+          "external_terminal_cmd must use 1 '%%s' (command) or 2 '%%s' placeholders (cwd, command); got %d",
+          placeholder_count
+        ),
+        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
 
   -- Start the external terminal as a detached process
+  -- Set cwd for jobstart when available to improve robustness even if the terminal ignores it
+  cwd_for_jobstart = cwd_for_jobstart or (vim.fn.getcwd and vim.fn.getcwd() or nil)
+
   jobid = vim.fn.jobstart(cmd_parts, {
     detach = true,
     env = env_table,
+    cwd = cwd_for_jobstart,
     on_exit = function(job_id, exit_code, _)
       vim.schedule(function()
         if job_id == jobid then

tests/unit/terminal/external_spec.lua

@@ -18,6 +18,9 @@ describe("claudecode.terminal.external", function()
           return 123
         end), -- Return valid job id
         jobstop = spy.new(function() end),
+        getcwd = spy.new(function()
+          return "/cwd"
+        end),
       },
       notify = spy.new(function() end),
       log = {
@@ -91,6 +94,7 @@ describe("claudecode.terminal.external", function()
       local call_args = mock_vim.fn.jobstart.calls[1].vals
       assert.are.same({ "alacritty", "-e", "claude", "--help" }, call_args[1])
       assert.are.same({ ENABLE_IDE_INTEGRATION = "true" }, call_args[2].env)
+      assert.are.equal("/cwd", call_args[2].cwd)
     end)
 
     it("should error if string command missing %s placeholder", function()
@@ -105,7 +109,7 @@ describe("claudecode.terminal.external", function()
 
       assert
         .spy(mock_vim.notify)
-        .was_called_with("external_terminal_cmd must contain '%s' placeholder for the Claude command.", mock_vim.log.levels.ERROR)
+        .was_called_with("external_terminal_cmd must contain '%s' placeholder(s) for the command.", mock_vim.log.levels.ERROR)
       assert.spy(mock_vim.fn.jobstart).was_not_called()
     end)
 
@@ -122,6 +126,45 @@ describe("claudecode.terminal.external", function()
       assert.spy(mock_vim.notify).was_called()
       assert.spy(mock_vim.fn.jobstart).was_not_called()
     end)
+
+    it("should handle string with two placeholders (cwd and command)", function()
+      -- Mock vim.fn.getcwd to return a known directory
+      mock_vim.fn.getcwd = spy.new(function()
+        return "/test/project"
+      end)
+
+      local config = {
+        provider_opts = {
+          external_terminal_cmd = "alacritty --working-directory %s -e %s",
+        },
+      }
+      external_provider.setup(config)
+
+      external_provider.open("claude --help", { ENABLE_IDE_INTEGRATION = "true" })
+
+      assert.spy(mock_vim.fn.jobstart).was_called(1)
+      local call_args = mock_vim.fn.jobstart.calls[1].vals
+      assert.are.same({ "alacritty", "--working-directory", "/test/project", "-e", "claude", "--help" }, call_args[1])
+      assert.are.same({ ENABLE_IDE_INTEGRATION = "true" }, call_args[2].env)
+      assert.are.equal("/test/project", call_args[2].cwd)
+    end)
+
+    it("should error if string has more than two placeholders", function()
+      local config = {
+        provider_opts = {
+          external_terminal_cmd = "alacritty --working-directory %s -e %s --title %s",
+        },
+      }
+      external_provider.setup(config)
+
+      external_provider.open("claude --help", {})
+
+      assert.spy(mock_vim.notify).was_called_with(
+        "external_terminal_cmd must use 1 '%s' (command) or 2 '%s' placeholders (cwd, command); got 3",
+        mock_vim.log.levels.ERROR
+      )
+      assert.spy(mock_vim.fn.jobstart).was_not_called()
+    end)
   end)
 
   describe("open with function command", function()
@@ -141,6 +184,7 @@ describe("claudecode.terminal.external", function()
       local call_args = mock_vim.fn.jobstart.calls[1].vals
       assert.are.same({ "kitty", "claude", "--help" }, call_args[1])
       assert.are.same({ ENABLE_IDE_INTEGRATION = "true" }, call_args[2].env)
+      assert.are.equal("/cwd", call_args[2].cwd)
     end)
 
     it("should handle function returning table", function()
@@ -158,6 +202,7 @@ describe("claudecode.terminal.external", function()
       assert.spy(mock_vim.fn.jobstart).was_called(1)
       local call_args = mock_vim.fn.jobstart.calls[1].vals
       assert.are.same({ "osascript", "-e", 'tell app "Terminal" to do script "claude"' }, call_args[1])
+      assert.are.equal("/cwd", call_args[2].cwd)
     end)
 
     it("should pass cmd and env to function", function()