Currently supports: Anthropic, Copilot, Gemini, Ollama and OpenAI adapters

New features are always announced here

💜 Sponsors

Thank you to the following people:

✨ Features

• 💬 Copilot Chat meets Zed AI, in Neovim
• 🔌 Support for Anthropic, Copilot, Gemini, Ollama and OpenAI LLMs (or bring your own!)
• 🚀 Inline transformations, code creation and refactoring
• 🤖 Variables, Slash Commands, Agents/Tools and Workflows to improve LLM output
• ✨ Built in prompts for common tasks like advice on LSP errors and code explanations
• 🏗️ Ability to create your own custom prompts, Variables and Slash Commands
• 💪 Async execution for fast performance

📸 Screenshots

Code.Companion.mp4

⚡ Requirements

• The curl library
• Neovim 0.9.2 or greater
• (Optional) An API key for your chosen LLM

📦 Installation

Install the plugin with your preferred package manager:

Lazy.nvim

{
  "olimorris/codecompanion.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "nvim-treesitter/nvim-treesitter",
    "hrsh7th/nvim-cmp", -- Optional: For using slash commands and variables in the chat buffer
    "nvim-telescope/telescope.nvim", -- Optional: For using slash commands
    { "stevearc/dressing.nvim", opts = {} }, -- Optional: Improves the default Neovim UI
  },
  config = true
}

Packer

use({
  "olimorris/codecompanion.nvim",
  config = function()
    require("codecompanion").setup()
  end,
  requires = {
    "nvim-lua/plenary.nvim",
    "nvim-treesitter/nvim-treesitter",
    "hrsh7th/nvim-cmp", -- Optional: For using slash commands and variables in the chat buffer
    "nvim-telescope/telescope.nvim", -- Optional: For using slash commands
    "stevearc/dressing.nvim" -- Optional: Improves the default Neovim UI
  }
})

vim-plug

call plug#begin()

Plug 'nvim-lua/plenary.nvim'
Plug 'nvim-treesitter/nvim-treesitter'
Plug 'hrsh7th/nvim-cmp', " Optional: For using slash commands and variables in the chat buffer
Plug 'nvim-telescope/telescope.nvim', " Optional: For using slash commands
Plug 'stevearc/dressing.nvim' " Optional: Improves the default Neovim UI
Plug 'olimorris/codecompanion.nvim'

call plug#end()

lua << EOF
  require("codecompanion").setup()
EOF

Important

The plugin requires the markdown Tree-sitter parser to be installed with :TSInstall markdown

Telescope.nvim is a suggested inclusion in order to leverage Slash Commands. However other providers are available. Please refer to the Chat Buffer section for more information.

🚀 Quickstart

Note

Okay, okay...it's not quite a quickstart as you'll need to configure an adapter first.

Chat Buffer

Run :CodeCompanionChat to open the chat buffer. Type your prompt and press <CR>. Toggle the chat buffer with :CodeCompanionToggle.

You can add context from your code base by using Variables and Slash Commands in the chat buffer.

Variables, accessed via #, contain data about the present state of Neovim:

• #buffer - Shares the current buffer's code. You can also specify line numbers with #buffer:8-20
• #editor - Shares the buffers and lines that you see in the Neovim viewport
• #lsp - Shares LSP information and code for the current buffer

Slash commands, accessed via /, run commands to insert additional context into the chat buffer:

• /buffer - Insert open buffers
• /file - Insert a file
• /help - Insert content from help tags
• /now - Insert the current date and time
• /symbols - Insert symbols for the active buffer
• /terminal - Insert terminal output

Tools, accessed via @, allow the LLM to function as an agent and carry out actions:

• @code_runner - The LLM will run code for you in a Docker container
• @editor - The LLM will edit code in a Neovim buffer
• @rag - The LLM will browse and search the internet for real-time information to supplement its response

Tip

Press ? in the chat buffer to reveal the keymaps and options that are available.

Inline Assistant

Run :CodeCompanion <your prompt> to call the inline assistant. The assistant will evaluate the prompt and either write code or open a chat buffer. You can also make a visual selection and call the assistant.

The assistant has knowledge of your last conversation from a chat buffer. A prompt such as :CodeCompanion add the new function here will see the assistant add a code block directly into the current buffer.

For convenience, you can call pre-defined prompts via the assistant such as :'<,'>CodeCompanion /buffer what does this file do?. The pre-defined prompts, by default, are:

• /buffer - Send the current buffer to the LLM alongside a prompt
• /commit - Generate a commit message
• /explain - Explain how selected code in a buffer works
• /fix - Fix the selected code
• /lsp - Explain the LSP diagnostics for the selected code
• /tests - Generate unit tests for selected code

There are keymaps available to accept or reject edits from the LLM in the inline assistant section.

Action Palette

Run :CodeCompanionActions to open the action palette, which gives you access to all of the functionality in the plugin. This is where core actions and the pre-defined prompts are listed.

Note

Some actions and prompts will only be visible if you're in Visual mode.

List of commands

Below is a list of all commands in the plugin:

• CodeCompanion - Open the inline assistant
• CodeCompanion <your prompt> - Prompt the inline assistant
• CodeCompanion /<slash_cmd> - Prompt the inline assistant with a slash command e.g. /commit
• CodeCompanionChat - Open a chat buffer
• CodeCompanionChat <adapter> - Open a chat buffer with a specific adapter
• CodeCompanionToggle - Toggle a chat buffer
• CodeCompanionActions - Open the Action Palette
• CodeCompanionAdd - Add visually selected chat to the current chat buffer

Suggested workflow

For an optimum workflow, I recommend the following keymaps:

vim.api.nvim_set_keymap("n", "<C-a>", "<cmd>CodeCompanionActions<cr>", { noremap = true, silent = true })
vim.api.nvim_set_keymap("v", "<C-a>", "<cmd>CodeCompanionActions<cr>", { noremap = true, silent = true })
vim.api.nvim_set_keymap("n", "<LocalLeader>a", "<cmd>CodeCompanionToggle<cr>", { noremap = true, silent = true })
vim.api.nvim_set_keymap("v", "<LocalLeader>a", "<cmd>CodeCompanionToggle<cr>", { noremap = true, silent = true })
vim.api.nvim_set_keymap("v", "ga", "<cmd>CodeCompanionAdd<cr>", { noremap = true, silent = true })

-- Expand 'cc' into 'CodeCompanion' in the command line
vim.cmd([[cab cc CodeCompanion]])

⚙️ Configuration

Before configuring the plugin, it's important to understand how it's structured.

The plugin uses adapters to connect to LLMs. Out of the box, the plugin supports:

• Anthropic (anthropic) - Requires an API key and supports prompt caching
• Copilot (copilot) - Requires a token which is created via :Copilot setup in Copilot.vim
• Gemini (gemini) - Requires an API key
• Ollama (ollama) - Both local and remotely hosted
• OpenAI (openai) - Requires an API key

The plugin also utilises objects called Strategies. These are the different ways that a user can interact with the plugin. The chat and agent strategies harness a buffer to allow direct conversation with the LLM. The inline strategy allows for output from the LLM to be written directly into a pre-existing Neovim buffer.

The plugin allows you to specify adapters for each strategy and also for each pre-defined prompt.

🛠️ Changing the Defaults

The default config can be found here and they can be changed by calling the setup function:

require("codecompanion").setup({
  display = {
    diff = {
      provider = "mini_diff",
    },
  },
  opts = {
    log_level = "DEBUG",
  },
})

Please refer to the section below in order to configure adapters.

Changing the System Prompt

The default system prompt has been carefully curated to deliver responses which are similar to GitHub Copilot Chat, no matter which LLM you use. That is, you'll receive responses which are terse, professional and with expertise in coding. However, you can modify the opts.system_prompt table in the config to suit your needs. You can also set it as a function which can receive the current chat buffer's adapter as a parameter, giving you the option of setting system prompts that are LLM or model specific:

require("codecompanion").setup({
  opts = {
    ---@param adapter CodeCompanion.Adapter
    ---@return string
    system_prompt = function(adapter)
      if adapter.schema.model.default == "llama3.1:latest" then
        return "My custom system prompt"
      end
      return "My default system prompt"
    end
  }
})

🔌 Adapters

Please refer to your chosen adapter to understand its configuration. You will need to set an API key for non-locally hosted LLMs.

Tip

To create your own adapter or better understand how they work, please refer to the ADAPTERS guide.

Changing the Default Adapter

To specify a different adapter to the default (openai), simply change the strategies.* table:

require("codecompanion").setup({
  strategies = {
    chat = {
      adapter = "anthropic",
    },
    inline = {
      adapter = "copilot",
    },
    agent = {
      adapter = "anthropic",
    },
  },
})

Setting an API Key

require("codecompanion").setup({
  adapters = {
    anthropic = function()
      return require("codecompanion.adapters").extend("anthropic", {
        env = {
          api_key = "MY_OTHER_ANTHROPIC_KEY"
        },
      })
    end,
  },
})

In the example above, we're using the base of the Anthropic adapter but changing the name of the default API key which it uses.

Setting an API Key Using a Command

Having API keys in plain text in your shell is not always safe. Thanks to this PR, you can run commands from within your config by prefixing them with cmd:. In the example below, we're using the 1Password CLI to read an OpenAI credential.

require("codecompanion").setup({
  adapters = {
    openai = function()
      return require("codecompanion.adapters").extend("openai", {
        env = {
          api_key = "cmd:op read op://personal/OpenAI/credential --no-newline",
        },
      })
    end,
  },
})

Using Ollama Remotely

To use Ollama remotely, change the URL in the env table, set an API key and pass it via an "Authorization" header:

require("codecompanion").setup({
  adapters = {
    ollama = function()
      return require("codecompanion.adapters").extend("ollama", {
        env = {
          url = "https://my_ollama_url",
          api_key = "OLLAMA_API_KEY",
        },
        headers = {
          ["Content-Type"] = "application/json",
          ["Authorization"] = "Bearer ${api_key}",
        },
        parameters = {
          sync = true,
        },
      })
    end,
  },
})

Connecting via a Proxy

You can also connect via a Proxy:

require("codecompanion").setup({
  adapters = {
    opts = {
      allow_insecure = true, -- Use if required
      proxy = "socks5://127.0.0.1:9999"
    }
  },
})

Changing an Adapter's Default Model

A common ask is to change an adapter's default model. This can be done by altering the schema.model.default table:

require("codecompanion").setup({
  adapters = {
    anthropic = function()
      return require("codecompanion.adapters").extend("anthropic", {
        schema = {
          model = {
            default = "claude-3-opus-20240229",
          },
        },
      })
    end,
  },
})

Configuring Adapter Settings

LLMs have many settings such as model, temperature and max_tokens. In an adapter, these sit within a schema table and can be configured during setup:

require("codecompanion").setup({
  adapters = {
    llama3 = function()
      return require("codecompanion.adapters").extend("ollama", {
        name = "llama3", -- Give this adapter a different name to differentiate it from the default ollama adapter
        schema = {
          model = {
            default = "llama3:latest",
          },
          num_ctx = {
            default = 16384,
          },
          num_predict = {
            default = -1,
          },
        },
      })
    end,
  },
})

💡 Advanced Usage

📋 Pre-Defined Prompts

The plugin comes with a number of pre-defined prompts. As per the config, these can be called via keymaps or slash commands (via the inline assistant). These prompts have been carefully curated to mimic those in GitHub's Copilot Chat. Of course, you can create your own prompts and add them to the Action Palette. Please see the RECIPES guide for more information.

💬 The Chat Buffer

The chat buffer is where you converse with an LLM from within Neovim. The chat buffer has been designed to be turn based, whereby you send a message and the LLM replies. Messages are segmented by H2 headers and once a message has been sent, it cannot be edited. You can also have multiple chat buffers open at the same.

The look and feel of the chat buffer can be customised as per the display.chat table in the config. You can also add additional Variables and Slash Commands which can then be referenced in the chat buffer.

Keymaps

When in the chat buffer, there are number of keymaps available to you:

• ? - Bring up the menu that lists the keymaps and commands
• <CR>|<C-s> - Send the buffer to the LLM
• <C-c> - Close the buffer
• q - Cancel the request from the LLM
• gr - Regenerate the last response from the LLM
• ga - Change the adapter
• gx - Clear the buffer's contents
• gx - Add a codeblock
• gf - To refresh the code folds in the buffer
• } - Move to the next chat
• { - Move to the previous chat
• ]] - Move to the next header
• [[ - Move to the previous header

Settings

You can display your selected adapter's schema at the top of the buffer, if display.chat.show_settings is set to true. This allows you to vary the response from the LLM.

Slash Commands

As outlined in the Quickstart section, Slash Commands allow you to easily share additional context with your LLM from the chat buffer. Some of the Slash Commands allow to change the default provider:

• /buffer - Has a default provider (which leverages vim.ui.select) alongside telescope and fzf_lua providers
• /files - Has telescope, mini_pick and fzf_lua providers

Please refer to the config to see how to change the default provider.

✏️ Inline Assistant

Note

If you've set opts.send_code = false in your config then the plugin will endeavour to ensure no code is sent to the LLM.

One of the challenges with inline editing is determining how the LLM's response should be handled in the buffer. If you've prompted the LLM to "create a table of 5 common text editors" then you may wish for the response to be placed at the cursor's position in the current buffer. However, if you asked the LLM to "refactor this function" then you'd expect the response to replace a visual selection. The plugin will use the inline LLM you've specified in your config to determine if the response should...

• replace - replace a visual selection you've made
• add - be added in the current buffer at the cursor position
• new - be placed in a new buffer
• chat - be placed in a chat buffer

By default, an inline assistant prompt will trigger the diff feature, showing differences between the original buffer and the changes from the LLM. This can be turned off in your config via the display.inline.diff table. You can also choose to accept or reject the LLM's suggestions with the following keymaps:

• ga - Accept an inline edit
• gr - Reject an inline edit

🤖 Agents / Tools

Agents.mp4

As outlined by Andrew Ng in Agentic Design Patterns Part 3, Tool Use, LLMs can act as agents by leveraging external tools. Andrew notes some common examples such as web searching or code execution that have obvious benefits when using LLMs.

In the plugin, agents are simply context that's given to an LLM via a system prompt. This gives it knowledge and a defined schema which it can include in its response for the plugin to parse, execute and feedback on. Agents can be added as a participant to the chat buffer by using the @ key.

More information on how agents work and how you can create your own can be found in the TOOLS guide.

🗺️ Workflows

Warning

Workflows may result in the significant consumption of tokens if you're using an external LLM.

As outlined by Andrew Ng, agentic workflows have the ability to dramatically improve the output of an LLM. Infact, it's possible for older models like GPT 3.5 to outperform newer models (using traditional zero-shot inference). Andrew discussed how an agentic workflow can be utilised via multiple prompts that invoke the LLM to self reflect. Implementing Andrew's advice, the plugin supports this notion via the use of workflows. At various stages of a pre-defined workflow, the plugin will automatically prompt the LLM without any input or triggering required from the user.

Currently, the plugin comes with the following workflows:

• Adding a new feature
• Refactoring code

Of course you can add new workflows by following the RECIPES guide.

🍭 Extras

Highlight Groups

The plugin sets the following highlight groups during setup:

• CodeCompanionChatHeader - The headers in the chat buffer
• CodeCompanionChatSeparator - Separator between headings in the chat buffer
• CodeCompanionChatTokens - Virtual text in the chat buffer showing the token count
• CodeCompanionChatTool - Tools in the chat buffer
• CodeCompanionChatVariable - Variables in the chat buffer
• CodeCompanionVirtualText - All other virtual text in the plugin

Events/Hooks

The plugin fires many events during its lifecycle:

• CodeCompanionToolAdded - Fired when a tool has been added to a chat buffer
• CodeCompanionChatClosed - Fired after a chat has been closed
• CodeCompanionChatAdapter - Fired after the adapter has been set in the chat
• CodeCompanionAgentStarted - Fired when an agent has started using a tool
• CodeCompanionAgentFinished - Fired when an agent has finished using a tool
• CodeCompanionInlineStarted - Fired at the start of the Inline strategy
• CodeCompanionInlineFinished - Fired at the end of the Inline strategy
• CodeCompanionRequestStarted - Fired at the start of any API request
• CodeCompanionRequestFinished - Fired at the end of any API request
• CodeCompanionDiffAttached - Fired when in Diff mode
• CodeCompanionDiffDetached - Fired when exiting Diff mode

Tip

Some events are sent with a data payload which can be leveraged.

Events can be hooked into as follows:

local group = vim.api.nvim_create_augroup("CodeCompanionHooks", {})

vim.api.nvim_create_autocmd({ "User" }, {
  pattern = "CodeCompanionInline*",
  group = group,
  callback = function(request)
    if request.match == "CodeCompanionInlineFinished" then
      -- Format the buffer after the inline request has completed
      require("conform").format({ bufnr = request.buf })
    end
  end,
})

Statuslines

You can incorporate a visual indication to show when the plugin is communicating with an LLM in your Neovim configuration. Below are examples for two popular statusline plugins.

lualine.nvim:

local M = require("lualine.component"):extend()

M.processing = false
M.spinner_index = 1

local spinner_symbols = {
  "⠋",
  "⠙",
  "⠹",
  "⠸",
  "⠼",
  "⠴",
  "⠦",
  "⠧",
  "⠇",
  "⠏",
}
local spinner_symbols_len = 10

-- Initializer
function M:init(options)
  M.super.init(self, options)

  local group = vim.api.nvim_create_augroup("CodeCompanionHooks", {})

  vim.api.nvim_create_autocmd({ "User" }, {
    pattern = "CodeCompanionRequest*",
    group = group,
    callback = function(request)
      if request.match == "CodeCompanionRequestStarted" then
        self.processing = true
      elseif request.match == "CodeCompanionRequestFinished" then
        self.processing = false
      end
    end,
  })
end

-- Function that runs every time statusline is updated
function M:update_status()
  if self.processing then
    self.spinner_index = (self.spinner_index % spinner_symbols_len) + 1
    return spinner_symbols[self.spinner_index]
  else
    return nil
  end
end

return M

heirline.nvim:

local CodeCompanion = {
  static = {
    processing = false,
  },
  update = {
    "User",
    pattern = "CodeCompanionRequest*",
    callback = function(self, args)
      if args.match == "CodeCompanionRequestStarted" then
        self.processing = true
      elseif args.match == "CodeCompanionRequestFinished" then
        self.processing = false
      end
      vim.cmd("redrawstatus")
    end,
  },
  {
    condition = function(self)
      return self.processing
    end,
    provider = " ",
    hl = { fg = "yellow" },
  },
}

Legendary.nvim

The plugin also supports the amazing legendary.nvim plugin. Simply enable it in your config:

require('legendary').setup({
  extensions = {
    codecompanion = true,
  },
})

Mini.Diff

if you're using mini.diff you can put an icon in the statusline to indicate which diff is used currently, git or llm changes:

local function getDiffSource()
  local buf_id, diff_source, diffIcon
  buf_id = vim.api.nvim_get_current_buf()
  diff_source = vim.b[buf_id].diffCompGit
  if not diff_source then
    return ""
  end
  if diff_source == "git" then
    diffIcon = "󰊤 "
  elseif diff_source == "llm" then
    diffIcon = " "
  end
  return string.format("%%#StatusLineLSP#%s", diffIcon)
end

🧰 Troubleshooting

Before raising an issue, there are a number of steps you can take to troubleshoot a problem:

Checkhealth

Run :checkhealth codecompanion and check all dependencies are installed correctly. Also take note of the log file path.

Turn on logging

Update your config and turn debug logging on:

opts = {
  log_level = "DEBUG", -- or "TRACE"
}

and inspect the log file as per the location from the checkhealth command.

🎁 Contributing

I am open to contributions but they will be implemented at my discretion. Feel free to open up a discussion before embarking on a PR and please read the CONTRIBUTING.md guide.

👏 Acknowledgements

• Steven Arcangeli for his genius creation of the chat buffer and his feedback early on
• Dante.nvim for the beautifully simple diff implementation
• Wtf.nvim for the LSP assistant action
• CopilotChat.nvim for the rendering and usability of the chat buffer
• Aerial.nvim for the Tree-sitter parsing which as inspired the symbols Slash Command