feat(tools): add get_changed_files tool (#1777)

olimorris · web-flow · commit ed5c493eaf54 · 2025-07-11T00:01:36.000+01:00
diff --git a/doc/getting-started.md b/doc/getting-started.md
@@ -110,16 +110,17 @@ _Tools_, accessed via `@`, allow the LLM to function as an agent and carry out a
 
 - `cmd_runner` - The LLM will run shell commands (subject to approval)
 - `create_file` - The LLM will create a file in the current working directory (subject to approval)
-- `file_search` - The LLM can search for a file in the current working directory
-- `grep_search` - The LLM can search within files in the current working directory
+- `file_search` - The LLM can search for a file in the CWD
+- `get_changed_files` - The LLM can get git diffs for any changed files in the CWD
+- `grep_search` - The LLM can search within files in the CWD
 - `insert_edit_into_file` - The LLM will edit code in a Neovim buffer or on the file system (subject to approval)
 - `next_edit_suggestion` - The LLM can show the user where the next edit is
 - `read_file` - The LLM can read a specific file
 - `web_search` -  The LLM can search the internet for information
 
 Tools can also be grouped together, also accessible via `@` in the chat buffer:
 
-- `files` - Contains the `create_file`, `file_search`, `grep_search`, `insert_edit_into_file` and `read_file` tools
+- `files` - Contains the `create_file`, `file_search`, `get_changed_files`, `grep_search`, `insert_edit_into_file` and `read_file` tools
 
 > [!TIP]
 > Use them in your prompt like: `Can you use the @{grep_search} tool to find occurrences of "add_message"`, ensuring they're wrapped in curly brackets
diff --git a/doc/usage/chat-buffer/agents.md b/doc/usage/chat-buffer/agents.md
@@ -51,6 +51,9 @@ Some commands do not write any data to [stdout](https://en.wikipedia.org/wiki/St
 
 The LLM is specifically instructed to detect if you're running a test suite, and if so, to insert a flag in its request. This is then detected and the outcome of the test is stored in the corresponding flag on the chat buffer. This makes it ideal for [workflows](/extending/workflows) to hook into.
 
+**Options:**
+- `requires_approval` require approval before running a command? (Default: true)
+
 ## create_file
 
 > [!NOTE]
@@ -62,6 +65,9 @@ Create a file within the current working directory:
 Can you create some test fixtures using the @{create_file} tool?
 ```
 
+**Options:**
+- `requires_approval` require approval before creating a file? (Default: true)
+
 ## file_search
 
 This tool enables an LLM to search for files in the current working directory by glob pattern. It will return a list of relative paths for any matching files.
@@ -70,6 +76,20 @@ This tool enables an LLM to search for files in the current working directory by
 Use the @{file_search} tool to list all the lua files in my project
 ```
 
+**Options:**
+- `max_results` limits the amount of results that can be sent to the LLM in the response (Default: 500)
+
+## get_changed_files
+
+This tool enables an LLM to get git diffs of any file changes in the current working directory. It will return a diff which can contain `staged`, `unstaged` and `merge-conflicts`.
+
+```md
+Use the @{get_changed_files} tool see what's changed
+```
+
+**Options:**
+- `max_lines` limits the amount of lines that can be sent to the LLM in the response (Default: 1000)
+
 ## grep_search
 
 > [!IMPORTANT]
@@ -81,6 +101,10 @@ This tool enables an LLM to search for text, within files, in the current workin
 Use the @{grep_search} tool to find all occurrences of `buf_add_message`?
 ```
 
+**Options:**
+- `max_files` (number) limits the amount of files that can be sent to the LLM in the response (Default: 100)
+- `respect_gitignore` (boolean) (Default: true)
+
 ## insert_edit_into_file
 
 > [!NOTE]
@@ -100,6 +124,11 @@ Use the @{insert_edit_into_file} tool to refactor the code in #buffer
 Can you apply the suggested changes to the buffer with the @{insert_edit_into_file} tool?
 ```
 
+**Options:**
+- `requires_approval.buffer` (boolean) Require approval before editng a buffer? (Default: false)
+- `requires_approval.file` (boolean) Require approval before editng a file? (Default: true)
+- `user_confirmation` (boolean) require confirmation from the user before moving on in the chat buffer? (Default: true)
+
 ## next_edit_suggestion
 
 Inspired by [Copilot Next Edit Suggestion](https://code.visualstudio.com/blogs/2025/02/12/next-edit-suggestions), the `@next_edit_suggestion` tool gives the LLM the ability to show the user where the next edit is. The LLM can only suggest edits in files or buffers that have been shared with it as context.
@@ -150,8 +179,8 @@ Using the @web_search tool to search from `https://neovim.io` and explain how I
 
 CodeCompanion comes with two built-in tool groups:
 
-- `full_stack_dev` - Contains `cmd_runner`, `create_file`, `read_file`, and `insert_edit_into_file` tools
-- `files` - Contains `create_file`, `read_file`, and `insert_edit_into_file` tools
+- `full_stack_dev` - Containing all of the tools
+- `files` - Containing `create_file`, `file_search`, `get_changed_files`, `grep_search`, `insert_edit_into_file` and `read_file` tools
 
 When you include a tool group in your chat (e.g., `@{files}`), all tools within that group become available to the LLM. By default, all the tools in the group will be shown as a single `<group>name</group>` reference in the chat buffer.
 
diff --git a/lua/codecompanion/config.lua b/lua/codecompanion/config.lua
@@ -60,6 +60,7 @@ local defaults = {
               "cmd_runner",
               "create_file",
               "file_search",
+              "get_changed_files",
               "grep_search",
               "insert_edit_into_file",
               "read_file",
@@ -74,6 +75,8 @@ local defaults = {
             tools = {
               "create_file",
               "file_search",
+              "get_changed_files",
+              "grep_search",
               "insert_edit_into_file",
               "read_file",
             },
@@ -103,6 +106,13 @@ local defaults = {
             max_results = 500,
           },
         },
+        ["get_changed_files"] = {
+          callback = "strategies.chat.agents.tools.get_changed_files",
+          description = "Get git diffs of current file changes in a git repository",
+          opts = {
+            max_lines = 1000,
+          },
+        },
         ["grep_search"] = {
           callback = "strategies.chat.agents.tools.grep_search",
           enabled = function()
diff --git a/lua/codecompanion/strategies/chat/agents/tools/get_changed_files.lua b/lua/codecompanion/strategies/chat/agents/tools/get_changed_files.lua
@@ -0,0 +1,149 @@
+local Job = require("plenary.job")
+local log = require("codecompanion.utils.log")
+
+local fmt = string.format
+
+---@param state string
+---@return string[]|nil, string|nil
+local function get_git_diff(state, opts)
+  local cmd, desc
+  if state == "staged" then
+    cmd = { "git", "diff", "--cached" }
+    desc = "staged"
+  elseif state == "unstaged" then
+    cmd = { "git", "diff" }
+    desc = "unstaged"
+  elseif state == "merge-conflicts" then
+    cmd = { "git", "diff", "--name-only", "--diff-filter=U" }
+    desc = "merge-conflicts"
+  else
+    return nil, nil
+  end
+
+  local ok, result = pcall(function()
+    return Job:new({ command = cmd[1], args = vim.list_slice(cmd, 2), cwd = vim.fn.getcwd() }):sync()
+  end)
+  if not ok then
+    return nil, desc
+  end
+
+  if result and #result > opts.max_lines then
+    result = vim.list_slice(result, 1, opts.max_lines)
+    table.insert(result, "... (diff output truncated)")
+  end
+
+  return result, desc
+end
+
+---Get changed files in the current working directory based on the git state.
+---@param action {source_control_state?: string[]}
+---@param opts {max_lines: number}
+---@return {status: "success"|"error", data: string}
+local function get_changed_files(action, opts)
+  local states = action.source_control_state or { "unstaged", "staged", "merge-conflicts" }
+  local output = {}
+
+  for _, state in ipairs(states) do
+    local result, desc = get_git_diff(state, opts)
+    if desc then
+      if state == "merge-conflicts" then
+        if result and #result > 0 then
+          table.insert(
+            output,
+            fmt(
+              [[<getChangedFiles type="%s">
+- %s
+</getChangedFiles]],
+              desc,
+              table.concat(result, "\n- ")
+            )
+          )
+        end
+      else
+        if result and #result > 0 then
+          table.insert(
+            output,
+            fmt(
+              [[<getChangedFiles type="%s">
+```diff
+%s
+```
+</getChangedFiles>]],
+              desc,
+              table.concat(result, "\n")
+            )
+          )
+        end
+      end
+    end
+  end
+
+  if vim.tbl_isempty(output) then
+    return {
+      status = "success",
+      data = "No changed files found.",
+    }
+  end
+
+  return {
+    status = "success",
+    data = table.concat(output, "\n\n"),
+  }
+end
+
+---@class CodeCompanion.Tool.GetChangedFiles: CodeCompanion.Agent.Tool
+return {
+  name = "get_changed_files",
+  cmds = {
+    ---@param self CodeCompanion.Tool.GetChangedFiles
+    ---@param args table
+    ---@param input? any
+    function(self, args, input)
+      return get_changed_files(args, self.tool.opts)
+    end,
+  },
+  schema = {
+    type = "function",
+    ["function"] = {
+      name = "get_changed_files",
+      description = "Get git diffs of current file changes in the current working directory.",
+      parameters = {
+        type = "object",
+        properties = {
+          source_control_state = {
+            type = "array",
+            items = {
+              type = "string",
+              enum = { "staged", "unstaged", "merge-conflicts" },
+            },
+            description = "The kinds of git state to filter by. Allowed values are: 'staged', 'unstaged', and 'merge-conflicts'. If not provided, all states will be included.",
+          },
+        },
+      },
+    },
+  },
+  handlers = {
+    on_exit = function(agent)
+      log:trace("[Insert Edit Into File Tool] on_exit handler executed")
+    end,
+  },
+  output = {
+    prompt = function(self, agent)
+      return "Get changed files in the git repository?"
+    end,
+    success = function(self, agent, cmd, stdout)
+      local chat = agent.chat
+      local output = vim.iter(stdout):flatten():join("\n")
+      chat:add_tool_output(self, output, "Reading changed files")
+    end,
+    error = function(self, agent, cmd, stderr, stdout)
+      local chat = agent.chat
+      local errors = vim.iter(stderr):flatten():join("\n")
+      chat:add_tool_output(self, errors)
+    end,
+    rejected = function(self, agent, cmd)
+      local chat = agent.chat
+      chat:add_tool_output(self, "The user declined to get changed files")
+    end,
+  },
+}
diff --git a/lua/codecompanion/strategies/chat/ui/formatters/tools.lua b/lua/codecompanion/strategies/chat/ui/formatters/tools.lua
@@ -35,12 +35,12 @@ function Tools:format(message, opts, state)
     return lines, nil
   end
 
-  -- Folds can only work up to the penultimate line in the buffer. So we add an
-  -- empty line as a result. But...we don't want to fold this line
+  -- Folds can only work up to the penultimate line in the buffer, so an extra
+  -- line has been added as a result. But, we don't want to fold this line
   local content_end = #lines - 1
 
   local fold_info = nil
-  if content_end > content_start then
+  if content_end >= content_start then
     fold_info = {
       start_offset = content_start - 1, -- 0-based index
       end_offset = content_end - 1, -- 0-based index
diff --git a/lua/codecompanion/strategies/chat/ui/tools.lua b/lua/codecompanion/strategies/chat/ui/tools.lua
@@ -116,6 +116,11 @@ function Tools:create_fold(start_line, end_line, foldtext)
     priority = 200,
   })
 
+  -- Some tools only have a single line of output, so we don't want to fold it
+  if start_line == end_line then
+    return
+  end
+
   -- Create the fold
   self.fold_summaries[self.chat_bufnr] = self.fold_summaries[self.chat_bufnr] or {}
   self.fold_summaries[self.chat_bufnr][start_line] = foldtext
diff --git a/tests/screenshots/tests-strategies-chat-agents-tools-test_tool_output.lua---Tool-output---Folds---does-not-fold-single-line-output-but-applies-extmarks b/tests/screenshots/tests-strategies-chat-agents-tools-test_tool_output.lua---Tool-output---Folds---does-not-fold-single-line-output-but-applies-extmarks
@@ -9,9 +9,9 @@
 08|I've found some awesome weather     │~                                          
 09|data for you:                       │~                                          
 10|                                    │~                                          
-11|**Weather Tool**: Ran successfully  │~                                          
-12|                                    │~                                          
-13|~                                   │~                                          
+11|!! **Weather Tool**: Ran            │~                                          
+12|successfully                        │~                                          
+13|                                    │~                                          
 14|~                                   │~                                          
 15|~                                   │~                                          
 16|~                                   │~                                          
@@ -35,9 +35,9 @@
 08|00000000000000000000000000000000000012222222222222222222222222222222222222222222
 09|00000000000000000000000000000000000012222222222222222222222222222222222222222222
 10|00000000000000000000000000000000000012222222222222222222222222222222222222222222
-11|00000000000000000000000000000000000012222222222222222222222222222222222222222222
+11|33300000000000000000000000000000000012222222222222222222222222222222222222222222
 12|00000000000000000000000000000000000012222222222222222222222222222222222222222222
-13|22222222222222222222222222222222222212222222222222222222222222222222222222222222
+13|00000000000000000000000000000000000012222222222222222222222222222222222222222222
 14|22222222222222222222222222222222222212222222222222222222222222222222222222222222
 15|22222222222222222222222222222222222212222222222222222222222222222222222222222222
 16|22222222222222222222222222222222222212222222222222222222222222222222222222222222
