neovimcraft github

plugins configs about

olimorris/codecompanion.nvim

github github
ai
stars 200
issues 2
subscribers 4
forks 18
CREATED

2023-12-27

UPDATED

yesterday

[!IMPORTANT] This plugin is provided as-is and is primarily developed for my own workflows. As such, I offer no guarantees of regular updates or support and I expect the plugin's API to change regularly. Bug fixes and feature enhancements will be implemented at my discretion, and only if they align with my personal use-cases. Feel free to fork the project and customize it to your needs, but please understand my involvement in further development will be intermittent. To be notified of breaking changes in the plugin, please subscribe to this issue.

:sparkles: Features

  • :speech_balloon: A Copilot Chat experience in Neovim
  • :electric_plug: Support for OpenAI, Anthropic and Ollama
  • :rocket: Inline code creation and refactoring
  • :robot: Variables, Agents and Workflows to improve LLM output
  • :sparkles: Built in prompts for LSP errors and code advice
  • :building_construction: Create your own custom prompts for Neovim
  • :floppy_disk: Save and restore your chats
  • :muscle: Async execution for improved performance

:camera_flash: Screenshots

:zap: Requirements

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

:package: Installation

Install the plugin with your preferred package manager:

Lazy.nvim

{
  "olimorris/codecompanion.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "nvim-treesitter/nvim-treesitter",
    "nvim-telescope/telescope.nvim", -- Optional
    {
      "stevearc/dressing.nvim", -- Optional: Improves the default Neovim UI
      opts = {},
    },
  },
  config = true
}

Packer

use({
  "olimorris/codecompanion.nvim",
  config = function()
    require("codecompanion").setup()
  end,
  requires = {
    "nvim-lua/plenary.nvim",
    "nvim-treesitter/nvim-treesitter",
    "nvim-telescope/telescope.nvim", -- Optional
    "stevearc/dressing.nvim" -- Optional: Improves the default Neovim UI
  }
})

:gear: Configuration

The default configuration can be found in the config.lua file. You can change any of the defaults by calling the setup function. For example:

require("codecompanion").setup({
  opts = {
    send_code = false
  }
})

Adapters

[!WARNING] Depending on your chosen adapter, you may need to set an API key.

The plugin uses adapters to connect the plugins to LLMs. Currently the plugin supports:

  • Anthropic (anthropic) - Requires an API key
  • Ollama (ollama)
  • OpenAI (openai) - Requires an API key

Strategies 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.

To specify a different adapter to the defaults, simply change the strategies.* table:

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

[!TIP] To create your own adapter please refer to the ADAPTERS guide.

Configuring environment variables

You can customise an adapter's configuration as follows:

require("codecompanion").setup({
  adapters = {
    anthropic = function()
      return require("codecompanion.adapters").use("anthropic", {
        env = {
          api_key = "ANTHROPIC_API_KEY_1"
        },
      })
    end,
  },
  strategies = {
    chat = {
      adapter = "anthropic",
    },
  },
})

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.

Having API keys in plain text in your shell is not always safe. Thanks to this PR, you can run commands from within the configuration:

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

In this example, we're using the 1Password CLI to read an OpenAI credential.

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 = {
    anthropic = function()
      return require("codecompanion.adapters").use("anthropic", {
        schema = {
          model = {
            default = "claude-3-sonnet-20240229",
          },
        },
      })
    end,
  },
})

[!TIP] Refer to your chosen adapter to see the settings available.

Highlight Groups

The plugin sets the following highlight groups during setup:

  • CodeCompanionTokens - Virtual text in the chat buffer showing the token count
  • CodeCompanionVirtualText - All other virtual text in the chat buffer
  • CodeCompanionVirtualTextAgents - Virtual text in the chat buffer for when a agent is running
  • CodeCompanionChatVariable - Variables in the chat buffer

[!TIP] You can change which highlight group these link to in your configuration.

:rocket: Getting Started

Inline Prompting

To start interacting with the plugin you can run :CodeCompanion <your prompt> from the command line. You can also make a visual selection in Neovim and run :'<,'>CodeCompanion <your prompt> to send it as context. The plugin will initially use an LLM to classify your prompt in order to determine where in Neovim to place the response. You can find more about the classificiations in the inline prompting section.

It's also possible to reference default prompts from the config using slash commands such as :'<,'>:CodeCompanion /advice. You can find more on this in the default prompts section.

Chat Buffer

The chat buffer is where you'll likely spend most of your time when interacting with the plugin. Running :CodeCompanionChat or :'<,'>CodeCompanionChat will open up a chat buffer where you can converse directly with an LLM. As a convenience, you can use :CodeCompanionToggle to toggle the visibility of a chat buffer.

When in the chat buffer you have access to the following variables:

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

There are also many keymaps you can leverage in the chat buffer which are covered in the chat buffer section of this readme.

Agents

The plugin also supports LLMs acting as agents by the calling of external tools. In the video above, we're asking an LLM to execute the contents of the buffer via the @code_runner tool, all from within a chat buffer.

When in the chat buffer you have access to the following agents:

  • @code_runner - The LLM can trigger the running of any code from within a Docker container
  • @rag - The LLM can browse and search the internet for real-time information to supplement its response
  • @buffer_editor - The LLM can edit code in a Neovim buffer by searching and replacing blocks

[!IMPORTANT] Agents are currently at an alpha stage right now and I'm using the term agent and tool interchangeably.

Action Palette

The :CodeCompanionActions command will open the Action Palette, giving you access to all of the functionality in the plugin. The Prompts section is where the default prompts and your custom ones can be accessed from. You'll notice that some prompts have a slash command in their description such as /commit. This enables you to trigger them from the command line by doing :CodeCompanion /commit. Some of these prompts also have keymaps assigned to them (which can be overwritten!) which offers an even easier route to triggering them.

[!NOTE] Some actions will only be visible in the Action Palette if you're in Visual mode.

List of commands

Below is the full list of commands that are available in the plugin:

  • CodeCompanionActions - To open the Action Palette
  • CodeCompanion - Inline prompting of the plugin
  • CodeCompanion <slash_cmd> - Inline prompting of the plugin with a slash command e.g. /commit
  • CodeCompanionChat - To open up a new chat buffer
  • CodeCompanionChat <adapter> - To open up a new chat buffer with a specific adapter
  • CodeCompanionToggle - To toggle a chat buffer
  • CodeCompanionAdd - To add visually selected chat to the current chat buffer

Suggested workflow

For an optimum workflow, I recommend the following options:

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]])

:bulb: Advanced Usage

Customising the Action Palette

A RECIPES guide has been created to show you how you can add your own prompts to the Action Palette.

The Chat Buffer

The chat buffer is where you can converse with an LLM, directly from Neovim. It behaves as a regular markdown buffer with some clever additions. When the buffer is written (or "saved"), autocmds trigger the sending of its content to the LLM in the form of prompts. These prompts are segmented by H1 headers: user, system and assistant. When a response is received, it is then streamed back into the buffer. The result is that you experience the feel of conversing with your LLM from within Neovim.

As noted in the Getting Started section, there are a number of variables that you can make use of whilst in the chat buffer. Use # to bring up the completion menu to see the available options.

Keymaps

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

  • <C-s> - Save the buffer and trigger a response from the LLM
  • <C-c> - Close the buffer
  • q - Cancel the stream from the LLM
  • gc - Clear the buffer's contents
  • ga - Add a codeblock
  • gs - Save the chat to disk
  • gt - Add an agent to an existing chat
  • [ - Move to the next header
  • ] - Move to the previous header

Saved Chats

Chat buffers are not saved to disk by default, but can be by pressing gs in the buffer. Saved chats can then be restored via the Action Palette and the Load saved chats action.

Settings

If display.chat.show_settings is set to true, at the very top of the chat buffer will be the adapter's model parameters which can be changed to tweak the response from the LLM. You can find more detail by moving the cursor over them.

Open Chats

From the Action Palette, the Open Chats action enables users to easily navigate between their open chat buffers. A chat buffer can be deleted (and removed from memory) by pressing <C-c>.

Inline Prompting

[!NOTE] If send_code = false then this will take precedent and no code will be sent to the LLM

Inline prompts can be triggered via the CodeCompanion <your prompt> command. As mentioned in the Getting Started section, you can also leverage visual selections and slash commands like '<,'>CodeCompanion /buffer what does this code do?, where the slash command points to a default prompt and any words after that act as a custom prompt 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 after 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 overwrite a visual selection. The plugin will use the inline LLM you've specified in your config to determine if the response should follow any of the placements below:

  • after - after the visual selection/cursor
  • before - before the visual selection/cursor
  • new - in a new buffer
  • replace - replacing the visual selection
  • chat - in a chat buffer

Default Prompts

[!NOTE] Please see the RECIPES guide in order to add your own prompts to the action palette and as a slash command.

The plugin comes with a number of default prompts (as per the config) which you can call via keymaps and/or slash commands:

  • Custom Prompt - For custom, inline prompting of an LLM (<LocalLeader>cc)
  • Senior Developer - Chat with a senior developer for the current buffer's filetype (<LocalLeader>ce)
  • Code Advisor - Get advice on code you've selected (<LocalLeader>ca / /advice)
  • Buffer selection - Send the current buffer to the LLM alongside a prompt (<LocalLeader>cb / /buffer)
  • Explain LSP Diagnostics - Use an LLM to explain LSP diagnostics for code you've selected (<LocalLeader>cl / /lsp)
  • Generate a Commit Message - Use an LLM to write a commit message for you (<LocalLeader>cm / /commit)

Slash commands can be accessed via the command line, for example :CodeCompanion /commit.

Agents

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 in a chat buffer by using the @ key.

More information on how agents work and how you can create your own can be found in the AGENTS 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.

:lollipop: Extras

Hooks / User events

The plugin fires the following events during its lifecycle:

  • CodeCompanionRequest - Fired during the API request. Outputs data.status with a value of started or finished
  • CodeCompanionChatSaved - Fired after a chat has been saved to disk
  • CodeCompanionChat - Fired at various points during the chat buffer. Comes with the following attributes:
    • data.action = hide_buffer - For when a chat buffer is hidden
  • CodeCompanionInline - Fired during the inline API request alongside CodeCompanionRequest. Outputs data.status with a value of started or finished and data.placement with the placement of the text from the LLM
  • CodeCompanionAgent - Fired when an agent is running. Outputs data.status with a value of started or success/failure

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(args)
    if args.data.status == "finished" then
      -- Format the buffer after the inline request has completed
      require("conform").format({ bufnr = args.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)
      self.processing = (request.data.status == "started")
    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)
      self.processing = (args.data.status == "started")
      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,
  },
})

:gift: 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 big PR and please make sure you've read the CONTRIBUTING.md guide.

:clap: Acknowledgements