Custom Instructions and Auto Buffers Context Support

[ravitemer]

I've been using CodeCompanion and implemented a way to include custom instructions like copilot-instructions.md and current buffer contexts in conversations with the LLM.
This has been super helpful with the @full_stack_dev (or I call @takeover) agent for generating code relevant to our project's guidelines and structure.
I'd like to share my approach and discuss potential improvements or official support for these features.

Current Implementation

I've extended the adapter's form_messages handler to inject two types of system messages:

1. Custom Project Instructions: Read from .github/copilot-instructions.md in the project root
2. Active Buffer Context: Information about currently open buffers and file structure

Custom Instructions

I'm reading project-specific instructions from .github/copilot-instructions.md in the project root or parent directories:

-- user/codecompanion/adapters/utils.lua
local function get_custom_instructions()
    local path = vim.fn.getcwd()
    while path ~= "/" do
        local instructions_path = path .. "/.github/copilot-instructions.md"
        if vim.fn.filereadable(instructions_path) == 1 then
            return vim.fn.readfile(instructions_path)
        end
        path = vim.fn.fnamemodify(path, ":h")
    end
    return nil
end

Buffer Context

I maintain an up-to-date list of active buffers and their content:

-- user/codecompanion/variables/bufs.lua
---Return the contents of all listed and loaded buffers
---@return string
function Variable:execute()
  local buffers_info = editor_utils.get_buffers_info()
  local output = {}

  -- First add visible buffers
  for _, buf_info in ipairs(buffers_info) do
    if buf_info.is_visible and vim.api.nvim_buf_is_loaded(buf_info.bufnr) then
      local buffer_content = buf_utils.format_with_line_numbers(buf_info.bufnr)
      buffer_content = "Visible Buffer:\n" .. buffer_content
      table.insert(output, buffer_content)
    end
  end

  -- Then add non-visible buffers
  for _, buf_info in ipairs(buffers_info) do
    if not buf_info.is_visible and vim.api.nvim_buf_is_loaded(buf_info.bufnr) then
      local buffer_content = buf_utils.format_with_line_numbers(buf_info.bufnr)
      table.insert(output, buffer_content)
    end
  end
  local active_buffers = table.concat(output, "\n\n")
  local file_structure = self:get_file_structure()
  return [[
=== Active Buffers ===

]] .. active_buffers .. [[

=== File Structure ]] .. self.layers .. [[ layers up ===

]] .. file_structure .. [[
  ]]
end

---Generate the file structure up to the specified number of layers
---@return string
function Variable:get_file_structure()
  local current_file_path = get_active_buf().filename
  local layers_up = self.layers
  local layers_deep = 3 -- Adjust as needed
  if self.params then
    local layersup, layersdown = self.params:match("(%d+)-(%d+)")
    if layersup and layersdown then
      layers_up = tonumber(layersup) or layers_up
      layers_deep = tonumber(layersdown) or layers_deep
    end
  end
  local ignore_dirs = { "^%.git$", "^node_modules$", "^.DS_Store$", "^__pycache__$" }
  local root_dir = file_utils.get_root_dir(current_file_path, layers_up)
  local file_structure = file_utils.generate_file_structure(root_dir, layers_deep, ignore_dirs)

  return [[
]] .. root_dir .. [[

]] .. file_structure .. [[
  ]]
end

Message Handling

I'm extending the Copilot adapter to include these contexts:

-- user/codecompanion/adapters/copilot.lua
handlers = {
    form_messages = function(adapter, messages)
        local obj = require("codecompanion.adapters.copilot").handlers.form_messages(adapter, messages)
        local _messages = utils.add_custom_instructions_message(obj.messages)
        _messages = utils.add_buffers_message(_messages, adapter)
        return {
            messages = _messages,
        }
    end,
}

To avoid duplicates, I check for existing context messages and update them:

-- user/codecompanion/adapters/utils.lua
local add_buffers_message = function(messages, chat)
    local bufs_message_index = utils.find_index(messages, function(message)
        return message.opts and message.opts.tag == "custom_buffers_message"
    end)
    local msg = get_buffers_message(chat)
    if bufs_message_index == -1 then
        table.insert(messages, 3, msg)
    else
        messages[bufs_message_index] = msg
    end
    return messages
end

Questions

1. Are there plans to support custom project-level instructions in CodeCompanion?
2. What would be the best way to implement this so that these context messages are visible in the debug view?
3. Would it make sense to have this as a core feature, allowing users to configure custom instructions and buffer context handling?

I'd appreciate any feedback on improving this implementation or guidance on a better approach that aligns with CodeCompanion's architecture.

[GitMurf]

@ravitemer wow this is amazing! Thank you for sharing! One question I have is how are you able to keep under token limits? It seems like I cannot do more than around 6,000 tokens at once or I get a plenary error. And this often is used up by a single medium size file. How are you able to include the full context of all your open buffers? Thanks!

EDIT: Update to my comment above! Now I can get a much higher context! The issue was a weird windows quirk and the plenary / curl api. See here for details: #427 (comment)

[ravitemer]

I use "copilot" adapter with

 schema = {
    model = {
      default = "claude-3.5-sonnet",
    },
    max_tokens = {
      default = 8192,
    },
}

I can open 6-7 buffers with each buffer having 150-200 lines everytime I ask a question. As this buffers message is replaced instead of adding to the chat history, everytime I continue the conversation I close any irrelevant buffers.

I do get the plenary error but only after 5-6 conversations.

[GitMurf]

@ravitemer wow this is amazing! Thank you for sharing! One question I have is how are you able to keep under token limits? It seems like I cannot do more than around 6,000 tokens at once or I get a plenary error. And this often is used up by a single medium size file. How are you able to include the full context of all your open buffers? Thanks!

UPDATE to my comment above! Now I can get a much higher context! The issue was a weird windows quirk and the plenary / curl api. See here for details: #427 (comment)

[ravitemer]

Finally! Awesome!

By the way I am on linux and this issue is not only for windows. However, It is fixed now using the temp json file. I just tested it by opening 30 buffers and can confirm the bug has been fixed.

Thanks

[GitMurf]

Finally! Awesome!

By the way I am on linux and this issue is not only for windows. However, It is fixed now using the temp json file. I just tested it by opening 30 buffers and can confirm the bug has been fixed.

Thanks

cc @olimorris This is great to hear helps Linux too!! And 30 buffers!! 👀

[arathunku]

@ravitemer, do you share your full codecompanion setup somewhere on github? This looks amazing! There's similar discussion #1080 so it looks like there's interest in supporting custom rules :)