feat: add working directory control for Claude terminal (#117)

ThomasK33 · web-flow · commit fe08db9aeb19 · 2025-09-10T17:44:26.000+02:00
# Working Directory Control for Claude Terminal

This PR adds the ability to fix Claude terminal's working directory regardless of `autochdir` and buffer-local cwd changes. The feature provides three options (in precedence order):

1. `cwd_provider(ctx)`: A function that returns a directory string, receiving context with `{ file, file_dir, cwd }`
2. `cwd`: A static path to use as working directory
3. `git_repo_cwd = true`: Resolves git root from the current file directory (or cwd if no file)

The implementation includes:
- A new `claudecode.cwd` module with directory resolution helpers
- Support for top-level aliases in the config for convenience
- Working directory resolution at terminal creation time
- Proper passing of cwd to both native terminal and snacks providers
- Comprehensive test coverage for the new functionality

This makes it easier to ensure Claude has the correct context when working with projects, especially in monorepos or when navigating between different parts of a codebase.
diff --git a/README.md b/README.md
@@ -285,6 +285,39 @@ For deep technical details, see [ARCHITECTURE.md](./ARCHITECTURE.md).
 }
 ```
 
+### Working Directory Control
+
+You can fix the Claude terminal's working directory regardless of `autochdir` and buffer-local cwd changes. Options (precedence order):
+
+- `cwd_provider(ctx)`: function that returns a directory string. Receives `{ file, file_dir, cwd }`.
+- `cwd`: static path to use as working directory.
+- `git_repo_cwd = true`: resolves git root from the current file directory (or cwd if no file).
+
+Examples:
+
+```lua
+require("claudecode").setup({
+  -- Top-level aliases are supported and forwarded to terminal config
+  git_repo_cwd = true,
+})
+
+require("claudecode").setup({
+  terminal = {
+    cwd = vim.fn.expand("~/projects/my-app"),
+  },
+})
+
+require("claudecode").setup({
+  terminal = {
+    cwd_provider = function(ctx)
+      -- Prefer repo root; fallback to file's directory
+      local cwd = require("claudecode.cwd").git_root(ctx.file_dir or ctx.cwd) or ctx.file_dir or ctx.cwd
+      return cwd
+    end,
+  },
+})
+```
+
 ## Floating Window Configuration
 
 The `snacks_win_opts` configuration allows you to create floating Claude Code terminals with custom positioning, sizing, and key bindings. Here are several practical examples:
diff --git a/lua/claudecode/cwd.lua b/lua/claudecode/cwd.lua
@@ -0,0 +1,109 @@
+--- Working directory resolution helpers for ClaudeCode.nvim
+---@module 'claudecode.cwd'
+
+local M = {}
+
+---Normalize and validate a directory path
+---@param dir string|nil
+---@return string|nil
+local function normalize_dir(dir)
+  if type(dir) ~= "string" or dir == "" then
+    return nil
+  end
+  -- Expand ~ and similar
+  local expanded = vim.fn.expand(dir)
+  local isdir = 1
+  if vim.fn.isdirectory then
+    isdir = vim.fn.isdirectory(expanded)
+  end
+  if isdir == 1 then
+    return expanded
+  end
+  return nil
+end
+
+---Find the git repository root starting from a directory
+---@param start_dir string|nil
+---@return string|nil
+function M.git_root(start_dir)
+  start_dir = normalize_dir(start_dir)
+  if not start_dir then
+    return nil
+  end
+
+  -- Prefer running without shell by passing a list
+  local result
+  if vim.fn.systemlist then
+    local ok, _ = pcall(function()
+      local _ = vim.fn.systemlist({ "git", "-C", start_dir, "rev-parse", "--show-toplevel" })
+    end)
+    if ok then
+      result = vim.fn.systemlist({ "git", "-C", start_dir, "rev-parse", "--show-toplevel" })
+    else
+      -- Fallback to string command if needed
+      local cmd = "git -C " .. vim.fn.shellescape(start_dir) .. " rev-parse --show-toplevel"
+      result = vim.fn.systemlist(cmd)
+    end
+  end
+
+  if vim.v.shell_error == 0 and result and #result > 0 then
+    local root = normalize_dir(result[1])
+    if root then
+      return root
+    end
+  end
+
+  -- Fallback: search for .git directory upward
+  if vim.fn.finddir then
+    local git_dir = vim.fn.finddir(".git", start_dir .. ";")
+    if type(git_dir) == "string" and git_dir ~= "" then
+      local parent = vim.fn.fnamemodify(git_dir, ":h")
+      return normalize_dir(parent)
+    end
+  end
+
+  return nil
+end
+
+---Resolve the effective working directory based on terminal config and context
+---@param term_cfg ClaudeCodeTerminalConfig
+---@param ctx ClaudeCodeCwdContext
+---@return string|nil
+function M.resolve(term_cfg, ctx)
+  if type(term_cfg) ~= "table" then
+    return nil
+  end
+
+  -- 1) Custom provider takes precedence
+  local provider = term_cfg.cwd_provider
+  local provider_type = type(provider)
+  if provider_type == "function" then
+    local ok, res = pcall(provider, ctx)
+    if ok then
+      local p = normalize_dir(res)
+      if p then
+        return p
+      end
+    end
+  end
+
+  -- 2) Static cwd
+  local static_cwd = normalize_dir(term_cfg.cwd)
+  if static_cwd then
+    return static_cwd
+  end
+
+  -- 3) Git repository root
+  if term_cfg.git_repo_cwd then
+    local start_dir = ctx and (ctx.file_dir or ctx.cwd) or vim.fn.getcwd()
+    local root = M.git_root(start_dir)
+    if root then
+      return root
+    end
+  end
+
+  -- 4) No override
+  return nil
+end
+
+return M
diff --git a/lua/claudecode/init.lua b/lua/claudecode/init.lua
@@ -300,6 +300,27 @@ function M.setup(opts)
 
   -- Setup terminal module: always try to call setup to pass terminal_cmd and env,
   -- even if terminal_opts (for split_side etc.) are not provided.
+  -- Map top-level cwd-related aliases into terminal config for convenience
+  do
+    local t = opts.terminal or {}
+    local had_alias = false
+    if opts.git_repo_cwd ~= nil then
+      t.git_repo_cwd = opts.git_repo_cwd
+      had_alias = true
+    end
+    if opts.cwd ~= nil then
+      t.cwd = opts.cwd
+      had_alias = true
+    end
+    if opts.cwd_provider ~= nil then
+      t.cwd_provider = opts.cwd_provider
+      had_alias = true
+    end
+    if had_alias then
+      opts.terminal = t
+    end
+  end
+
   local terminal_setup_ok, terminal_module = pcall(require, "claudecode.terminal")
   if terminal_setup_ok then
     -- Guard in case tests or user replace the module with a minimal stub without `setup`.
diff --git a/lua/claudecode/terminal.lua b/lua/claudecode/terminal.lua
@@ -19,6 +19,10 @@ local defaults = {
   auto_close = true,
   env = {},
   snacks_win_opts = {},
+  -- Working directory control
+  cwd = nil, -- static cwd override
+  git_repo_cwd = false, -- resolve to git root when spawning
+  cwd_provider = nil, -- function(ctx) -> cwd string
 }
 
 M.defaults = defaults
@@ -197,18 +201,67 @@ local function build_config(opts_override)
       snacks_win_opts = function(val)
         return type(val) == "table"
       end,
+      cwd = function(val)
+        return val == nil or type(val) == "string"
+      end,
+      git_repo_cwd = function(val)
+        return type(val) == "boolean"
+      end,
+      cwd_provider = function(val)
+        local t = type(val)
+        if t == "function" then
+          return true
+        end
+        if t == "table" then
+          local mt = getmetatable(val)
+          return mt and mt.__call ~= nil
+        end
+        return false
+      end,
     }
     for key, val in pairs(opts_override) do
       if effective_config[key] ~= nil and validators[key] and validators[key](val) then
         effective_config[key] = val
       end
     end
   end
+  -- Resolve cwd at config-build time so providers receive it directly
+  local cwd_ctx = {
+    file = (function()
+      local path = vim.fn.expand("%:p")
+      if type(path) == "string" and path ~= "" then
+        return path
+      end
+      return nil
+    end)(),
+    cwd = vim.fn.getcwd(),
+  }
+  cwd_ctx.file_dir = cwd_ctx.file and vim.fn.fnamemodify(cwd_ctx.file, ":h") or nil
+
+  local resolved_cwd = nil
+  -- Prefer provider function, then static cwd, then git root via resolver
+  if effective_config.cwd_provider then
+    local ok_p, res = pcall(effective_config.cwd_provider, cwd_ctx)
+    if ok_p and type(res) == "string" and res ~= "" then
+      resolved_cwd = vim.fn.expand(res)
+    end
+  end
+  if not resolved_cwd and type(effective_config.cwd) == "string" and effective_config.cwd ~= "" then
+    resolved_cwd = vim.fn.expand(effective_config.cwd)
+  end
+  if not resolved_cwd and effective_config.git_repo_cwd then
+    local ok_r, cwd_mod = pcall(require, "claudecode.cwd")
+    if ok_r and cwd_mod and type(cwd_mod.git_root) == "function" then
+      resolved_cwd = cwd_mod.git_root(cwd_ctx.file_dir or cwd_ctx.cwd)
+    end
+  end
+
   return {
     split_side = effective_config.split_side,
     split_width_percentage = effective_config.split_width_percentage,
     auto_close = effective_config.auto_close,
     snacks_win_opts = effective_config.snacks_win_opts,
+    cwd = resolved_cwd,
   }
 end
 
@@ -325,9 +378,30 @@ function M.setup(user_term_config, p_terminal_cmd, p_env)
   end
 
   for k, v in pairs(user_term_config) do
-    if k == "terminal_cmd" then
-      -- terminal_cmd is handled above, skip
-      break
+    if k == "split_side" then
+      if v == "left" or v == "right" then
+        defaults.split_side = v
+      else
+        vim.notify("claudecode.terminal.setup: Invalid value for split_side: " .. tostring(v), vim.log.levels.WARN)
+      end
+    elseif k == "split_width_percentage" then
+      if type(v) == "number" and v > 0 and v < 1 then
+        defaults.split_width_percentage = v
+      else
+        vim.notify(
+          "claudecode.terminal.setup: Invalid value for split_width_percentage: " .. tostring(v),
+          vim.log.levels.WARN
+        )
+      end
+    elseif k == "provider" then
+      if type(v) == "table" or v == "snacks" or v == "native" or v == "external" or v == "auto" then
+        defaults.provider = v
+      else
+        vim.notify(
+          "claudecode.terminal.setup: Invalid value for provider: " .. tostring(v) .. ". Defaulting to 'native'.",
+          vim.log.levels.WARN
+        )
+      end
     elseif k == "provider_opts" then
       -- Handle nested provider options
       if type(v) == "table" then
@@ -350,26 +424,60 @@ function M.setup(user_term_config, p_terminal_cmd, p_env)
       else
         vim.notify("claudecode.terminal.setup: Invalid value for provider_opts: " .. tostring(v), vim.log.levels.WARN)
       end
-    elseif defaults[k] ~= nil then -- Other known config keys
-      if k == "split_side" and (v == "left" or v == "right") then
-        defaults[k] = v
-      elseif k == "split_width_percentage" and type(v) == "number" and v > 0 and v < 1 then
-        defaults[k] = v
-      elseif
-        k == "provider" and (v == "snacks" or v == "native" or v == "external" or v == "auto" or type(v) == "table")
-      then
-        defaults[k] = v
-      elseif k == "show_native_term_exit_tip" and type(v) == "boolean" then
-        defaults[k] = v
-      elseif k == "auto_close" and type(v) == "boolean" then
-        defaults[k] = v
-      elseif k == "snacks_win_opts" and type(v) == "table" then
-        defaults[k] = v
+    elseif k == "show_native_term_exit_tip" then
+      if type(v) == "boolean" then
+        defaults.show_native_term_exit_tip = v
+      else
+        vim.notify(
+          "claudecode.terminal.setup: Invalid value for show_native_term_exit_tip: " .. tostring(v),
+          vim.log.levels.WARN
+        )
+      end
+    elseif k == "auto_close" then
+      if type(v) == "boolean" then
+        defaults.auto_close = v
+      else
+        vim.notify("claudecode.terminal.setup: Invalid value for auto_close: " .. tostring(v), vim.log.levels.WARN)
+      end
+    elseif k == "snacks_win_opts" then
+      if type(v) == "table" then
+        defaults.snacks_win_opts = v
+      else
+        vim.notify("claudecode.terminal.setup: Invalid value for snacks_win_opts", vim.log.levels.WARN)
+      end
+    elseif k == "cwd" then
+      if v == nil or type(v) == "string" then
+        defaults.cwd = v
+      else
+        vim.notify("claudecode.terminal.setup: Invalid value for cwd: " .. tostring(v), vim.log.levels.WARN)
+      end
+    elseif k == "git_repo_cwd" then
+      if type(v) == "boolean" then
+        defaults.git_repo_cwd = v
       else
-        vim.notify("claudecode.terminal.setup: Invalid value for " .. k .. ": " .. tostring(v), vim.log.levels.WARN)
+        vim.notify("claudecode.terminal.setup: Invalid value for git_repo_cwd: " .. tostring(v), vim.log.levels.WARN)
+      end
+    elseif k == "cwd_provider" then
+      local t = type(v)
+      if t == "function" then
+        defaults.cwd_provider = v
+      elseif t == "table" then
+        local mt = getmetatable(v)
+        if mt and mt.__call then
+          defaults.cwd_provider = v
+        else
+          vim.notify(
+            "claudecode.terminal.setup: cwd_provider table is not callable (missing __call)",
+            vim.log.levels.WARN
+          )
+        end
+      else
+        vim.notify("claudecode.terminal.setup: Invalid cwd_provider type: " .. tostring(t), vim.log.levels.WARN)
       end
     else
-      vim.notify("claudecode.terminal.setup: Unknown configuration key: " .. k, vim.log.levels.WARN)
+      if k ~= "terminal_cmd" then
+        vim.notify("claudecode.terminal.setup: Unknown configuration key: " .. k, vim.log.levels.WARN)
+      end
     end
   end
 
diff --git a/lua/claudecode/terminal/native.lua b/lua/claudecode/terminal/native.lua
@@ -88,6 +88,7 @@ local function open_terminal(cmd_string, env_table, effective_config, focus)
 
   jobid = vim.fn.termopen(term_cmd_arg, {
     env = env_table,
+    cwd = effective_config.cwd,
     on_exit = function(job_id, _, _)
       vim.schedule(function()
         if job_id == jobid then
diff --git a/lua/claudecode/terminal/snacks.lua b/lua/claudecode/terminal/snacks.lua
@@ -50,6 +50,7 @@ local function build_opts(config, env_table, focus)
   focus = utils.normalize_focus(focus)
   return {
     env = env_table,
+    cwd = config.cwd,
     start_insert = focus,
     auto_insert = focus,
     auto_close = false,
diff --git a/lua/claudecode/types.lua b/lua/claudecode/types.lua
diff --git a/tests/integration/command_args_spec.lua b/tests/integration/command_args_spec.lua
