codecompanion.txt

*codecompanion.txt*         For NVIM v0.11        Last change: 2026 January 21

==============================================================================
Table of Contents                            *codecompanion-table-of-contents*

1. Welcome                                             |codecompanion-welcome|
  - Features                                  |codecompanion-welcome-features|
  - Overview                                  |codecompanion-welcome-overview|
  - Supported LLMs and Agents|codecompanion-welcome-supported-llms-and-agents|
2. Installation                                   |codecompanion-installation|
  - Requirements                     |codecompanion-installation-requirements|
  - Installation                     |codecompanion-installation-installation|
  - Extensions                         |codecompanion-installation-extensions|
  - Other s                               |codecompanion-installation-other-s|
  - Completion                         |codecompanion-installation-completion|
  - Help                                     |codecompanion-installation-help|
3. Getting Started                             |codecompanion-getting-started|
  - Documentation                |codecompanion-getting-started-documentation|
  - Interactions                  |codecompanion-getting-started-interactions|
  - With an Adapter            |codecompanion-getting-started-with-an-adapter|
  - Chat Buffer                    |codecompanion-getting-started-chat-buffer|
  - Inline Assistant          |codecompanion-getting-started-inline-assistant|
  - Commands                          |codecompanion-getting-started-commands|
  - Action Palette              |codecompanion-getting-started-action-palette|
  - List of Commands          |codecompanion-getting-started-list-of-commands|
  - Suggested Workflow      |codecompanion-getting-started-suggested-workflow|
4. Upgrading General                         |codecompanion-upgrading-general|
  - v17.33.0 to v18.0.0  |codecompanion-upgrading-general-v17.33.0-to-v18.0.0|
  - default_memory has been renamed to autoload (#2509)|codecompanion-upgrading-general-default_memory-has-been-renamed-to-autoload-(#2509)|
5. Configuration                                 |codecompanion-configuration|
  - Action Palette                |codecompanion-configuration-action-palette|
  - ACP Adapters                    |codecompanion-configuration-acp-adapters|
  - HTTP Adapters                  |codecompanion-configuration-http-adapters|
  - Chat Buffer                      |codecompanion-configuration-chat-buffer|
  - Inline Assistant            |codecompanion-configuration-inline-assistant|
  - Rules                                  |codecompanion-configuration-rules|
  - Prompt Library                |codecompanion-configuration-prompt-library|
  - System Prompts                |codecompanion-configuration-system-prompts|
  - Extensions                        |codecompanion-configuration-extensions|
  - Other Options                  |codecompanion-configuration-other-options|
6. Usage                                                 |codecompanion-usage|
  - General                                      |codecompanion-usage-general|
  - ACP Protocol Reference        |codecompanion-usage-acp-protocol-reference|
  - Action Palette                        |codecompanion-usage-action-palette|
  - Chat Buffer                              |codecompanion-usage-chat-buffer|
  - Agents                                        |codecompanion-usage-agents|
  - Rules                                          |codecompanion-usage-rules|
  - Tools                                          |codecompanion-usage-tools|
  - Slash Commands                        |codecompanion-usage-slash-commands|
  - Variables                                  |codecompanion-usage-variables|
  - Events / Hooks                        |codecompanion-usage-events-/-hooks|
  - Inline Assistant                    |codecompanion-usage-inline-assistant|
  - Prompt Library                        |codecompanion-usage-prompt-library|
  - User Interface                        |codecompanion-usage-user-interface|
  - Workflows                                  |codecompanion-usage-workflows|
7. Extending                                         |codecompanion-extending|
  - Extending with Adapters  |codecompanion-extending-extending-with-adapters|
  - Extending with Agentic Workflows|codecompanion-extending-extending-with-agentic-workflows|
  - Extending with Extensions|codecompanion-extending-extending-with-extensions|
  - Extending with Rules Parsers|codecompanion-extending-extending-with-rules-parsers|
  - Extending with Tools        |codecompanion-extending-extending-with-tools|
  - Extending the UI                |codecompanion-extending-extending-the-ui|

==============================================================================
1. Welcome                                             *codecompanion-welcome*


  AI Coding, Vim Style
CodeCompanion is a Neovim plugin which enables you to code with AI, using LLMs
and agents, in Neovim.


FEATURES                                      *codecompanion-welcome-features*

-  Copilot Chat <https://github.com/features/copilot> meets Zed AI <https://zed.dev/blog/zed-ai>, in Neovim
-  Support for LLMs from Anthropic, Copilot, GitHub Models, DeepSeek, Gemini, Mistral AI, Novita, Ollama, OpenAI, Azure OpenAI, HuggingFace and xAI out of the box (or bring your own!)
-  Support for Agent Client Protocol <https://agentclientprotocol.com/overview/introduction>, enabling coding with agents like Augment Code <https://docs.augmentcode.com/cli/overview>, Cagent <https://github.com/docker/cagent> from Docker, Claude Code <https://docs.anthropic.com/en/docs/claude-code/overview>, Codex <https://openai.com/codex>, Gemini CLI <https://github.com/google-gemini/gemini-cli>, Goose <https://block.github.io/goose/>, Kimi CLI <https://github.com/MoonshotAI/kimi-cli> and OpenCode <https://opencode.ai>
-  User contributed and supported |codecompanion-configuration-adapters-http-community-adapters|
-  |codecompanion-usage-inline-assistant.html|, code creation and refactoring
-  |codecompanion-usage-chat-buffer-variables|, |codecompanion-usage-chat-buffer-slash-commands|, |codecompanion-usage-chat-buffer-tools| and |codecompanion-usage-workflows| to improve LLM output
-  Support for |codecompanion-usage-chat-buffer-rules| files like `CLAUDE.md`, `.cursor/rules` and your own custom ones
-  Native |codecompanion-usage-chat-buffer-index-super-diff| for tracking agent edits
-  Built-in |codecompanion-usage-action-palette.html| for common tasks like advice on LSP errors and code explanations
-  Create your own |codecompanion-configuration-prompt-library-creating-prompts|, Variables and Slash Commands
-  Have |codecompanion-usage-introduction-quickly-accessing-a-chat-buffer| open at the same time
-  Support for |codecompanion-usage-chat-buffer--images-vision| as input
-  Async execution for fast performance


OVERVIEW                                      *codecompanion-welcome-overview*

The plugin utilises objects called `interactions`. These are the different ways
that a user can interact with the plugin. The `chat` interaction harnesses a
buffer to allow direct conversation with the LLM. The `inline` interaction
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 interaction and also for
each |codecompanion-configuration-prompt-library| entry.


SUPPORTED LLMS AND AGENTS    *codecompanion-welcome-supported-llms-and-agents*

CodeCompanion uses |codecompanion-configuration-adapters-http| and
|codecompanion-configuration-adapters-acp| adapters to connect to LLMs and
agents. Out of the box, the plugin supports:

- Anthropic (`anthropic`) - Requires an API key and supports prompt caching <https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching>
- Augment Code (`auggie_cli`) - Requires an API key
- Cagent (`cagent`)
- Claude Code (`claude_code`) - Requires an API key or a Claude Pro subscription
- Codex (`codex`) - Requires an API key
- Copilot (`copilot`) - Requires a token which is created via `:Copilot setup` in Copilot.vim <https://github.com/github/copilot.vim>
- Gemini CLI (`gemini_cli`) - Requires an API key or a Gemini Pro subscription
- GitHub Models (`githubmodels`) - Requires `gh` <https://github.com/cli/cli> to be installed and logged in
- Goose (`goose`) - Requires an API key
- DeepSeek (`deepseek`) - Requires an API key
- Gemini (`gemini`) - Requires an API key
- HuggingFace (`huggingface`) - Requires an API key
- Kimi CLI (`kimi_cli`) - Requires an API key
- Mistral AI (`mistral`) - Requires an API key
- Novita (`novita`) - Requires an API key
- Ollama (`ollama`) - Both local and remotely hosted
- OpenAI (`openai`) - Requires an API key
- opencode (`opencode`) - Requires an API key
- xAI (`xai`) - Requires an API key

In order to add a custom adapter, please refer to the
|codecompanion-extending-adapters| documentation. Also, be sure to check out
the |codecompanion-configuration-adapters-http-community-adapters| section for
user contributed adapters.


==============================================================================
2. Installation                                   *codecompanion-installation*


  [!IMPORTANT] To avoid breaking changes, it is recommended to pin the plugin to
  a specific release when installing.

REQUIREMENTS                         *codecompanion-installation-requirements*

- The `curl` library
- Neovim 0.11.0 or greater
- `(Optional)` An API key for your chosen LLM
- `(Optional)` nvim-treesitter <https://github.com/nvim-treesitter/nvim-treesitter> and a `yaml` parser for markdown prompt library items
- `(Optional)` The file <https://man7.org/linux/man-pages/man1/file.1.html> command for detecting image mimetype
- `(Optional)` The ripgrep <https://github.com/BurntSushi/ripgrep> library for the `grep_search` tool

You can run `:checkhealth codecompanion` to verify that all requirements are
met.


INSTALLATION                         *codecompanion-installation-installation*

The plugin can be installed with the plugin manager of your choice. It is
recommended to pin the plugin to a specific release to avoid breaking changes.

nvim-treesitter <https://github.com/nvim-treesitter/nvim-treesitter> is
required if you plan to use markdown prompts in the
|codecompanion-configuration-prompt-library|, ensuring you have the `yaml`
parser installed.


**Plenary.nvim note:**

As per #377 <https://github.com/olimorris/codecompanion.nvim/issues/377>, if
you pin your plugins to the latest releases, ensure you set plenary.nvim to
follow the master branch


EXTENSIONS                             *codecompanion-installation-extensions*

CodeCompanion supports extensions that add additional functionality to the
plugin. Below is an example which installs and configures mcphub.nvim
<https://github.com/ravitemer/mcphub.nvim>:


Visit the |codecompanion-extending-extensions| to learn more about available
extensions and how to create your own.


OTHER S                                   *codecompanion-installation-other-s*

CodeCompanion integrates with a number of other plugins to make your AI coding
experience more enjoyable. Below are some common lazy.nvim configurations for
popular plugins:


Use render-markdown.nvim
<https://github.com/MeanderingProgrammer/render-markdown.nvim> or markview.nvim
<https://github.com/OXY2DEV/markview.nvim> to render the markdown in the chat
buffer. Use img-clip.nvim <https://github.com/hakonharnes/img-clip.nvim> to
copy images from your system clipboard into a chat buffer via `:PasteImage`:


COMPLETION                             *codecompanion-installation-completion*

When in the |codecompanion-usage-chat-buffer-index|, completion can be used to
more easily add |codecompanion-usage-chat-buffer-variables|,
|codecompanion-usage-chat-buffer-slash-commands| and
|codecompanion-usage-chat-buffer-tools|. Out of the box, the plugin supports
completion with both nvim-cmp <https://github.com/hrsh7th/nvim-cmp> and
blink.cmp <https://github.com/Saghen/blink.cmp>. For the latter, on version <=
0.10.0, ensure that you’ve added `codecompanion` as a source:

>lua
    sources = {
      per_filetype = {
        codecompanion = { "codecompanion" },
      }
    },
<

The plugin also supports |codecompanion-usage-chat-buffer-index-completion| and
coc.nvim <https://github.com/neoclide/coc.nvim>.


HELP                                         *codecompanion-installation-help*

If you’re having trouble installing the plugin, as a first step, run
`:checkhealth codecompanion` to check that plugin is installed correctly. After
that, consider using the minimal.lua
<https://github.com/olimorris/codecompanion.nvim/blob/main/minimal.lua> file to
troubleshoot, running it with `nvim --clean -u minimal.lua`.


==============================================================================
3. Getting Started                             *codecompanion-getting-started*


  [!IMPORTANT] The default adapter in CodeCompanion is GitHub Copilot
  <https://docs.github.com/en/copilot/using-github-copilot/copilot-chat/asking-github-copilot-questions-in-your-ide>.
  If you have copilot.vim <https://github.com/github/copilot.vim> or copilot.lua
  <https://github.com/zbirenbaum/copilot.lua> installed then expect CodeCompanion
  to work out of the box.
This guide is intended to help you get up and running with CodeCompanion and
begin your journey of coding with AI in Neovim. It assumes that you have
already installed the plugin. If you haven’t done so, please refer to the
|codecompanion-installation| first.


DOCUMENTATION                    *codecompanion-getting-started-documentation*

Throughout the documentation you will see examples that are wrapped in a
`require("codecompanion").setup({ })` block. This is purposefully done so that
users can apply them to their own Neovim configuration.

If you’re using lazy.nvim <https://github.com/folke/lazy.nvim>, you can
simply apply the examples that you see in this documentation in the `opts`
table. For example, the following code snippet from these docs:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          adapter = "anthropic",
          model = "claude-sonnet-4-20250514"
        },
      },
      opts = {
        log_level = "DEBUG",
      },
    })
<

can be used in a `lazy.nvim` configuration like so:

>lua
    {
      "olimorris/codecompanion.nvim",
      dependencies = {
        "nvim-lua/plenary.nvim"
      },
      opts = {
        interactions = {
          chat = {
            adapter = "anthropic",
            model = "claude-sonnet-4-20250514"
          },
        },
        -- NOTE: The log_level is in `opts.opts`
        opts = {
          log_level = "DEBUG",
        },
      },
    },
<


INTERACTIONS                      *codecompanion-getting-started-interactions*

The plugin uses the notion of `interactions` to describe the many different
ways that you can interact with an LLM from within CodeCompanion. There are
four main types of interactions:

- **Chat** - A chat buffer where you can converse with an LLM (`:CodeCompanionChat`)
- **Inline** - An inline assistant that can write code directly into a buffer (`:CodeCompanion`)
- **Cmd** - Create Neovim commands in the command-line (`:CodeCompanionCmd`)
- **Background** - Runs tasks in the background such as compacting chat messages or generating titles for chats


WITH AN ADAPTER                *codecompanion-getting-started-with-an-adapter*


  [!NOTE] The adapters that the plugin supports out of the box can be found here
  <https://github.com/olimorris/codecompanion.nvim/tree/main/lua/codecompanion/adapters>.
  Or, see the user contributed adapters
  |codecompanion-configuration-adapters-http-community-adapters|
An adapter is what connects Neovim to an LLM (via `HTTP`) or an agent (via ACP
<https://agentclientprotocol.com/overview/introduction>). It’s the interface
that allows data to be sent, received and processed. In order to use the
plugin, you need to make sure you’ve configured an adapter first:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          -- You can specify an adapter by name and model (both ACP and HTTP)
          adapter = {
            name = "copilot",
            model = "gpt-4.1",
          },
        },
        -- Or, just specify the adapter by name
        inline = {
          adapter = "anthropic",
        },
        cmd = {
          adapter = "openai",
        },
        background = {
          adapter = {
            name = "ollama",
            model = "qwen-7b-instruct",
          },
        },
      },
    })
<

In the example above, we’re using the Copilot adapter for the chat
interaction and the Anthropic one for the inline. We’re also using something
cheap for the background adapter (although these interactions are opt-in). You
can mix and match adapters as you see fit for your workflow.


  [!IMPORTANT] |codecompanion-configuration-adapters-acp| are only supported for
  the chat interaction.
There are two "types" of adapter in CodeCompanion;
|codecompanion-configuration-adapters-http| adapters which connect you to an
LLM and |codecompanion-configuration-adapters-acp| adapters which leverage the
Agent Client Protocol <https://agentclientprotocol.com> to connect you to an
agent.

Refer to the respective sections to understand more about working with adapters
that enable agents like
|codecompanion-configuration-adapters-acp-setup-claude-code|.


SETTING AN API KEY ~

Because most LLMs require an API key, you’ll need to share that with the
adapter. By default, adapters will look in your environment for a `*_API_KEY`
where `*` is the name of the adapter such as `ANTHROPIC` or `OPENAI`. Refer to
the documentation of the LLM or agent you’re using to find out what the
environment variable is called.

You can extend an adapter and change the API key like so:

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

There are numerous ways that environment variables can be set for adapters.
Refer to the |codecompanion-configuration-adapters-http-environment-variables|
section for more information.


CHAT BUFFER                        *codecompanion-getting-started-chat-buffer*

The Chat Buffer is where you can converse with an LLM from within Neovim. It
operates on a single response per turn, basis. Once your adapter has been
configured, you can start using the chat buffer and begin interacting with an
LLM.

Run `:CodeCompanionChat` to open a chat buffer. Type your prompt and send it by
pressing `<C-s>` while in insert mode or `<CR>` in normal mode. Alternatively,
run `:CodeCompanionChat why are Lua and Neovim so perfect together?` to open
the chat buffer and send a prompt at the same time. Toggle the chat buffer with
`:CodeCompanionChat Toggle`.

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


VARIABLES ~

`Variables`, accessed via `#`, contain data about the present state of Neovim.
You can find a list of available variables,
|codecompanion-usage-chat-buffer-variables.html|. The buffer variable will
automatically link a buffer to the chat buffer, by default, updating the LLM
when the buffer changes.


  [!TIP] Use them in your prompt like: `What does the code in #{buffer} do?`

SLASH COMMANDS ~


  [!IMPORTANT] These have been designed to work with native Neovim completions
  alongside nvim-cmp and blink.cmp. To open the native completion menu use
  `<C-_>` in insert mode when in the chat buffer. Note: Slash commands should
  also work with coc.nvim.
`Slash commands`, accessed via `/`, run commands to insert additional context
into the chat buffer. You can find a list of available commands as well as how
to use them, |codecompanion-usage-chat-buffer-slash-commands.html|.


TOOLS ~

`Tools`, accessed via `@`, allow the LLM to function as an agent and leverage
external tools. You can find a list of available tools as well as how to use
them, |codecompanion-usage-chat-buffer-tools.html-available-tools|.


  [!TIP] Use them in your prompt like:
  `Can you use @{grep_search} to find occurrences of "hello world"`

INLINE ASSISTANT              *codecompanion-getting-started-inline-assistant*


  [!NOTE] The diff provider in the video is mini.diff
  <https://github.com/echasnovski/mini.diff>
The inline assistant enables an LLM to write code directly into a Neovim
buffer.

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. To send additional context
alongside your prompt, you can leverage
|codecompanion-usage-inline-assistant-variables| such as `:CodeCompanion
#{buffer} <your prompt>`.

For convenience, you can call prompts with their `alias` from the prompt
library
<https://github.com/olimorris/codecompanion.nvim/blob/6a4341a4cfe8988a57ad9e8b7dc01ccd6f3e1628/lua/codecompanion/config.lua#L565>
such as `:'<,'>CodeCompanion /explain`. The prompt library comes with the
following presets:

- `/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


COMMANDS                              *codecompanion-getting-started-commands*

Use CodeCompanion to create Neovim commands in command-line mode
(|Command-line|) via `:CodeCompanionCmd <your prompt>`.


ACTION PALETTE                  *codecompanion-getting-started-action-palette*

Run `:CodeCompanionActions` to open the action palette, which gives you access
to the plugin’s features, including your prompts from the
|codecompanion-configuration-prompt-library|.

By default the plugin uses `vim.ui.select`, however, you can change the
provider by altering the `display.action_palette.provider` config value to be
`telescope`, `mini_pick` or `snacks`. You can also call the Telescope extension
with `:Telescope codecompanion`.


  [!NOTE] Some actions and prompts will only be visible if you’re in `Visual
  mode`.

LIST OF COMMANDS              *codecompanion-getting-started-list-of-commands*

The plugin has four core commands:

- `CodeCompanion` - Open the inline assistant
- `CodeCompanionChat` - Open a chat buffer
- `CodeCompanionCmd` - Generate a command in the command-line
- `CodeCompanionActions` - Open the `Action Palette`

However, there are multiple options available:

- `CodeCompanion <prompt>` - Prompt the inline assistant
- `CodeCompanion adapter=<adapter> <prompt>` - Prompt the inline assistant with a specific adapter
- `CodeCompanion /<prompt library>` - Call an item via its alias from the |codecompanion-configuration-prompt-library|
- `CodeCompanionChat <prompt>` - Send a prompt to the LLM via a chat buffer
- `CodeCompanionChat adapter=<adapter> model=<model>` - Open a chat buffer with a specific http adapter and model
- `CodeCompanionChat adapter=<adapter> command=<command>` - Open a chat buffer with a specific ACP adapter and command
- `CodeCompanionChat Add` - Add visually selected chat to the current chat buffer
- `CodeCompanionChat RefreshCache` - Used to refresh conditional elements in the chat buffer
- `CodeCompanionChat Toggle` - Toggle a chat buffer


SUGGESTED WORKFLOW          *codecompanion-getting-started-suggested-workflow*

For an optimum plugin workflow, I recommend the following:

>lua
    vim.keymap.set({ "n", "v" }, "<C-a>", "<cmd>CodeCompanionActions<cr>", { noremap = true, silent = true })
    vim.keymap.set({ "n", "v" }, "<LocalLeader>a", "<cmd>CodeCompanionChat Toggle<cr>", { noremap = true, silent = true })
    vim.keymap.set("v", "ga", "<cmd>CodeCompanionChat Add<cr>", { noremap = true, silent = true })
    
    -- Expand 'cc' into 'CodeCompanion' in the command line
    vim.cmd([[cab cc CodeCompanion]])
<


  [!NOTE] You can also assign prompts from the library to specific mappings. See
  the |codecompanion-configuration-prompt-library-assigning-prompts-to-a-keymap|
  section for more information.

==============================================================================
4. Upgrading General                         *codecompanion-upgrading-general*

This document provides a guide for upgrading from one version of CodeCompanion
to another.

CodeCompanion follows semantic versioning <https://semver.org/> and to avoid
breaking changes, it is recommended to pin the plugin to a specific version in
your Neovim configuration. The |codecompanion-installation| provides more
information on how to do this.


V17.33.0 TO V18.0.0      *codecompanion-upgrading-general-v17.33.0-to-v18.0.0*


CONFIG ~

- The biggest change in this release is the renaming of `strategies` to `interactions`. This will only be a breaking change if you specifically reference `codecompanion.strategies` in your configuration. If you do, you’ll need to change it to `codecompanion.interactions` (#2485 <https://github.com/olimorris/codecompanion.nvim/pull/2485>)
- Previously, built-in slash commands and tools were stored in `/catalog` folders which have now been renamed to `/builtin`. If you reference these in your configuration you’ll need to update the paths accordingly (#2482 <https://github.com/olimorris/codecompanion.nvim/pull/2482>)
- Workspaces have now been removed from the plugin. Please use |codecompanion-configuration-rules| instead.


ADAPTERS ~

- If you have a custom adapter, you’ll need to rename `condition` to be `enabled` on any schema items (#2439 <https://github.com/olimorris/codecompanion.nvim/pull/2439/commits/cb14c7bac869346e2d12b775c4bf258606add569>):

>lua
    return {
      schema = {
        ["reasoning.effort"] = {
          ---@type fun(self: CodeCompanion.HTTPAdapter): boolean
          condition = function(self) -- [!code --]
          enabled = function(self) -- [!code ++]
            --
          end,
        },
      }
    }
<

- The default adapters on the **Anthropic** and **Gemini** adapters have changed to `claude-sonnet-4-5-20250929` and `gemini-3-pro-preview`, respectively (#2494 <https://github.com/olimorris/codecompanion.nvim/pull/2494>)
- If you wish to hide the adapters that come with CodeCompanion, `adapter.[acp|http].opts.show_defaults` has been renamed to `adapter.[acp|http].opts.show_presets` for both HTTP and ACP adapters (#2497 <https://github.com/olimorris/codecompanion.nvim/pull/2497>)


CHAT ~

- Memory has been renamed to rules. Please rename any references to `memory` in your configuration to `rules`. Please refer to the |codecompanion-configuration-rules| documentation for more information (#2440 <https://github.com/olimorris/codecompanion.nvim/pull/2440>)
- DEFAULT_MEMORY HAS BEEN RENAMED TO AUTOLOAD (#2509)*codecompanion-upgrading-general-default_memory-has-been-renamed-to-autoload-(#2509)*
- The variable and parameter `#{buffer}{watch}` has been renamed to `#{buffer}{diff}`. This better reflects that an LLM receives a diff of buffer changes with each request (#2444 <https://github.com/olimorris/codecompanion.nvim/pull/2444>)
- The variable and parameter `#{buffer}{pin}` has now been renamed to `#{buffer}{all}`. This better reflects that the
    entire buffer is sent to the LLM with each request (#2444 <https://github.com/olimorris/codecompanion.nvim/pull/2444>)
    —
- Passing an adapter as an argument to `:CodeCompanionChat` is now done with `:CodeCompanionChat adapter=<adapter_name>` (#2437 <https://github.com/olimorris/codecompanion.nvim/pull/2437>)
- If your chat buffer system prompt is still stored at `opts.system_prompt` you’ll need to change it to `interactions.chat.opts.system_prompt` (#2484 <https://github.com/olimorris/codecompanion.nvim/pull/2484>)


PROMPT LIBRARY ~

If you have any prompts defined in your config, you’ll need to:

- Rename `opts.short_name` to `opts.alias` for each item in order to allow you to call them with `require("codecompanion").prompt("my_prompt")` or as slash commands in the chat buffer (#2471 <https://github.com/olimorris/codecompanion.nvim/pull/2471>).

>lua
    ["my custom prompt"] = {
      strategy = "chat",
      description = "My custom prompt",
      opts = {
        short_name = "my_prompt", -- [!code --]
        alias = "my_prompt", -- [!code ++]
      },
      prompts = {
        -- ...
      },
    },
<

- Change all workflow prompts, replacing `strategy = "workflow"` with `interaction = "chat"` and specifying `opts.is_workflow = true` (#2487 <https://github.com/olimorris/codecompanion.nvim/pull/2487>).

>lua
    ["my_workflow"] = {
      strategy = "workflow", -- [!code --]
      interaction = "chat", -- [!code ++]
      description = "My custom workflow",
      opts = {
        is_workflow = true, -- [!code ++]
      },
      prompts = {
        -- ...
      },
    },
<

- If you don’t wish to display any of the built-in prompt library items, you’ll need to change `display.action_palette.show_default_prompt_library` to `display.action_palette.show_preset_prompts` (#2499 <https://github.com/olimorris/codecompanion.nvim/pull/2499>)


TOOLS ~

If you have any tools in your config, you’ll need to rename:

- `requires_approval` to `require_approval_before` (#2439 <https://github.com/olimorris/codecompanion.nvim/pull/2439/commits/cb14c7bac869346e2d12b775c4bf258606add569>)
- `user_confirmation` to `require_confirmation_after` (#2450 <https://github.com/olimorris/codecompanion.nvim/pull/2450>)

These now better reflect the timing of each action.


UI ~

- The `display.chat.child_window` has been renamed `display.chat.floating_window` to better describe what it is (#2452 <https://github.com/olimorris/codecompanion.nvim/pull/2452>)
- The `display.action_palette.opts.show_default_actions` has been renamed to be `display.action_palette.opts.show_preset_actions` (#2499 <https://github.com/olimorris/codecompanion.nvim/pull/2499>)


==============================================================================
5. Configuration                                 *codecompanion-configuration*


ACTION PALETTE                    *codecompanion-configuration-action-palette*

The Action Palette holds plugin specific items like the ability to launch a
chat buffer and the currently open chat buffers alongside displaying the
prompts from the |codecompanion-prompt-library|.


LAYOUT ~


  [!NOTE] The Action Palette also supports Telescope.nvim
  <https://github.com/nvim-telescope/telescope.nvim>, fzf_lua
  <https://github.com/ibhagwan/fzf-lua>, mini.pick
  <https://github.com/echasnovski/mini.pick> and snacks.nvim
  <https://github.com/folke/snacks.nvim>
You can change the appearance of the chat buffer by changing the
`display.action_palette` table in your configuration:

>lua
    require("codecompanion").setup({
      display = {
        action_palette = {
          width = 95,
          height = 10,
          prompt = "Prompt ", -- Prompt used for interactive LLM calls
          provider = "default", -- Can be "default", "telescope", "fzf_lua", "mini_pick" or "snacks". If not specified, the plugin will autodetect installed providers.
          opts = {
            show_preset_actions = true, -- Show the preset actions in the action palette?
            show_preset_prompts = true, -- Show the preset prompts in the action palette?
            title = "CodeCompanion actions", -- The title of the action palette
          },
        },
      },
    }),
<


ACP ADAPTERS                        *codecompanion-configuration-acp-adapters*

This section contains configuration which is specific to Agent Client Protocol
(ACP) adapters only. There is a lot of shared functionality between ACP and
|codecompanion-configuration-adapters-http| adapters. Therefore it’s
recommended you read the two pages together.


CHANGING THE DEFAULT ADAPTER ~

You can select an ACP adapter to be the default for all chat interactions:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          adapter = "gemini_cli",
        },
      },
    }),
<


CHANGING THE DEFAULT MODEL ~

You can change the default model used by an ACP adapter. For example, to change
the default model for the Claude Code adapter:


Using a `function` is useful for working around the limitations
<https://github.com/zed-industries/claude-code-acp/issues/225> in the Claude
Code SDK (which enables ACP support).


CHANGING ADAPTER SETTINGS ~

To change any of the default settings for an ACP adapter, you can extend it in
your CodeCompanion setup. For example, to change the timeout and authentication
method for the Gemini CLI adapter, you can do the following:

>lua
    require("codecompanion").setup({
      adapters = {
        acp = {
          gemini_cli = function()
            return require("codecompanion.adapters").extend("gemini_cli", {
              commands = {
                default = {
                  "some-other-gemini"
                  "--experimental-acp",
                },
              },
              defaults = {
                auth_method = "gemini-api-key",
                timeout = 20000, -- 20 seconds
              },
              env = {
                GEMINI_API_KEY = "GEMINI_API_KEY",
              },
            })
          end,
        },
      },
    })
<


HIDING PRESET ADAPTERS ~

By default, the plugin shows all available adapters, including the presets. If
you prefer to only display the adapters defined in your user configuration, you
can set the `show_presets` option to `false`:

>lua
    require("codecompanion").setup({
      adapters = {
        acp = {
          opts = {
            show_presets = false,
          },
        },
      },
    })
<


SETUP: AUGGIE CLI FROM AUGMENT CODE ~

To use Auggie CLI <https://docs.augmentcode.com/cli/overview> within
CodeCompanion, you simply need to follow their Getting Started
<https://docs.augmentcode.com/cli/overview#getting-started> guide.


SETUP: CAGENT ~

To use Docker’s Cagent <https://github.com/docker/cagent> within
CodeCompanion, you need to follow these steps:

1. Install <https://github.com/docker/cagent?tab=readme-ov-file#installation> Cagent as per their instructions
2. Create an agent <https://github.com/docker/cagent?tab=readme-ov-file#run-agents> in the repository you’re working from
3. Test the agent by running `cagent run your_agent.yaml` in the CLI
4. In your CodeCompanion config, extend the `cagent` adapter to include the agent:

>lua
    require("codecompanion").setup({
      adapters = {
        acp = {
          cagent = function()
            return require("codecompanion.adapters").extend("cagent", {
              commands = {
                default = {
                  "cagent",
                  "acp",
                  "your_agent.yaml",
                },
              },
            })
          end,
        },
      },
    })
<

If you have multiple agent files that you like to run separately, you can
create multiple commands for each agent.


SETUP: CLAUDE CODE ~

To use Claude Code <https://www.anthropic.com/claude-code> within
CodeCompanion, you’ll need to take the following steps:

1. Install <https://docs.anthropic.com/en/docs/claude-code/quickstart#step-1%3A-install-claude-code> Claude Code
2. Install <https://github.com/zed-industries/claude-code-acp> the Zed ACP adapter for Claude Code


CLAUDE PRO SUBSCRIPTION

1. In your CLI, run `claude setup-token`. You’ll be redirected to the Claude.ai website for authorization:

2. Back in your CLI, copy the OAuth token (in yellow):

3. In your CodeCompanion config, extend the `claude_code` adapter and include the OAuth token (see the section on |codecompanion-configuration-adapters-http-environment-variables-setting-an-api-key| for other ways to do this):

>lua
    require("codecompanion").setup({
      adapters = {
        acp = {
          claude_code = function()
            return require("codecompanion.adapters").extend("claude_code", {
              env = {
                CLAUDE_CODE_OAUTH_TOKEN = "my-oauth-token",
              },
            })
          end,
        },
      },
    })
<


AN API KEY

1. Create <https://console.anthropic.com/settings/keys> an API key in your Anthropic console.
2. In your CodeCompanion config, extend the `claude_code` adapter and set the `ANTHROPIC_API_KEY`:

>lua
    require("codecompanion").setup({
      adapters = {
        acp = {
          claude_code = function()
            return require("codecompanion.adapters").extend("claude_code", {
              env = {
                ANTHROPIC_API_KEY = "my-api-key",
              },
            })
          end,
        },
      },
    })
<


SETUP: CODEX ~

To use OpenAI’s Codex <https://openai.com/codex/>, install an ACP-compatible
adapter like this <https://github.com/zed-industries/codex-acp> one from Zed
<https://zed.dev>.

By default, the adapter will look for an `OPENAI_API_KEY` in your shell,
however you can also authenticate via ChatGPT. This can be customized in the
plugin configuration:

>lua
    require("codecompanion").setup({
      adapters = {
        acp = {
          codex = function()
            return require("codecompanion.adapters").extend("codex", {
              defaults = {
                auth_method = "openai-api-key", -- "openai-api-key"|"codex-api-key"|"chatgpt"
              },
              env = {
                OPENAI_API_KEY = "my-api-key",
              },
            })
          end,
        },
      },
    })
<


SETUP: GEMINI CLI ~

1. Install Gemini CLI <https://github.com/google-gemini/gemini-cli>
2. Update your CodeCompanion config and select which authentication methods you’d like to use. Currently there are:- `oauth-personal` which uses your Google login
- `gemini-api-key`
- `vertex-ai`)



The example below uses the `gemini-api-key` method, pulling the API key from
1Password CLI <https://developer.1password.com/docs/cli/get-started/>:

>lua
    require("codecompanion").setup({
      adapters = {
        acp = {
          gemini_cli = function()
            return require("codecompanion.adapters").extend("gemini_cli", {
              defaults = {
                auth_method = "gemini-api-key", -- "oauth-personal"|"gemini-api-key"|"vertex-ai"
              },
              env = {
                GEMINI_API_KEY = "cmd:op read op://personal/Gemini_API/credential --no-newline",
              },
            })
          end,
        },
      },
    })
<


SETUP: GOOSE CLI ~

To use Goose <https://block.github.io/goose/> in CodeCompanion, ensure you’ve
followed their documentation
<https://block.github.io/goose/docs/getting-started/installation/> to setup and
install Goose CLI. Then ensure that in your chat buffer you select the `goose`
adapter.


SETUP: KIMI CLI ~

Install Kimi CLI
<https://github.com/MoonshotAI/kimi-cli?tab=readme-ov-file#installation> as per
their instructions. Then in the CLI, run `kimi` followed by `/setup` to
configure your API key. Then ensure that in your chat buffer you select the
`kimi_cli` adapter.


SETUP: OPENCODE ~

To use OpenCode <https://opencode.ai> in CodeCompanion, ensure you’ve
followed their documentation to install <https://opencode.ai/docs/#install> and
configure <https://opencode.ai/docs/#configure> it. Then ensure that in your
chat buffer you select the `opencode` adapter.

You can specify a custom model in your `~/.config/opencode/config.json` file:

>json
    {
        "$schema": "https://opencode.ai/config.json",
        "model": "github-copilot/claude-sonnet-4.5",
    }
<


HTTP ADAPTERS                      *codecompanion-configuration-http-adapters*


  [!TIP] Want to connect to an LLM that isn’t supported out of the box? Check
  out |codecompanion--community-adapters| user contributed adapters,
  |codecompanion-extending-adapters.html| your own or post in the discussions
  <https://github.com/olimorris/codecompanion.nvim/discussions>
An adapter is what connects Neovim to an LLM provider and model. It’s the
interface that allows data to be sent, received and processed. There are a
multitude of ways to customize them.

There are two "types" of adapter in CodeCompanion; **http** adapters which
connect you to an LLM and |codecompanion-configuration-adapters-acp| adapters
which leverage the Agent Client Protocol <https://agentclientprotocol.com> to
connect you to an agent.

The configuration for both types of adapters is exactly the same, however they
sit within their own tables (`adapters.http.*` and `adapters.acp.*`) and have
different options available. HTTP adapters use `models` to allow users to
select the specific LLM they’d like to interact with. ACP adapters use
`commands` to allow users to customize their interaction with agents (e.g.�
enabling `yolo` mode). As there is a lot of shared functionality between the
two adapters, it is recommend that you read this page alongside the ACP one.


CHANGING THE DEFAULT ADAPTER ~

You can change the default adapter for each interaction as follows:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          adapter = "anthropic",
        },
        inline = {
          adapter = "copilot",
        },
        cmd = {
          adapter = "deepseek",
        }
      },
    }),
<


CHANGING THE DEFAULT MODEL ~

A core part of working with CodeCompanion is being able to easily switch
between adapters and LLMs. Below are two examples of how this can be achieved.



CHANGING ADAPTER SCHEMA ~


  [!NOTE] When extending an adapter with `extend`, use it’s key from the
  `adapters` dictionary
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:



ENVIRONMENT VARIABLES ~

Setting environment variables within adapters is a key part of configuration.
The adapter `env` table lets you define values that will be interpolated into
the adapter’s URL, headers, parameters and other fields at runtime.



  [!NOTE] In this `command` example, we’re using the 1Password CLI to extract
  the Gemini API Key. You could also use gpg as outlined here
  <https://github.com/olimorris/codecompanion.nvim/discussions/601>
Supported `env` value types: - **Plain environment variable name (string)**: if
the value is the name of an environment variable that has already been set
(e.g.� `"HOME"` or `"GEMINI_API_KEY"`), the plugin will read the value. -
**Command (string prefixed with cmd:)**: any value that starts with `cmd:` will
be executed via the shell. Example: `"cmd:op read
op://personal/Gemini/credential --no-newline"`. - **Function**: you can provide
a Lua function which returns a string and will be called with the adapter as
its sole argument. - **Schema reference (dot notation)**: you can reference
values from the adapter table (for example `"schema.model.default"`).


ADDING A CUSTOM ADAPTER ~


  [!NOTE] See the |codecompanion-extending-adapters| section to learn how to
  create custom adapters
Custom adapters can be added to the plugin as follows:

>lua
    require("codecompanion").setup({
      adapters = {
        http = {
          my_custom_adapter = function()
            return {} -- My adapter logic
          end,
        },
      },
    })
<


SETTING A PROXY ~

A proxy can be configured by utilising the `adapters.opts` table in the config:

>lua
    require("codecompanion").setup({
      adapters = {
        http = {
          opts = {
            allow_insecure = true,
            proxy = "socks5://127.0.0.1:9999",
          },
        },
      },
    }),
<


HIDING PRESET ADAPTERS ~

By default, the plugin shows all available adapters, including the presets. If
you prefer to only display the adapters defined in your user configuration, you
can set the `show_presets` option to `false`:

>lua
    require("codecompanion").setup({
      adapters = {
        http = {
          opts = {
            show_presets = false,
          },
        },
      },
    })
<


CONTROLLING MODEL CHOICES ~

When switching between adapters, the plugin typically displays all available
model choices for the selected adapter. If you want to simplify the interface
and have the default model automatically chosen (without showing any model
selection UI), you can set the `show_model_choices` option to `false`:

>lua
    require("codecompanion").setup({
      adapters = {
        http = {
          -- Define your custom adapters here
          opts = {
            show_model_choices = false,
          },
        },
      },
    })
<

With `show_model_choices = false`, the default model (as defined in the
adapter’s schema) will be automatically selected when changing adapters, and
no model selection will be shown to the user.


SETUP EXAMPLES ~

Below are some examples of how you can configure various adapters within
CodeCompanion. Some merely serve as illustrations and are not actively
supported by the plugin.


AZURE OPENAI

Below is an example of how you can leverage the `azure_openai` adapter within
the plugin:

>lua
    require("codecompanion").setup({
      adapters = {
        http = {
          azure_openai = function()
            return require("codecompanion.adapters").extend("azure_openai", {
              env = {
                api_key = "YOUR_AZURE_OPENAI_API_KEY",
                endpoint = "YOUR_AZURE_OPENAI_ENDPOINT",
              },
              schema = {
                model = {
                  default = "YOUR_DEPLOYMENT_NAME",
                },
              },
            })
          end,
        },
      },
      interactions = {
        chat = {
          adapter = "azure_openai",
        },
        inline = {
          adapter = "azure_openai",
        },
      },
    }),
<


LLAMA.CPP WITH --REASONING-FORMAT DEEPSEEK

>lua
    require("codecompanion").setup({
      adapters = {
        http = {
          ["llama.cpp"] = function()
            return require("codecompanion.adapters").extend("openai_compatible", {
              env = {
                url = "http://127.0.0.1:8080", -- replace with your llama.cpp instance
                api_key = "TERM",
                chat_url = "/v1/chat/completions",
              },
              handlers = {
                parse_message_meta = function(self, data)
                  local extra = data.extra
                  if extra and extra.reasoning_content then
                    data.output.reasoning = { content = extra.reasoning_content }
                    if data.output.content == "" then
                      data.output.content = nil
                    end
                  end
                  return data
                end,
              },
            })
          end,
        },
      },
      interactions = {
        chat = {
          adapter = "llama.cpp",
        },
        inline = {
          adapter = "llama.cpp",
        },
      },
    })
<


OLLAMA (REMOTELY)

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

>lua
    require("codecompanion").setup({
      adapters = {
        http = {
          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,
        },
      },
    })
<


OPENAI RESPONSES API

CodeCompanion supports OpenAI’s Responses API
<https://platform.openai.com/docs/api-reference/responses> out of the box, via
a separate adapter:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          adapter = "openai_responses",
        },
        inline = {
          adapter = "openai_responses",
        },
      },
    }),
<

and it can be configured as with any other adapter:

>lua
    require("codecompanion").setup({
      adapters = {
        http = {
          openai_responses = function()
            return require("codecompanion.adapters").extend("openai_responses", {
              env = {
                api_key = "OPENAI_API_KEY",
              },
            })
          end,
        },
      },
    },
<

By default, CodeCompanion sets `store = false` to ensure that state isn’t
stored
<https://platform.openai.com/docs/api-reference/responses/create#responses-create-store>
via the API. This is standard behaviour across all http adapters within the
plugin.


COMMUNITY ADAPTERS ~

Thanks to the community for building the following adapters:

- Venice.ai <https://github.com/olimorris/codecompanion.nvim/discussions/972>
- Fireworks.ai <https://github.com/olimorris/codecompanion.nvim/discussions/693>
- OpenRouter <https://github.com/olimorris/codecompanion.nvim/discussions/1013>
- DashScope <https://github.com/olimorris/codecompanion.nvim/discussions/2239>

The section of the discussion forums which is dedicated to user created
adapters can be found here
<https://github.com/olimorris/codecompanion.nvim/discussions?discussions_q=is%3Aopen+label%3A%22tip%3A+adapter%22>.
Use these individual threads as a place to raise issues and ask questions about
your specific adapters.


CHAT BUFFER                          *codecompanion-configuration-chat-buffer*

By default, CodeCompanion provides a `chat` interaction that uses a dedicated
Neovim buffer for conversational interaction with your chosen LLM. This buffer
can be customized according to your preferences.

Please refer to the config.lua
<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/config.lua#L42-L392>
file for a full list of all configuration options.


CHANGING ADAPTER ~

By default, CodeCompanion sets the `copilot` adapter for the chat interaction.
You can change this to be a `ACP` or `HTTP` adapter:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          adapter = {
            name = "anthropic",
            model = "claude-haiku-4-5-20251001"
          },
        },
      },
    })
<

See the section on |codecompanion-configuration-adapters-acp| and
|codecompanion-configuration-adapters-http| for more information.


DIFF ~

CodeCompanion has built-in inline and split diffs available to you. If you
utilize the `insert_edit_into_file` tool, then the plugin can update files and
buffers and a diff will be created so you can see the changes made by the LLM.
The `inline` is the default diff.

Depending on which provider you choose, there are different configuration
options available to you:


The keymaps for accepting and rejecting the diff sit within the `inline`
interaction configuration and can be changed via:

>lua
    require("codecompanion").setup({
      interactions = {
        inline = {
          keymaps = {
            accept_change = {
              modes = { n = "gda" }, -- Remember this as DiffAccept
            },
            reject_change = {
              modes = { n = "gdr" }, -- Remember this as DiffReject
            },
            always_accept = {
              modes = { n = "gdy" }, -- Remember this as DiffYolo
            },
          },
        },
      },
    })
<


KEYMAPS ~


  [!NOTE] The plugin scopes CodeCompanion specific keymaps to the `chat buffer`
  only.
You can define or override the default keymaps
<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/config.lua#L178>
to send messages, regenerate responses, close the buffer, etc. Example:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          keymaps = {
            send = {
              modes = { n = "<C-s>", i = "<C-s>" },
              opts = {},
            },
            close = {
              modes = { n = "<C-c>", i = "<C-c>" },
              opts = {},
            },
            -- Add further custom keymaps here
          },
        },
      },
    })
<

The keymaps are mapped to `<C-s>` for sending a message and `<C-c>` for closing
in both normal and insert modes. To set other `:map-arguments`, you can use the
optional `opts` table which will be fed to `vim.keymap.set`.


PROMPT DECORATOR ~

It can be useful to decorate your prompt, prior to sending to an LLM, with
additional information. For example, the GitHub Copilot prompt in VS Code,
wraps a user’s prompt between `<prompt></prompt>` tags, presumably to
differentiate the user’s ask from additional context. This can also be
achieved in CodeCompanion:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          opts = {
            ---Decorate the user message before it's sent to the LLM
            ---@param message string
            ---@param adapter CodeCompanion.Adapter
            ---@param context table
            ---@return string
            prompt_decorator = function(message, adapter, context)
              return string.format([[<prompt>%s</prompt>]], message)
            end,
          }
        }
      }
    })
<

The decorator function also has access to the adapter in the chat buffer
alongside the context
<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/utils/context.lua#L121-L137>
table (which refreshes when a user toggles the chat buffer).


SLASH COMMANDS ~


  [!IMPORTANT] Each slash command may have their own unique configuration so be
  sure to check out the config.lua
  <https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/config.lua>
  file
Slash Commands
<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/config.lua#L114>
(invoked with `/`) let you dynamically insert context into the chat buffer,
such as file contents or date/time.

The plugin supports providers like telescope
<https://github.com/nvim-telescope/telescope.nvim>, mini_pick
<https://github.com/echasnovski/mini.pick>, fzf_lua
<https://github.com/ibhagwan/fzf-lua> and snacks.nvim
<https://github.com/folke/snacks.nvim>. By default, the plugin will
automatically detect if you have any of those plugins installed and duly set
them as the default provider. Failing that, the in-built `default` provider
will be used. Please see the |codecompanion-usage-chat-buffer-index| usage
section for information on how to use Slash Commands.


Credit to @lazymaniac <https://github.com/lazymaniac> for the inspiration
<https://github.com/olimorris/codecompanion.nvim/discussions/958> for the
custom slash command example.


TOOLS ~

Tools
<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/config.lua#L55>
perform specific tasks (e.g., running shell commands, editing buffers, etc.)
when invoked by an LLM. Multiple tools can be grouped together. Both can be
referenced with `@` when in the chat buffer:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          tools = {
            ["my_tool"] = {
              description = "Run a custom task",
              callback = require("user.codecompanion.tools.my_tool")
            },
            groups = {
              ["my_group"] = {
                description = "A custom agent combining tools",
                system_prompt = "Describe what the agent should do",
                tools = {
                  "cmd_runner",
                  "insert_edit_into_file",
                  -- Add your own tools or reuse existing ones
                },
                opts = {
                  collapse_tools = true, -- When true, show as a single group reference instead of individual tools
                },
              },
            },
          },
        },
      },
    })
<

When users introduce the group, `my_group`, in the chat buffer, it can call the
tools you listed (such as `cmd_runner`) to perform tasks on your code.

A tool is a |codecompanion-extending-tools| table with specific keys that
define the interface and workflow of the tool. The table can be resolved using
the `callback` option. The `callback` option can be a table itself or either a
function or a string that points to a luafile that return the table.


ENABLING TOOLS

Tools can be conditionally enabled using the `enabled` option. This works for
built-in tools as well as an adapter’s own tools. This is useful to ensure
that a particular dependency is installed on the machine. You can use the
`:CodeCompanionChat RefreshCache` command if you’ve installed a new
dependency and want to refresh the tool availability in the chat buffer.



APPROVALS

CodeCompanion allows you to apply safety mechanisms to its built-in tools prior
to execution.



AUTO SUBMIT (RECURSION)

When a tool executes, it can be useful to automatically send its output back to
the LLM. This can be achieved by the following options in your configuration:

`lua {6-7} require("codecompanion").setup({ interactions = { chat = { tools = {
opts = { auto_submit_errors = true, -- Send any errors to the LLM
automatically? auto_submit_success = true, -- Send any successful output to the
LLM automatically? }, } } } })`


DEFAULT TOOLS

You can configure the plugin to automatically add tools and tool groups to new
chat buffers:

`lua {6-9} require("codecompanion").setup({ interactions = { chat = { tools = {
opts = { default_tools = { "my_tool", "my_tool_group" } }, } } } })`

This also works for |codecompanion-configuration-extensions|.


USER INTERFACE (UI) ~


  [!NOTE] The |codecompanion-installation-other-plugins| section contains
  installation instructions for some popular markdown rendering plugins

AUTO SCROLLING

By default, the page scrolls down automatically as the response streams, with
the cursor placed at the end. This can be distracting if you are focusing on
the earlier content while the page scrolls up away during a long response. You
can disable this behavior using a flag:

>lua
    require("codecompanion").setup({
      display = {
        chat = {
          auto_scroll = false,
        },
      },
    })
<


  [!TIP] If you move your cursor while the LLM is streaming a response,
  auto-scrolling will be turned off.

COMPLETION

By default, CodeCompanion looks to use the fantastic blink.cmp
<https://github.com/Saghen/blink.cmp> plugin to complete variables, slash
commands and tools. However, you can override this in your config:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          opts = {
            completion_provider = "cmp", -- blink|cmp|coc|default
          }
        }
      }
    })
<

The plugin also supports nvim-cmp <https://github.com/hrsh7th/nvim-cmp>, a
native completion solution (`default`), and coc.nvim
<https://github.com/neoclide/coc.nvim>.


CONTEXT

It’s not uncommon for users to share many items, as context, with an LLM.
This can impact the chat buffer’s UI significantly, leaving a large space
between the LLM’s last response and the user’s input. To minimize this
impact, the context can be folded:

>lua
    require("codecompanion").setup({
      display = {
        chat = {
          icons = {
            chat_context = "📎️", -- You can also apply an icon to the fold
          },
          fold_context = true,
        },
      },
    })
<


LAYOUT

The plugin leverages floating windows to display content to a user in a variety
of scenarios, such as with the |codecompanion-usage-chat-buffer--super-diff|,
|codecompanion-usage-chat-buffer--messages| or agent
|codecompanion-usage-chat-buffer-agents.html-permissions|. You can change the
appearance of the chat buffer by changing the `display.chat.window` table in
your configuration.



REASONING

An adapter’s reasoning is streamed into the chat buffer by default, under a
`h3` heading. By default, this output will be folded once streaming has been
completed. You can turn off folding and hide reasoning output altogether:

>lua
    require("codecompanion").setup({
      display = {
        chat = {
          icons = {
            chat_fold = " ",
          },
          fold_reasoning = false,
          show_reasoning = false,
        },
      },
    })
<


ROLES

The chat buffer places user and LLM responses under a `H2` header. These can be
customized in the configuration:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          roles = {
            ---The header name for the LLM's messages
            ---@type string|fun(adapter: CodeCompanion.Adapter): string
            llm = function(adapter)
              return "CodeCompanion (" .. adapter.formatted_name .. ")"
            end,
    
            ---The header name for your messages
            ---@type string
            user = "Me",
          }
        }
      }
    })
<

By default, the LLM’s responses will be placed under a header such as
`CodeCompanion (DeepSeek)`, leveraging the current adapter in the chat buffer.
This option can be in the form of a string or a function that returns a string.
If you opt for a function, the first parameter will always be the adapter from
the chat buffer.

The user role is currently only available as a string.


OTHERS

There are also a number of other options that you can customize in the UI:

>lua
    require("codecompanion").setup({
      display = {
        chat = {
          intro_message = "Welcome to CodeCompanion ✨! Press ? for options",
          separator = "─", -- The separator between the different messages in the chat buffer
          show_context = true, -- Show context (from slash commands and variables) in the chat buffer?
          show_header_separator = false, -- Show header separators in the chat buffer? Set this to false if you're using an external markdown formatting plugin
          show_settings = false, -- Show LLM settings at the top of the chat buffer?
          show_token_count = true, -- Show the token count for each response?
          show_tools_processing = true, -- Show the loading message when tools are being executed?
          start_in_insert_mode = false, -- Open the chat buffer in insert mode?
        },
      },
    })
<


VARIABLES ~

Variables
<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/config.lua#L90>
are placeholders inserted into the chat buffer (using `#`). They provide
contextual code or information about the current Neovim state. For instance,
the built-in `#buffer` variable sends the current buffer’s contents to the
LLM.

You can even define your own variables to share specific content:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          variables = {
            ["my_var"] = {
              ---Ensure the file matches the CodeCompanion.Variable class
              ---@return string|fun(): nil
              callback = "/Users/Oli/Code/my_var.lua",
              description = "Explain what my_var does",
              opts = {
                contains_code = false,
                --has_params = true,    -- Set this if your variable supports parameters
                --default_params = nil, -- Set default parameters
              },
            },
          },
        },
      },
    })
<


SYNCING

Neovim buffers can be
|codecompanion-usage-chat-buffer-variables-with-parameters| with the chat
buffer. That is, on each turn their content can be shared with the LLM. This is
useful if you’re modifying a buffer and want the LLM to always have the
latest changes.

To enable this by default for the built-in `#buffer` variable, you can set the
`default_params` option to either `diff` or `all`:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          variables = {
            ["buffer"] = {
              opts = {
                -- Always sync the buffer by sharing its "diff"
                -- Or choose "all" to share the entire buffer
                default_params = "diff",
              },
            },
          },
        },
      },
    })
<


INLINE ASSISTANT                *codecompanion-configuration-inline-assistant*


  [!IMPORTANT] Only **http** adapters are supported for the inline assistant.
CodeCompanion provides an `inline` interaction for quick, direct editing of
your code. Unlike the chat buffer, the inline assistant integrates responses
directly into the current buffer—allowing the LLM to add or replace code as
needed.


CHANGING ADAPTER ~

By default, CodeCompanion sets the `copilot` adapter for the inline assistant.
You can change this to any other HTTP adapter:

>lua
    require("codecompanion").setup({
      interactions = {
        inline = {
          adapter = {
            name = "anthropic",
            model = "claude-haiku-4-5-20251001"
          },
        },
      },
    })
<

See the section on |codecompanion-configuration-adapters-http| for more
information.


KEYMAPS ~

The inline assistant supports keymaps for accepting or rejecting changes:

>lua
    require("codecompanion").setup({
      interactions = {
        inline = {
          keymaps = {
            accept_change = {
              modes = { n = "ga" },
              description = "Accept the suggested change",
            },
            reject_change = {
              modes = { n = "gr" },
              opts = { nowait = true },
              description = "Reject the suggested change",
            },
          },
        },
      },
    })
<

In this example, `ga` accepts inline changes, while `gr` rejects them.

You can also cancel an inline request with:

>lua
    require("codecompanion").setup({
      interactions = {
        inline = {
          keymaps = {
            stop = {
              modes = { n = "q" },
              index = 4,
              callback = "keymaps.stop",
              description = "Stop request",
            },
          },
        },
      },
    })
<


VARIABLES ~

The plugin comes with a number of
|codecompanion-usage-inline-assistant.html-variables| that can be used
alongside your prompt using the `#{}` syntax (e.g., `#{my_new_var}`). You can
also add your own:

>lua
    require("codecompanion").setup({
      interactions = {
        inline = {
          variables = {
            ["my_new_var"] = {
              ---@return string
              callback = "/Users/Oli/Code/my_var.lua",
              description = "My shiny new variable",
              opts = {
                contains_code = true,
              },
            },
          }
        }
      }
    })
<


LAYOUT ~

If the inline prompt creates a new buffer, you can also customize if this
should be output in a vertical/horizontal split or a new buffer:

>lua
    require("codecompanion").setup({
      display = {
        inline = {
          layout = "vertical", -- vertical|horizontal|buffer
        },
      }
    })
<


DIFF ~

Please see the |codecompanion-chat-buffer-diff| on the Chat Buffer page for
configuration options.


RULES                                      *codecompanion-configuration-rules*

Within CodeCompanion, rules fulfil two main purposes within a chat buffer:

1. To provide system-level instructions to your LLM
2. To provide persistent context via files in your project

Similar to Cursor’s Rules <https://cursor.com/docs/context/rules>, they
provide a way to guide the behavior of your LLM within a chat. Why? LLMs
don’t retain memory between sessions so preferences and context need to be
re-applied each time a new chat is started.


ENABLING RULES ~


Once enabled, the plugin will look to load a common, or default, set of rules
every time a chat buffer is created.


  [!INFO] Refer to the config.lua
  <https://github.com/olimorris/codecompanion.nvim/blob/5807e0457111f0de267fc9a6543b41fae0f5c2b1/lua/codecompanion/config.lua#L1167-L1179>
  file for the full set of files included in the default group.

RULE GROUPS ~

In the plugin, rule groups are a collection of files and/or directories that
can be loaded into the chat buffer. Groups give you flexibility to create
different sets of rules for different use-cases. For example, you may want a
set of rules specifically for working with Claude Code or another for working
with a specific project.


Nested groups allow you to apply the same conditional to multiple groups
alongside keeping your config clean. Infact, the plugin uses this itself. There
is a `CodeCompanion` group with sub-groups for different parts of the plugin,
allowing contributors to easily share context with an LLM when they’re
working on specific parts of the codebase.

When using the `Action Palette` or the slash command, the plugin will extract
these nested groups and display them in the `Chat with rules ...` menu.

You can also set default groups that are automatically applied to all chat
buffers. This is useful for ensuring that your preferred rules are always
available.


AUTOLOAD

You can set specific rule groups that will be automatically added to chat
buffers. This is useful for ensuring that your preferred rules are always
available.



PARSERS ~

Parsers allow CodeCompanion to transform rules, affecting how they are shared
in the chat buffer. This is particularly useful if you reference files in your
rules. Currently, the plugin has two in-built parsers:

- `claude` - which will import files into the chat buffer in the same way Claude Code does <https://code.claude.com/docs/en/memory#claude-md-imports>. Note, this requires rules to be `markdown` files
- `CodeCompanion` - parses rules in the same ways as `claude` but allows for a system prompts to be extracted via a H2 "System Prompt" header
- `none` - a blank parser which can be used to overwrite parsers that have been set on the default rules groups

Please see the guide on |codecompanion-extending-parsers| to understand how you
can create and apply your own.


APPLYING PARSERS

You can apply parsers at a group level, to ensure that all files in the group
are parsed in the same way. Alternatively, you can apply them at a file level
to have more granular control.



PROMPT LIBRARY                    *codecompanion-configuration-prompt-library*

CodeCompanion enables you to leverage prompt templates to quickly interact with
your codebase. These prompts can be the built-in ones or custom-built.
CodeCompanion uses a prompt library to manage and organize these prompts.


  [!IMPORTANT] Prompts can be pure Lua tables, residing in your configuration, or
  markdown files stored in your filesystem.

ADDING PROMPTS ~


  [!NOTE] See the |codecompanion--creating-prompts| section to learn how to
  create your own.
There are two ways to add prompts to the prompt library. You can either define
them directly in your configuration file as Lua tables, or you can store them
as markdown files in your filesystem and reference them in your configuration.



REFRESHING MARKDOWN PROMPTS

If you add or modify markdown prompts whilst your Neovim session is running,
you can refresh the prompt library to pick up the changes with:

>
    :CodeCompanionActions refresh
<


CREATING PROMPTS ~

As mentioned earlier, prompts can be created in two ways: as Lua tables or as
markdown files.


  [!NOTE] Markdown prompts are new in `v18.0.0`. They provide a cleaner, more
  maintainable way to define prompts with support for external Lua files for
  dynamic content.

WHY MARKDOWN?

Markdown prompts offer several advantages:

- **Cleaner syntax** - No Lua string escaping or concatenation
- **Better readability** - Natural formatting with proper indentation
- **Easier editing** - Edit in any markdown editor with syntax highlighting
- **Reusability** - Share Lua helper files across multiple prompts
- **Version control friendly** - Easier to diff and review changes

For complex prompts with multiple messages or dynamic content, markdown files
are significantly easier to maintain than Lua tables.


BASIC STRUCTURE

At their core, prompts define a series of messages sent to an LLM. Let’s
start with a simple example:


Markdown prompts consist of two main parts:

1. **Frontmatter** - YAML metadata between `---` delimiters that defines the prompt’s configuration
2. **Prompt sections** - Markdown headings (`## system`, `## user`) that define the role and content of each message

**Required frontmatter fields:** - `name` - The display name in the Action
Palette - `description` - Description shown in the Action Palette -
`interaction` - The interaction to use (`chat`, `inline`, `workflow`)

**Optional frontmatter fields:** - `opts` - Additional options (see
|codecompanion--options| section) - `context` - Pre-loaded context (see
|codecompanion--context-placeholders| section)

**Prompt sections:** - `## system` - System messages that set the LLM’s
behaviour - `## user` - User messages containing your requests


OPTIONS

Both markdown and Lua prompts support a wide range of options to customise
behaviour:


**Common options:**

- `adapter` - Specify a different adapter/model:


- `alias` - Allows the prompt to be triggered via `:CodeCompanion /{alias}`
- `auto_submit` - Automatically submit the prompt to the LLM
- `ignore_system_prompt` - Don’t send the default system prompt with the request
- `intro_message` - Custom intro message for the chat buffer UI
- `is_slash_cmd` - Make the prompt available as a slash command in chat
- `is_workflow` - Treat successive prompts as a workflow
- `modes` - Only show in specific modes (`{ "v" }` for visual mode)
- `placement` - For inline interaction: `new`, `replace`, `add`, `before`, `chat`
- `pre_hook` - Function to run before the prompt is executed (Lua only)
- `rules` - Specify a rule group to load with the prompt
- `stop_context_insertion` - Prevent automatic context insertion
- `user_prompt` - Get user input before actioning the response


PLACEHOLDERS

Placeholders allow you to inject dynamic content into your prompts. In markdown
prompts, use `${placeholder.name}` syntax:


CONTEXT PLACEHOLDERS

The `context` object contains information about the current buffer:


**Available context fields:**

>lua
    {
      bufnr = 7,
      buftype = "",
      code = [[local function hello(text)
        return "hello " .. text
      end]],
      cursor_pos = { 10, 3 },
      end_col = 3,
      end_line = 10,
      filetype = "lua",
      is_normal = false,
      is_visual = true,
      lines = { "local function hello(text)", '  return "hello " .. text', "end" },
      mode = "V",
      start_col = 1,
      start_line = 8,
      winnr = 1000
    }
<


EXTERNAL LUA FILES

For markdown prompts, you can reference functions and values from external Lua
files placed in the same directory as your prompt. This is useful for complex
logic or reusable components:

**Example directory structure:**

>
    .prompts/
    ├── commit.md
    ├── commit.lua
    └── utils.lua
<

**commit.lua:**

>lua
    return {
      diff = function(args)
        return vim.system({ "git", "diff", "--no-ext-diff", "--staged" }, { text = true }):wait().stdout
      end,
    }
<

**commit.md:**

>markdown
    ---
    name: Commit message
    interaction: chat
    description: Generate a commit message
    opts:
      alias: commit
    ---
    
    ## user
    
    You are an expert at following the Conventional Commit specification. Given the git diff listed below, please generate a commit message for me:
    
    ```diff
    ${commit.diff}
    ```
<

In this example, `${commit.diff}` references the `diff` function from
`commit.lua`. The plugin automatically:

1. Detects the dot notation (`commit.`)
2. Loads `commit.lua` from the same directory
3. Calls the `diff` function
4. Replaces `${commit.diff}` with the result

**Multiple files example:**

>markdown
    ---
    name: Code Review
    interaction: chat
    description: Review code changes
    ---
    
    ## user
    
    Please review this code:
    
    ```${context.filetype}
    ${context.code}
    ```
    
    Here's the git diff:
    
    ```diff
    ${utils.git_diff}
    ```
<

This prompt can reference functions from both `shared.lua` and `utils.lua` in
the same directory.

**Function signature:**

External Lua functions receive an `args` table:

>lua
    return {
      my_function = function(args)
        -- args.context - Buffer context
        -- args.item - The full prompt item
        return "some value"
      end,
      static_value = "I'm just a string",
    }
<


BUILT-IN HELPERS

You can also reference built-in values using dot notation:

- `${context.bufnr}` - Current buffer number
- `${context.filetype}` - Current filetype
- `${context.start_line}` - Visual selection start
- `${context.end_line}` - Visual selection end

And many more from the context object.


ADVANCED CONFIGURATION


CONDITIONALS

You can conditionally control when prompts appear in the Action Palette or
conditionally include specific prompt messages using `condition` functions:

**Lua only:**



CONTEXT

Pre-load a chat buffer with context from files, symbols, or URLs:


Context items appear at the top of the chat buffer. URLs are automatically
cached for you.


PICKERS

Pickers allow you to create dynamic prompt menus based on runtime data.

**Lua only:**

>lua
    ["My picker menu ..."] = {
      name = "A list of items",
      interaction = " ",
      description = "My current items",
      picker = {
        prompt = "Select an item",
        columns = { "name", "description" },
        items = {
          {
            name = "Item 1",
            description = "This is item 1",
            callback = function()
              print("You selected item 1")
            end,
          },
          {
            name = "Item 2",
            description = "This is item 2",
            callback = function()
              print("You selected item 2")
            end,
          },
        },
      },
    },
<


PRE-HOOKS

Pre-hooks allow you to run custom logic before a prompt is executed. This is
particularly useful for creating new buffers or setting up the environment:

**Lua only:**

>lua
    ["Boilerplate HTML"] = {
      interaction = "inline",
      description = "Generate some boilerplate HTML",
      opts = {
        ---@return number
        pre_hook = function()
          local bufnr = vim.api.nvim_create_buf(true, false)
          vim.api.nvim_set_current_buf(bufnr)
          vim.api.nvim_set_option_value("filetype", "html", { buf = bufnr })
          return bufnr
        end,
      },
      prompts = {
        {
          role = "system",
          content = "You are an expert HTML programmer",
        },
        {
          role = "user",
          content = "Please generate some HTML boilerplate for me. Return the code only and no markdown codeblocks",
        },
      },
    }
<

For the inline interaction, the plugin will detect a number being returned from
the `pre_hook` and assume that is the buffer number you wish any code to be
streamed into.


WORKFLOWS

Workflows allow you to chain multiple prompts together in a sequence. That is,
the first prompt is sent to the LLM, the LLM responds, then the next prompt in
the workflow is sent, etc. This can be useful for implementing multi-step
processes such as chain-of-thought reasoning or iterative code refinement.

**Note:** Markdown prompts do not support
|codecompanion-extending-agentic-workflows|.


You can also modify the options for the entire workflow at an individual prompt
level. This can be useful if you wish to automatically submit certain prompts
or change the adapter/model mid-workflow. Simply use a yaml code block with
`opts` as a meta field:



OTHERS ~


HIDING BUILT-IN PROMPTS

You can hide the built-in prompts from the Action Palette by setting the
following configuration option:

>lua
    require("codecompanion").setup({
      display = {
        action_palette = {
          opts = {
            show_prompt_library_builtins = false,
          }
        },
      },
    })
<


SYSTEM PROMPTS                    *codecompanion-configuration-system-prompts*


CHAT SYSTEM PROMPT ~

The default system prompt has been carefully curated to deliver terse and
professional responses that relate to development and Neovim. It is sent with
every request in the chat buffer.

The plugin comes with the following system prompt:

>txt
    You are an AI programming assistant named "CodeCompanion", working within the Neovim text editor.
    
    You can answer general programming questions and perform the following tasks:
    * Answer general programming questions.
    * Explain how the code in a Neovim buffer works.
    * Review the selected code from a Neovim buffer.
    * Generate unit tests for the selected code.
    * Propose fixes for problems in the selected code.
    * Scaffold code for a new workspace.
    * Find relevant code to the user's query.
    * Propose fixes for test failures.
    * Answer questions about Neovim.
    
    Follow the user's requirements carefully and to the letter.
    Use the context and attachments the user provides.
    Keep your answers short and impersonal, especially if the user's context is outside your core tasks.
    Use Markdown formatting in your answers.
    Do not use H1 or H2 markdown headers.
    When suggesting code changes or new content, use Markdown code blocks.
    To start a code block, use 4 backticks.
    After the backticks, add the programming language name as the language ID.
    To close a code block, use 4 backticks on a new line.
    If the code modifies an existing file or should be placed at a specific location, add a line comment with 'filepath:' and the file path.
    If you want the user to decide where to place the code, do not add the file path comment.
    In the code block, use a line comment with '...existing code...' to indicate code that is already present in the file.
    Code block example:
    ````languageId
    // filepath: /path/to/file
    // ...existing code...
    { changed code }
    // ...existing code...
    { changed code }
    // ...existing code...
    ````
    Ensure line comments use the correct syntax for the programming language (e.g. "#" for Python, "--" for Lua).
    For code blocks use four backticks to start and end.
    Avoid wrapping the whole response in triple backticks.
    Do not include diff formatting unless explicitly asked.
    Do not include line numbers in code blocks.
    
    When given a task:
    1. Think step-by-step and, unless the user requests otherwise or the task is very simple, describe your plan in pseudocode.
    2. When outputting code blocks, ensure only relevant code is included, avoiding any repeating or unrelated code.
    3. End your response with a short suggestion for the next user turn that directly supports continuing the conversation.
    
    Additional context:
    All non-code text responses must be written in the ${language} language.
    The current date is ${date}.
    The user's Neovim version is ${version}.
    The user is working on a ${os} machine. Please respond with system specific commands if applicable.
<


TOOL SYSTEM PROMPT ~

CodeCompanion also ships with a separate system prompt when
|codecompanion-usage-chat-buffer-tools| are used in the chat buffer:

>txt
    <instructions>
    You are a highly sophisticated automated coding agent with expert-level knowledge across many different programming languages and frameworks.
    The user will ask a question, or ask you to perform a task, and it may require lots of research to answer correctly. There is a selection of tools that let you perform actions or retrieve helpful context to answer the user's question.
    You will be given some context and attachments along with the user prompt. You can use them if they are relevant to the task, and ignore them if not.
    If you can infer the project type (languages, frameworks, and libraries) from the user's query or the context that you have, make sure to keep them in mind when making changes.
    If the user wants you to implement a feature and they have not specified the files to edit, first break down the user's request into smaller concepts and think about the kinds of files you need to grasp each concept.
    If you aren't sure which tool is relevant, you can call multiple tools. You can call tools repeatedly to take actions or gather as much context as needed until you have completed the task fully. Don't give up unless you are sure the request cannot be fulfilled with the tools you have. It's YOUR RESPONSIBILITY to make sure that you have done all you can to collect necessary context.
    Don't make assumptions about the situation - gather context first, then perform the task or answer the question.
    Think creatively and explore the workspace in order to make a complete fix.
    Don't repeat yourself after a tool call, pick up where you left off.
    NEVER print out a codeblock with a terminal command to run unless the user asked for it.
    You don't need to read a file if it's already provided in context.
    </instructions>
    <toolUseInstructions>
    When using a tool, follow the json schema very carefully and make sure to include ALL required properties.
    Always output valid JSON when using a tool.
    If a tool exists to do a task, use the tool instead of asking the user to manually take an action.
    If you say that you will take an action, then go ahead and use the tool to do it. No need to ask permission.
    Never use a tool that does not exist. Use tools using the proper procedure, DO NOT write out a json codeblock with the tool inputs.
    Never say the name of a tool to a user. For example, instead of saying that you'll use the insert_edit_into_file tool, say "I'll edit the file".
    If you think running multiple tools can answer the user's question, prefer calling them in parallel whenever possible.
    When invoking a tool that takes a file path, always use the file path you have been given by the user or by the output of a tool.
    </toolUseInstructions>
    <outputFormatting>
    Use proper Markdown formatting in your answers. When referring to a filename or symbol in the user's workspace, wrap it in backticks.
    Any code block examples must be wrapped in four backticks with the programming language.
    <example>
    ````languageId
    // Your code here
    ````
    </example>
    The languageId must be the correct identifier for the programming language, e.g. python, javascript, lua, etc.
    If you are providing code changes, use the insert_edit_into_file tool (if available to you) to make the changes directly instead of printing out a code block with the changes.
    </outputFormatting>
<


CHANGING SYSTEM PROMPTS ~


CHAT

The chat system prompt can be changed with:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          opts = {
            system_prompt = "My new system prompt",
          },
        },
      },
    })
<

Alternatively, the system prompt can be a function. The `opts` parameter
contains several pieces of information related to the chat, which you can use
to build the system prompt:

>lua
    ---@class CodeCompanion.SystemPrompt.Context
    ---@field language string
    ---@field adapter CodeCompanion.HTTPAdapter|CodeCompanion.ACPAdapter
    ---@field date string
    ---@field nvim_version string
    ---@field os string the operating system that the user is using
    ---@field default_system_prompt string
    ---@field cwd string current working directory
    ---The closest parent directory that contains one of the following VCS markers:
    --- - `.git`
    --- - `.svn`
    --- - `.hg`
    ---@field project_root? string the closest parent directory that contains a `.git` subdirectory.
    
    require("codecompanion").setup({
      interactions = {
        chat = {
          opts = {
            ---@param ctx CodeCompanion.SystemPrompt.Context
            ---@return string
            system_prompt = function(ctx)
              return ctx.default_system_prompt
                .. fmt(
                  [[Additional context:
    All non-code text responses must be written in the %s language.
    The current date is %s.
    The user's Neovim version is %s.
    The user is working on a %s machine. Please respond with system specific commands if applicable.
    ]],
                  ctx.language,
                  ctx.date,
                  ctx.nvim_version,
                  ctx.os
                )
            end,
          },
        },
      },
    })
<


TOOLS

There are additional options available when working with tool system prompts:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          tools = {
            opts = {
              system_prompt = {
                enabled = true, -- Enable the tools system prompt?
                replace_main_system_prompt = false, -- Replace the main system prompt with the tools system prompt?
    
                ---The tool system prompt
                ---@param args { tools: string[]} The tools available
                ---@return string
                prompt = function(args)
                  return "My custom tools prompt"
                end,
              },
            },
          },
        },
      },
    })
<


WHEN SYSTEM PROMPTS CHANGE ~

There are various scenarios for when the system prompt may change in the chat
buffer:

- When a user changes adapter
- When a user changes the model on an adapter
- When a rule is added
- When a tool (with a defined system prompt) is added to the chat buffer

CodeCompanion will always resolve a system prompt change asynchronously, as
many adapters make a HTTP request to a server in order to obtain the available
models.


EXTENSIONS                            *codecompanion-configuration-extensions*

CodeCompanion supports extensions similar to telescope.nvim, allowing users to
create functionality that can be shared with others. Extensions can either be
distributed as plugins or defined locally in your configuration.


INSTALLING EXTENSIONS ~

CodeCompanion supports extensions that add additional functionality to the
plugin. For example, to install and set up the mcphub extension using
lazy.nvim:

1. Install the extension:

>lua
    {
      "olimorris/codecompanion.nvim",
      dependencies = {
        -- Add mcphub.nvim as a dependency
        "ravitemer/mcphub.nvim"
      }
    }
<

1. Add extension to your config with additional options:

>lua
    -- Configure in your setup
    require("codecompanion").setup({
      extensions = {
        mcphub = {
          callback = "mcphub.extensions.codecompanion",
          opts = {
            make_vars = true,
            make_slash_commands = true,
            show_result_in_chat = true
          }
        }
      }
    })
<

Visit the creating |codecompanion-extending-extensions| guide to learn more
about available extensions and how to create your own.


OTHER OPTIONS                      *codecompanion-configuration-other-options*


LANGUAGE ~

If you use the default system prompt, you can specify which language an LLM
should respond in by changing the `opts.language` option:

>lua
    require("codecompanion").setup({
      opts = {
        language = "English",
      },
    }),
<

Of course, if you have your own system prompt you can specify your own language
for the LLM to respond in.


LOG LEVEL ~


  [!IMPORTANT] By default, logs are stored at
  `~/.local/state/nvim/codecompanion.log`
When it comes to debugging, you can change the level of logging which takes
place in the plugin as follows:

>lua
    require("codecompanion").setup({
      opts = {
        log_level = "ERROR", -- TRACE|DEBUG|ERROR|INFO
      },
    }),
<


SENDING CODE ~


  [!IMPORTANT] Whilst the plugin makes every attempt to prevent code from being
  sent to the LLM, use this option at your own risk
You can prevent any code from being sent to the LLM with:

>lua
    require("codecompanion").setup({
      opts = {
        send_code = false,
      },
    }),
<


==============================================================================
6. Usage                                                 *codecompanion-usage*


GENERAL                                          *codecompanion-usage-general*

CodeCompanion continues to evolve with regular frequency. This page will
endeavour to serve as focal point for providing useful productivity tips for
the plugin.


COPYING CODE FROM A CHAT BUFFER ~

The fastest way to copy an LLM’s code output is with `gy`. This will yank the
nearest codeblock.


APPLYING AN LLM€�S EDITS TO A BUFFER OR FILE ~

The |codecompanion-usage-chat-buffer-tools-files| tool, combined with the
|codecompanion-usage-chat-buffer-variables.html-buffer| variable or
|codecompanion-usage-chat-buffer-slash-commands.html-buffer| slash command,
enables an LLM to modify code in a Neovim buffer. This is especially useful if
you do not wish to manually apply an LLM’s suggestions yourself. Simply tag
it in the chat buffer with `@files` or `@insert_edit_into_file`.


RUN TESTS FROM THE CHAT BUFFER ~

The |codecompanion-usage-chat-buffer-tools-cmd-runner| tool enables an LLM to
execute commands on your machine. This can be useful if you wish the LLM to run
a test suite on your behalf and give insight on failing cases. Simply tag the
`@cmd_runner` in the chat buffer and ask it run your tests.


NAVIGATING BETWEEN RESPONSES IN THE CHAT BUFFER ~

You can quickly move between responses in the chat buffer using `[[` or `]]`.


QUICKLY ACCESSING A CHAT BUFFER ~

The `:CodeCompanionChat Toggle` command will automatically create a chat buffer
if one doesn’t exist, open the last chat buffer or hide the current chat
buffer.

When in a chat buffer, you can cycle between other chat buffers with `{` or
`}`.


ACP PROTOCOL REFERENCE            *codecompanion-usage-acp-protocol-reference*

CodeCompanion implements the Agent Client Protocol (ACP)
<https://agentclientprotocol.com/> to enable you to work with coding agents
from within Neovim. ACP is an open standard that enables structured interaction
between clients (like CodeCompanion) and AI agents, providing capabilities such
as session management, file system operations, tool execution, and permission
handling.

This page provides a technical reference for what’s supported in
CodeCompanion and how it’s been implemented.


PROTOCOL SUPPORT ~

CodeCompanion provides comprehensive support for the ACP specification:

  ------------------------------------------------------------------------
  Feature Category               Support Level             Details
  ------------------------------ ------------------------- ---------------
  Core Protocol                  ✅ Full                   JSON-RPC 2.0,
                                                           streaming
                                                           responses,
                                                           message
                                                           buffering

  Session Management             ✅ Full                   Create, load,
                                                           and persist
                                                           sessions with
                                                           state tracking

  Authentication                 ✅ Full                   Multiple auth
                                                           methods,
                                                           adapter-level
                                                           hooks

  File System                    ✅ Full                   Read/write text
                                                           files with line
                                                           ranges

  Permissions                    ✅ Full                   Interactive UI
                                                           with diff
                                                           preview for
                                                           tool approval

  Content Types                  ✅ Full                   Text, images,
                                                           embedded
                                                           resources

  Tool Calls                     ✅ Full                   Content blocks,
                                                           file diffs,
                                                           status updates

  Session Modes                  ✅ Full                   Mode switching
                                                           and state
                                                           management

  MCP Integration                ✅ Full                   Stdio, HTTP,
                                                           and SSE
                                                           transports

  Agent Plans                    ❌                        Visual display
                                                           of an agent’s
                                                           execution plan

  Terminal Operations            ❌                        Terminal
                                                           capabilities
                                                           not implemented
  ------------------------------------------------------------------------

SUPPORTED ADAPTERS

Please see the |codecompanion-configuration-adapters-acp| page.


CLIENT CAPABILITIES

CodeCompanion advertises the following capabilities to ACP agents:

>lua
    {
      fs = {
        readTextFile = true,   -- Read files with optional line ranges
        writeTextFile = true   -- Write/create files
      },
      terminal = false         -- Terminal operations not supported
    }
<


CONTENT SUPPORT

  Content Type         Send to Agent   Receive from Agent
  -------------------- --------------- --------------------
  Text                 ✅              ✅
  Images               ✅              ✅
  Embedded Resources   ✅              ✅
  Audio                ❌              ❌
  File Diffs           N/A             ✅

SESSION UPDATES HANDLED

CodeCompanion processes the following session update types:

- **Message chunks**: Streamed text from agent responses
- **Thought chunks**: Agent reasoning displayed separately
- **Tool calls**: Full execution lifecycle with status tracking
- **Mode changes**: Automatic UI updates when modes switch
- **Available commands**: Dynamic command registration for completion


IMPLEMENTATION NOTES ~


MESSAGE BUFFERING

JSON-RPC message boundaries don’t always align with I/O boundaries.
CodeCompanion buffers stdout from the agent process and extracts complete
JSON-RPC messages line-by-line, ensuring robust parsing even with partial
reads.


STATE MANAGEMENT

Unlike HTTP adapters which are stateless (sending the full conversation history
with each request), ACP adapters are stateful. The agent maintains the
conversation context, so CodeCompanion only sends new messages with each
prompt. Session IDs are tracked throughout the conversation lifecycle.


TOOL CALL CACHING

Tool call state is maintained in memory to support permission requests. When an
agent requests permission for a tool call, the cached details enable features
like the diff preview UI for file edits.


FILE CONTEXT HANDLING

When sending files as embedded resources to agents, CodeCompanion re-reads the
file content rather than using the chat buffer representation. This avoids
HTTP-style `<attachment>` tags that are used for LLM adapters but don’t make
sense for ACP agents.


SLASH COMMANDS

ACP agents can advertise their own slash commands dynamically. You can access
them with `\command` in the chat buffer. CodeCompanion transforms this to
`/command` before sending your prompt to the agent.


MODEL SELECTION

CodeCompanion implements a `session/set_model` method that allows you to select
a model for the current session. This feature is not part of the official ACP
specification
<https://agentclientprotocol.com/protocol/draft/schema#session-set_model> and
is subject to change in future versions.


GRACEFUL DEGRADATION

CodeCompanion checks an agent’s capabilities during initialization and
gracefully falls back to supported content types. For example, if an agent
doesn’t support embedded context, files are sent as plain text instead.


CLEANUP AND LIFECYCLE

CodeCompanion ensures clean disconnection from ACP agents by hooking into
Neovim’s `VimLeavePre` autocmd. This guarantees that agent processes are
properly terminated even if Neovim exits unexpectedly.


KEY FEATURES ~

- **Streaming**: Real-time response streaming with chunk-by-chunk rendering
- **Permission System**: Interactive approval for file operations with diff preview
- **Session Persistence**: Resume previous conversations across Neovim sessions
- **Mode Management**: Switch between agent modes (e.g. ask, architect, code)
- **MCP Servers**: Connect agents to external tools via the Model Context Protocol
- **Slash Command Completion**: Auto-complete agent-specific commands with `\command` syntax
- **Error Handling**: Comprehensive error messages and graceful degradation


PROTOCOL VERSION ~

CodeCompanion currently implements **ACP Protocol Version 1**.

The protocol version is negotiated during initialization. If an agent selects a
different version, CodeCompanion will log a warning but continue to operate,
following the agent’s selected version.


KNOWN LIMITATIONS ~

- **Terminal Operations**: The `terminal/*` family of methods (`terminal/create`,
    `terminal/output`, `terminal/release`, etc.) are not implemented. CodeCompanion
    doesn’t advertise terminal capabilities to agents.
- **Agent Plan Rendering**: Plan
    <https://agentclientprotocol.com/protocol/agent-plan> updates from agents are
    received and logged, but they’re not currently rendered in the chat buffer
    UI.
- **Audio Content**: Audio content blocks aren’t sent in prompts, despite
    capability detection.


SEE ALSO ~

- |codecompanion-configuration-adapters-acp| - Setup instructions for specific agents
- |codecompanion-usage-chat-buffer-agents| - How to interact with agents in chat
- Agent Client Protocol Specification <https://agentclientprotocol.com/> - Official ACP documentation


ACTION PALETTE                            *codecompanion-usage-action-palette*

The `Action Palette` has been designed to be your entry point for the many
configuration options that CodeCompanion offers. It can be opened with
`:CodeCompanionActions`.

Once opened, the user can see plugin defined actions such as `Chat` and `Open
Chats`. The latter, enabling the user to move between any open chat buffers.
These can be turned off in the config by setting
`display.action_palette.opts.show_preset_actions = false`.


BUILT-IN PROMPTS ~

The plugin also defines a number of prompts in the form of the prompt library:

- `Commit message` - Generate a commit message
- `Explain code` - Explain how code in a buffer works
- `Explain LSP diagnostics` - Explain the LSP diagnostics for the selected code
- `Fix code` - Fix the selected code
- `Unit tests` - Generate unit tests for selected code


  [!INFO] These can also be called via the cmd line with their `alias`, for
  example `:CodeCompanion /explain`
The plugin also contains two built-in workflows, `Code workflow` and `Edit test
repeat workflow`. See the |codecompanion-usage-workflows| for more information.

The built-in prompts can be turned off by setting
`display.action_palette.opts.show_preset_prompts = false`.

You can also refresh the markdown prompts in your prompt library with
`:CodeCompanionActions refresh`


CHAT BUFFER                                  *codecompanion-usage-chat-buffer*


  [!NOTE] The chat buffer has a filetype of `codecompanion` and a buftype of
  `nofile`.
You can open a chat buffer with the `:CodeCompanionChat` command or with
`require("codecompanion").chat()` and you can toggle the visibility of the chat
buffer with `:CodeCompanionChat Toggle` or `require("codecompanion").toggle()`.

You can even customize the chat buffer’s window options:

>lua
    require("codecompanion").chat({ window_opts = { layout = "float", width = 0.6 }})
    -- or:
    require("codecompanion").toggle({ window_opts = { layout = "float", width = 0.6 }})
<

The chat buffer uses markdown as its syntax and `H2` headers separate the user
and LLM’s responses. The plugin is turn-based, meaning that the user sends a
response which is then followed by the LLM’s. The user’s responses are
parsed by treesitter and sent via an adapter to an LLM for a response which is
then streamed back into the buffer. A response is sent to the LLM by pressing
`<CR>` or `<C-s>`. This can of course be changed as per the
|codecompanion--keymaps| section.


CHANGING ADAPTER AND MODEL ~



One of the joys of working with CodeCompanion is being able to switch between
conversing with an LLM and an agent, all from within the chat buffer.

To do this, simply press `ga` to open up the `Select Adapter` select window. If
your chosen adapter has more than one model then you’ll be prompted to make
another selection. This works for both `HTTP` and `ACP` adapters.


CHANGING ACP COMMAND ~

ACP adapters are initiated via a command in the configuration. By default, this
will be the `default` command. Some ACP adapters have additional commands and
these can be triggered via the cmd line with something like `:CodeCompanionChat
adapter=gemini_cli command=yolo`, or you can use the
|codecompanion-usage-chat-buffer-slash-commands-command| slash command within
the chat buffer.


COMPLETION ~


  [!IMPORTANT] As of `v17.5.0`, variables and tools are wrapped in curly braces
  automatically, such as `#{buffer}` or `@{files}`


You can invoke the completion plugins by typing `#` or `@` followed by the
variable or tool name, which will trigger the completion menu. If you don’t
use a completion plugin, you can use native completions with no setup, invoking
them with `<C-_>` from within the chat buffer.

When using an ACP adapter (such as claude-code), you can also type `\`
(backslash, by default) to get completions for ACP commands. These are
agent-specific commands like `/compact` (compact chat history) that are
dynamically discovered from the agent itself.


  [!NOTE] It typically takes 1-5 seconds after opening a chat buffer for ACP
  commands to become available. The agent needs to initialize and scan for both
  built-in and custom commands. If you define a new custom command mid-session,
  the same delay applies before it appears in the completion list.
The backslash trigger is used to avoid conflicts with CodeCompanion’s
built-in |codecompanion-usage-chat-buffer-slash-commands|. When you send a
message, `\command` is automatically transformed to `/command` for the agent.
The trigger character can be customized via
`interactions.chat.slash_commands.opts.acp.trigger` in your config.

It’s worth noting that not all commands available in ACP CLI tools are
exposed via the SDK. Only a subset of built-in commands are supported, though
this is constantly evolving as the underlying SDKs mature.


CONTEXT ~



Sharing context with an LLM is crucial in order to generate useful responses.
In the plugin, context is defined as output that is shared with a chat buffer
via a `Variable`, `Slash Command` or `Tool`. They appear in a blockquote
entitled `Context`. In essence, this is context that you’re sharing with an
LLM.


  [!IMPORTANT] Context items contain the data of an object at a point in time. By
  default, they **are not** self-updating
In order to allow for context to self-update, buffers and files can be synced
to a chat buffer. On every turn, you can determine what is sent to the LLM. For
buffers, you can choose to send `all` of the content or just the `diff`. For
files, you only have the choice of sending `all` of the content.

The advantage of sending `all` of a file or buffer’s content is that the LLM
will always receive a fresh copy of the source data regardless of any changes.
This can be useful if you’re working with tools. However, please note that
this can consume a lot of tokens.

Syncing and sending only a `diff`, is a more token-conscious way of keeping the
LLM up to date on the contents of a buffer. Buffer diffs track changes (adds,
edits, deletes) in the underlying buffer and update the LLM on each turn, with
only those changes.

If a context item is added by mistake, it can be removed from the chat buffer
by simply deleting it from the `Context` blockquote. On the next turn, all data
related to that context item will be removed from the message history.

Finally, it’s important to note that all http adapter endpoints require the
sending of previous messages that make up the conversation. So even though
you’ve shared context once, many messages ago, the LLM will always be able to
refer to it, unless you actively alter the history of the conversation via
`gd`.


GENERATING TITLES ~

CodeCompanion can automatically generate titles for your chat buffers based on
their content. This is accomplished via a background interaction. To enable
this:

`lua{11,16} require("codecompanion").setup({ interactions = { background = {
chat = { callbacks = { ["on_ready"] = { actions = {
"interactions.background.builtin.chat_make_title", }, -- Enable "on_ready"
callback which contains the title generation action enabled = true, }, }, opts
= { -- Enable background interactions generally enabled = true, }, }, }, } })`

Finally, ensure that you have an adapter configured for any background
interactions.


IMAGES / VISION ~

Many LLMs have the ability to receive images as input (sometimes referred to as
vision). CodeCompanion supports the adding of images into the chat buffer via
the |codecompanion-usage-chat-buffer-slash-commands-image| slash command and
through the system clipboard with |codecompanion-installation-img-clip-nvim|.
CodeCompanion can work with images in your file system and also with remote
URLs, encoding both into a base64 representation.

If your adapter and model doesn’t support images, then CodeCompanion will
endeavour to ensure that the image is not included in the messages payload
that’s sent to the LLM.


KEYMAPS ~

The plugin has a host of keymaps available in the chat buffer. Pressing `?` in
the chat buffer will conveniently display all of them to you.

The keymaps available to the user in normal mode are:

- `<CR>|<C-s>` to send a message to the LLM
- `<C-c>` to close the chat buffer
- `q` to stop the current request
- `ga` to change the adapter for the currentchat
- `gba` to sync the entire buffer on every turn
- `gbd` to sync only a buffers diff on every turn
- `gc` to insert a codeblock in the chat buffer
- `gd` to view/debug the chat buffer’s contents
- `gD` to view the chat buffer’s super diff feature
- `gf` to fold any codeblocks in the chat buffer
- `gM` to clear all rules from the chat buffer
- `gr` to regenerate the last response
- `gR` to go to the file under cursor. If the file is already opened, it’ll jump
    to the existing window. Otherwise, it’ll be opened in a new tab.
- `gs` to toggle the system prompt on/off
- `gS` to show copilot usage stats
- `gta` to toggle auto tool mode
- `gx` to clear the chat buffer’s contents
- `gy` to yank the last codeblock in the chat buffer
- `[[` to move to the previous header
- `]]` to move to the next header
- `{` to move to the previous chat
- `}` to move to the next chat

To disable a keymap, you can set it to `false` in your configuration:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          keymaps = {
            clear = false,
          }
        }
      }
    })
<


MESSAGES ~


  [!TIP] The message history and adapter settings can be modified via the debug
  window (`gd`) in the chat buffer
It’s important to note that some messages, such as system prompts or context
provided via |codecompanion-usage-chat-buffer-slash-commands|, will be hidden.
This is to keep the chat buffer uncluttered from a UI perspective. Using the
`gd` keymap opens up the debug window, which allows the user to see the full
contents of the messages table which will be sent to the LLM on the next turn.

The message history cannot be altered directly in the chat buffer. However, it
can be modified in the debug window. This window is simply a Lua buffer which
the user can edit as they wish. To persist any changes, the chat buffer keymaps
for sending a message (defaults: `<CR>` or `<C-s>`) can be used.


SETTINGS ~



When conversing with an LLM, it can be useful to tweak model settings in
between responses in order to generate the perfect output. If settings are
enabled (`display.chat.show_settings = true`), then a yaml block will be
present at the top of the chat buffer which can be modified in between
responses. The yaml block is simply a representation of an adapter’s schema
table.


SUPER DIFF ~



When an LLM uses tools like
|codecompanion-usage-chat-buffer-tools-insert-edit-into-file| to make changes
across multiple files and buffers, it can be difficult to keep track. This is
amplified if the tools are working without requiring approvals (perhaps via
|codecompanion-usage-chat-buffer-tools.html-automatic-tool-mode|) and it simply
isn’t impossible to keep track of what an LLM has added, deleted or modified.

Super Diff gives you a single, unified view of all edits made in via the chat
buffer. Open it with `gD` to review every change, grouped by file, with visual
diffs and status indicators. You can accept or reject changes before they’re
applied, keeping you in control of your codebase. You can even send changes to
the quickfix list for easier navigation and review.


AGENTS                                            *codecompanion-usage-agents*

CodeCompanion implements the Agent Client Protocol
<https://agentclientprotocol.com> to enable you to work with coding agents from
within Neovim. Please refer to the |codecompanion-configuration-adapters-acp|
if you’ve not setup an ACP adapter.


GETTING STARTED ~

To start coding with agents right away, ensure you’ve
|codecompanion-configuration-adapters-acp-setup-claude-code| on your chosen
adapter, correctly. Then, open a chat buffer with `:CodeCompanionChat` and
|codecompanion-usage-chat-buffer--changing-adapter| to an ACP adapter such as
`gemini_cli`, if it’s not set as your default.

A key difference in working with agents versus LLMs is the matter of state.
LLMs, via `http` adapters, are stateless. This means that CodeCompanion sends
the entire message history over with every request. Agents differ in that they
are the ones responsible for managing state. As a result, CodeCompanion only
sends the latest messages over with every prompt. From a UX perspective
however, neither of these have an impact on how it feels to work with
CodeCompanion.


CHANGING MODEL ~



Sometimes it can be helpful to switch between models if you’re conscious of
token consumption or changing workloads. You can do this within the chat buffer
by pressing `ga` to open the change adapter/model picker.


PROMPTING ~

Conversing with an agent in CodeCompanion is done in exactly the same way as
with an LLM. Simply type your prompt and press `<C-CR>` in insert mode or
`<CR>` in normal mode to send it to the agent.

|codecompanion-usage-chat-buffer-slash-commands| and
|codecompanion-usage-chat-buffer-variables| are available to share additional
context with the agent. However, |codecompanion-usage-chat-buffer-tools| are
disabled as the agent has their own tool set and the autonomy to decide what to
run and when. CodeCompanion also supports an agent’s own slash commands
<https://agentclientprotocol.com/protocol/slash-commands> however these are
invoked with `\` instead of `/` which is reserved for CodeCompanion’s
built-in ones.

As outlined in the Agent Client Protocol documentation
<https://agentclientprotocol.com/protocol/initialization>, there are a number
of steps which take place internally before a response is received from the
agent. The initialization and creating of a session inevitably lead to the
first prompt waiting slightly longer to receive a response than future ones.


PERMISSIONS ~

At various points during the agent’s lifecycle, you may be prompted for
permission
<https://agentclientprotocol.com/protocol/schema#session%2Frequest-permission>
to execute a tool.

If the agent wishes to edit a file, then you will be shown a diff and presented
with the various options available to you. You can send a response back to the
agent via the keymaps defined in your config at
`interactions.chat.keymaps._acp_*` (which are also displayed to you in the
diff). If there is no diff associated with the tool call then you will be
prompted via |vim.fn.confirm|.

By default, the chat buffer will wait for c. 30 mins for you to respond to a
permission request. This can be configured in
`interactions.chat.opts.wait_timeout` with the default response, after a
timeout, being defined at `interactions.chat.opts.acp_timeout_response`.


CANCELLING A REQUEST ~

You can halt the execution of a request at any point by pressing `q` in normal
mode which will send a cancellation notification to the agent.


IMAGES ~

The |codecompanion-usage-chat-buffer-slash-commands.html-image| slash command
can be leveraged to share images with the agent.


RULES                                              *codecompanion-usage-rules*

Ensure that you have read the |codecompanion-configuration-rules| section to
understand how to create and configure rule groups.


DEFAULT RULE GROUP ~

Below is the `default` rule group that, when
|codecompanion-configuration-rules-enabling-rules|, provides a collection of
common files to the chat buffer:

>lua
    require("codecompanion").setup({
      rules = {
        default = {
          description = "Collection of common files for all projects",
          files = {
            ".clinerules",
            ".cursorrules",
            ".goosehints",
            ".rules",
            ".windsurfrules",
            ".github/copilot-instructions.md",
            "AGENT.md",
            "AGENTS.md",
            { path = "CLAUDE.md", parser = "claude" },
            { path = "CLAUDE.local.md", parser = "claude" },
            { path = "~/.claude/CLAUDE.md", parser = "claude" },
          },
        },
      },
    })
<


CREATING RULES ~

The plugin does not require rules to be in a specific filetype or even format
(unless you’re using the `claude` parser). This allows you to leverage mdc
<https://docs.cursor.com/en/context/rules#rule-anatomy> files, markdown files
or good old plain text files.

The location of the rules is also unimportant. The rules files could be local
to the project you’re working in. Or, they could reside in a separate
location on your disk. Just ensure the path is correct when you’re
|codecompanion-configuration-rules-rule-groups| the rules group.

You can even set the system prompt for the chat buffer in the rules file
itself.


EXAMPLE 1: RULE THAT CAN BE PROCESSED WITH THE CODECOMPANION PARSER

>markdown
    # Example Rules File
    
    ## System Prompt
    
    What ever goes in this section is used as a system prompt in the chat buffer.
    
    So you can specify instructions:
    - Here
    - And here
    
    ...and anywhere here
    
    ## My other header
    
    @./lua/codecompanion/interactions/chat/tools/init.lua
    
    Anything in this section is added as context to the chat buffer. The file above is also shared
<


EXAMPLE 2: RULE THAT CAN BE PROCESSED WITH THE CLAUDE PARSER

>markdown
    # Example Claude Rules File
    
    @./lua/codecompanion/interactions/chat/tools/init.lua
    
    This is a rules file that can be parsed with the Claude parser.
    
    Anything in this file is added as context to the chat buffer.
    
    Including the file above.
<


ADDING RULES TO A CHAT BUFFER ~


WHEN OPENING THE CHAT BUFFER

Rules can automatically be added to a chat buffer when it’s created. Just
specify the default rules to include:



SLASH COMMAND

To add rules to an existing chat buffer, use the `/rules` slash command. This
will allow multiple rule groups to be added at a time.


ACTION PALETTE



There is also a `Chat with rules` action in the
|codecompanion-usage-action-palette|. This lists all of the rule groups in the
config that can be added to a new chat buffer.


CLEARING RULES

Rules can also be cleared from a chat buffer via the `gR` keymap. Although
note, this will remove `ALL` context that’s been designated as `rules`.


TOOLS                                              *codecompanion-usage-tools*


  [!IMPORTANT] Tools are not supported for ACP adapters as they have their own
  set. Not all LLMs support function calling and the use of tools. Please see the
  |codecompanion--compatibility| section for more information.
As outlined by Andrew Ng in Agentic Design Patterns Part 3, Tool Use
<https://www.deeplearning.ai/the-batch/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, tools are simply context and actions that are shared with an
LLM. The LLM can act as an agent by executing tools via the chat buffer which
in turn orchestrates their use within Neovim. Tools can be added as a
participant to the chat buffer by using the `@` key.


  [!IMPORTANT] The use of some tools in the plugin results in you, the developer,
  acting as the human-in-the-loop and approving their use.

HOW THEY WORK ~

Tools make use of an LLM’s function calling
<https://platform.openai.com/docs/guides/function-calling> ability. All tools
in CodeCompanion follow OpenAI’s function calling specification, here
<https://platform.openai.com/docs/guides/function-calling#defining-functions>.

When a tool is added to the chat buffer, the LLM is instructured by the plugin
to return a structured JSON schema which has been defined for each tool. The
chat buffer parses the LLMs response and detects the tool use before triggering
the `tools/init.lua` file. The tool system triggers off a series of events,
which sees tool’s added to a queue and sequentially worked with their output
being shared back to the LLM via the chat buffer. Depending on the tool, flags
may be inserted on the chat buffer for later processing.

An outline of the architecture can be seen
|codecompanion-extending-tools-architecture|.


BUILT-IN TOOLS ~

CodeCompanion comes with a number of built-in tools which you can leverage, as
long as your adapter and model are |codecompanion--compatibility|.

When calling a tool, CodeCompanion replaces the tool call in any prompt you
send to the LLM with the value of a tool’s `opts.tool_replacement_message`
string. This is to ensure that you can call a tool efficiently whilst making
the prompt readable to the LLM.

So calling a tool with:

>md
    Use @{lorem_ipsum} to generate a random paragraph
<

will yield:

>md
    Use the lorem_ipsum tool to generate a random paragraph
<


CMD_RUNNER

The `@cmd_runner` tool enables an LLM to execute commands on your machine,
subject to your authorization. For example:

>md
    Can you use @{cmd_runner} to run my test suite with `pytest`?
<

>md
    Use @{cmd_runner} to install any missing libraries in my project
<

Some commands do not write any data to stdout
<https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)> which
means the plugin can’t pass the output of the execution to the LLM. When this
occurs, the tool will instead share the exit code.

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 |codecompanion-extending-agentic-workflows| to hook
into.

**Options:** - `require_approval_before` require approval before running a
command? (Default: true)


CREATE_FILE


  [!NOTE] By default, this tool requires user approval before it can be executed
Create a file within the current working directory:

>md
    Can you create some test fixtures using @{create_file}?
<

**Options:** - `require_approval_before` require approval before creating a
file? (Default: true)


DELETE_FILE


  [!NOTE] By default, this tool requires user approval before it can be executed
Delete a file within the current working directory:

>md
    Can you use @{delete_file} to delete the quotes.lua file?
<

**Options:** - `require_approval_before` require approval before deleting a
file? (Default: true)


FETCH_WEBPAGE

This tools enables an LLM to fetch the content from a specific webpage. It will
return the text in a text format, depending on which adapter you’ve
configured for the tool.

>md
    Use @{fetch_webpage} to tell me what the latest version on neovim.io is
<

**Options:** - `adapter` The adapter used to fetch, process and format the
webpage’s content (Default: `jina`)


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.

>md
    Use @{file_search} 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 @{get_changed_files} 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] This tool requires ripgrep <https://github.com/BurntSushi/ripgrep>
  to be installed
This tool enables an LLM to search for text, within files, in the current
working directory. For every match, the output (`{filename}:{line number}
{relative filepath}`) will be shared with the LLM:

>md
    Use @{grep_search} 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] By default, when editing files, this tool requires user approval before
  it can be executed
This tool can edit buffers and files for code changes from an LLM:

>md
    Use @{insert_edit_into_file} to refactor the code in #buffer
<

>md
    Can you apply the suggested changes to the buffer with @{insert_edit_into_file}?
<

**Options:** - `patching_algorithm` (string|table|function) The algorithm to
use to determine how to edit files and buffers -
`require_approval_before.buffer` (boolean) Require approval before editng a
buffer? (Default: false) - `require_approval_before.file` (boolean) Require
approval before editng a file? (Default: true) - `require_confirmation_after`
(boolean) require confirmation after the execution and before moving on in the
chat buffer? (Default: true)


LIST_CODE_USAGES


  [!NOTE] This tool requires LSP to be configured and active for optimal results
This tool enables an LLM to find all usages of a symbol (function, class,
method, variable, etc.) throughout your codebase. It leverages LSP for accurate
results and falls back to grep for broader text searching.

The tool provides comprehensive information about symbols including:

- **References**: All places where the symbol is used
- **Definitions**: Where the symbol is defined
- **Implementations**: Concrete implementations of interfaces/abstract methods
- **Declarations**: Forward declarations
- **Type Definitions**: Type aliases and definitions
- **Documentation**: Hover documentation when available

>md
    Use @{list_code_usages} to find all usages of the `create_file` function
<

>md
    Can you use @{list_code_usages} to show me how the `Tools` class is implemented and used?
<


MEMORY


  [!IMPORTANT] For security, all memory operations are restricted to the
  `/memories` directory
The memory tool enables LLMs to store and retrieve information across
conversations through a memory file directory (`/memories`).

If you’re using the `Anthropic` adapter, then this tool will act as its
client implementation. Please refer to their documentation
<https://docs.claude.com/en/docs/agents-and-tools/tool-use/memory-tool> for
more information.

The tool has the following commands that an LLM can use:

- **view** - Lists the contents in the `/memories` directory or displays file content with optional line ranges
- **create** - Creates a new file or overwrites an existing file with specified content
- **str_replace** - Replaces the first exact match of text in a file with new text
- **insert** - Inserts text at a specific line number in a file
- **delete** - Removes a file or recursively deletes a directory and all its contents
- **rename** - Moves or renames a file or directory to a new path

To use the tool:

>md
    Use @{memory} to carry on our conversation about streamlining my dotfiles
<


NEXT_EDIT_SUGGESTION

Inspired by Copilot Next Edit Suggestion
<https://code.visualstudio.com/blogs/2025/02/12/next-edit-suggestions>, the
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.

**Options:** - `jump_action` (string|function) Determines how a jump to the
next edit is made (Default: `tabnew`)


READ_FILE

This tool can read the contents of a specific file in the current working
directory. This can be useful for an LLM to gain wider context of files that
haven’t been shared with it.


WEB_SEARCH

This tool enables an LLM to search the web for a specific query, enabling it to
receive up to date information:

>md
    Use @{web_search} to find the latest version of Neovim?
<

>md
    Use @{web_search} to search neovim.io and explain how I can configure a new language server
<

Currently, the tool uses tavily <https://www.tavily.com> and you’ll need to
ensure that an API key has been set accordingly, as per the adapter
<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/adapters/tavily.lua>.


TOOL GROUPS ~

Tool Groups are a convenient way to combine multiple built-in tools together in
the chat buffer. CodeCompanion comes with two built-in ones,
`@{full_stack_dev}` and `@{files}`.

When you include a tool group in the chat, 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. If you want to show
all tools as context items in the chat buffer, set the `opts.collapse_tools`
option to `false` on the group itself.

Groups may also have a `prompt` field which is used to replace their reference
in a message in the chat buffer. This ensures that the LLM receives a useful
message rather than the name of the tools themselves.

For example, the following prompt:

>md
    @{full_stack_dev}. Can you create Snake for me, in Python?
<

Is replaced by:

>
    I'm giving you access to the cmd_runner, create_file, file_search, get_changed_files, grep_search, insert_edit_into_file, list_code_usages, read_file tools to help you perform coding tasks. Can you create Snake for me, in Python?
<

This is because the `@{full_stack_dev}` group has the following prompt set in
the config:

>lua
    groups = {
      ["full_stack_dev"] = {
        -- ...
        prompt = "I'm giving you access to the ${tools} to help you perform coding tasks",
        -- ...
      }
    },
<


FULL_STACK_DEV

The `@{full_stack_dev}` is a collection of tools which have been curated to
enable an LLM to create applications and understand and refactor code bases.

It contains the following tools:

- |codecompanion-usage-chat-buffer-tools-cmd-runner|
- |codecompanion-usage-chat-buffer-tools-create-file|
- |codecompanion-usage-chat-buffer-tools-file-search|
- |codecompanion-usage-chat-buffer-tools-get-changed-files|
- |codecompanion-usage-chat-buffer-tools-grep-search|
- |codecompanion-usage-chat-buffer-tools-insert-edit-into-file|
- |codecompanion-usage-chat-buffer-tools-list-code-usages|
- |codecompanion-usage-chat-buffer-tools-read-file|

You can use it with:

>md
    @{full_stack_dev}. Can we create a todo list in Vue.js?
<


FILES

The `@{files}` tool is a collection of tools that allows an LLM to carry out
file operations in your current working directory. It contains the following
files:

- |codecompanion-usage-chat-buffer-tools-create-file|
- |codecompanion-usage-chat-buffer-tools-file-search|
- |codecompanion-usage-chat-buffer-tools-get-changed-files|
- |codecompanion-usage-chat-buffer-tools-grep-search|
- |codecompanion-usage-chat-buffer-tools-insert-edit-into-file|
- |codecompanion-usage-chat-buffer-tools-read-file|

You can use it with:

>md
    @{files}. Can you scaffold out the folder structure for a python package?
<


ADAPTER TOOLS ~


  [!NOTE] Adapter tools are configured via the `available_tools` dictionary on
  the adapter itself
Prior to v17.30.0
<https://github.com/olimorris/codecompanion.nvim/releases/tag/v17.30.0>, tool
use in CodeCompanion was only possible with the built-in tools. However, that
release unlocked `adapter` tools. That is, tools that are owned by LLM
providers such as Anthropic
<https://docs.claude.com/en/docs/agents-and-tools/tool-use/computer-use-tool>
and OpenAI
<https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses>.
This allows for remote tool execution of common tasks such as web searching and
computer use.

From a UX perspective, there is no difference in using the built-in and adapter
tools. However, please note that an adapter tool takes precedence over a
built-in tool in the event of a name clash.


ANTHROPIC

In the `anthropic` adapter, the following tools are available:

- `code_execution` - The code execution tool allows Claude to run Bash commands and manipulate files, including writing code, in a secure, sandboxed environment
- `memory` - Enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions, allowing it to build knowledge over time without keeping everything in the context window
- `web_fetch` - The web fetch tool allows Claude to retrieve full content from specified web pages and PDF documents.
- `web_search` - The web search tool gives Claude direct access to real-time web content, allowing it to answer questions with up-to-date information beyond its knowledge cutoff


OPENAI

In the `openai_responses` adapter, the following tools are available:

- `web_search` - Allow models to search the web for the latest information before generating a response.


SECURITY ~

CodeCompanion takes security very seriously, especially in a world of agentic
code development. To that end, every effort is made to ensure that LLMs are
only given the information that they need to execute a tool successfully.
CodeCompanion will endeavour to make sure that the full disk path to your
current working directory (cwd) in Neovim is never shared. The impact of this
is that the LLM can only work within the cwd when executing tools but will
minimize actions that are hard to recover from
<https://www.businessinsider.com/replit-ceo-apologizes-ai-coding-tool-delete-company-database-2025-7>.


APPROVALS


  [!NOTE] This applies to CodeCompanion’s built-in tools only. ACP agents have
  their own tools and approval systems.
In order to give developers the confidence to use tools, CodeCompanion has
implemented a comprehensive approval system for it’s built-in tools.

CodeCompanion segregates tool approvals by chat buffer and by tool. This means
that if you approve a tool in one chat buffer, it is `not` approved for use
anywhere else. Similarly, if you approve a tool once, you’ll be prompted to
approve it again next time it’s executed.

When prompted, the user has four options available to them:

- **Allow always** - Always allow this tool/cmd to be executed without further prompts
- **Allow once** - Allow this tool/cmd to be executed this one time
- **Reject** - Reject the execution of this tool/cmd and provide a reason
- **Cancel** - Cancel this tool execution and all other pending tool executions

Certain tools with potentially destructive capabilities have an additional
layer of protection. Instead of being approved at a tool level, these are
approved at a command level. Taking the `cmd_runner` tool as an example. If you
approve an agent to always run `make format`, if it tries to run `make test`,
you’ll be prompted to approve that command specifically.

Approvals can be reset for the given chat buffer by using the `gtx` keymap.


YOLO MODE

To bypass the approval system, you can use `gty` in the chat buffer to enable
YOLO mode. This will automatically approve all tool executions without
prompting the user. However, note that some tools such as `cmd_runner` and
`delete_file` are excluded from this.


COMPATIBILITY ~

Below is the tool use status of various adapters and models in CodeCompanion:

  ------------------------------------------------------------------------
  Adapter        Model            Supported   Notes
  -------------- -------------- ------------- ----------------------------
  Anthropic                                   Dependent on the model

  Azure OpenAI                                Dependent on the model

  Copilot                                     Dependent on the model

  DeepSeek                                    Dependent on the model

  Gemini                                      Dependent on the model

  GitHub Models  All                          Not supported yet

  Huggingface    All                          Not supported yet

  Mistral                                     Dependent on the model

  Novita                                      Dependent on the model

  Ollama         Tested with                  Dependent on the model
                 Qwen3                        

  OpenAI                                      Dependent on the model

  xAI            All                          Not supported yet
  ------------------------------------------------------------------------

  [!IMPORTANT] When using Mistral, you will need to set
  `interactions.chat.tools.opts.auto_submit_errors` to `true`. See #2278
  <https://github.com/olimorris/codecompanion.nvim/pull/2278> for more
  information.

SLASH COMMANDS                            *codecompanion-usage-slash-commands*

Slash Commands enable you to quickly add context to the chat buffer. They are
comprised of values present in the `interactions.chat.slash_commands` table
alongside the `prompt_library` table where individual prompts have
`opts.is_slash_cmd = true`.


/BUFFER ~


  [!NOTE] As of v16.2.0
  <https://github.com/olimorris/codecompanion.nvim/releases/tag/v16.2.0>, buffers
  are now watched by default
The `buffer` slash command enables you to add the contents of any open buffers
in Neovim to the chat buffer. The command has native, `Telescope`, `mini.pick`,
`fzf.lua` and `snacks.nvim` providers available. Also, multiple buffers can be
selected and added to the chat buffer as per the video above.


/COMMAND ~

The `command` slash command is specific to
|codecompanion-configuration-adapters-acp| adapters and allows users to switch
between different adapter commands. For instance, some ACP adapters may allow
you to run the agent command with a specific flag. Be mindful that switching
commands is destructive and essentially resets the chat buffer for the purposes
of a conversation with an agent.


/COMPACT ~

The `compact` slash command, based on Claude Code’s
<https://code.claude.com/docs/en/slash-commands#built-in-slash-commands>
corresponding feature, clears the chat buffer’s message history whilst
preserving a summary, in context.

System prompts, rules and file/buffer shares will be preserved but all user,
assistant and tool messages will be removed. The summary is generated by
prompting the same LLM to summarize the chat history into a concise format.


/FETCH ~


  [!TIP] To better understand a Neovim plugin, send its `config.lua` to your LLM
  via the `fetch` command alongside a prompt
The `fetch` slash command allows you to add the contents of a URL to the chat
buffer. By default, the plugin uses the awesome and powerful jina.ai
<https://jina.ai> to parse the page’s content and convert it into plain text.
For convenience, the slash command will cache the output to disk and prompt the
user if they wish to restore from the cache, should they look to fetch the same
URL.


/FILE ~

The `file` slash command allows you to add the contents of a file in the
current working directory to the chat buffer. The command has native,
`Telescope`, `mini.pick`, `fzf.lua` and `snacks.nvim` providers available.
Also, multiple files can be selected and added to the chat buffer:

- Select a single file: `⏎ enter`
- Select multiple files: `⇥ tab`

Please note that these mappings may be different depending on your provider.


/HELP ~

The `help` slash command allows you to add content from a vim help file
(|helpfile|), to the chat buffer, by searching for help tags. Currently this is
only available for `Telescope`, `mini.pick`, `fzf_lua` and `snacks.nvim`
providers. By default, the slash command will prompt you to trim a help file
that is over 1,000 lines in length.


/IMAGE ~

The `image` slash command allows you to add images into a chat buffer via
remote URLs and through your file system. In the config for the slash command,
you can specify a group of directories (with `opts.dirs`) that the image picker
will always search in, alongside the current working directory. Currently the
image picker is only available with `snacks.nvim` and the `vim.ui.select`.


/RULES ~

The `rules` slash command allows you to add
|codecompanion-usage-chat-buffer-rules| groups to the chat buffer.


/MODE ~

The `mode` slash command is specific to
|codecompanion-configuration-adapters-acp| adapters and allows users to switch
between different agent operating modes, as per the protocol
<https://agentclientprotocol.com/protocol/session-modes> docs.


/NOW ~

The `now` slash command simply inserts the current datetime stamp into the chat
buffer.


/QUICKFIX ~

The `quickfix` slash command adds entries from the Neovim quickfix list to the
chat buffer.

- For search patterns or file entries, the whole file is shared.
- For diagnostics, the context of the function/method/class is shared if possible; otherwise, 10 lines around the diagnostic are included.


/SYMBOLS ~


  [!NOTE] If a filetype isn’t supported please consider making a PR to add the
  corresponding Tree-sitter queries from aerial.nvim
  <https://github.com/stevearc/aerial.nvim>
The `symbols` slash command uses Tree-sitter to create a symbolic outline of a
file to share with the LLM. This can be a useful way to minimize token
consumption whilst sharing the basic outline of a file. The plugin utilizes the
amazing work from **aerial.nvim** by using their Tree-sitter symbol queries as
the basis. The list of filetypes that the plugin currently supports can be
found here <https://github.com/olimorris/codecompanion.nvim/tree/main/queries>.

The command has native, `Telescope`, `mini.pick`, `fzf.lua` and `snacks.nvim`
providers available. Also, multiple symbols can be selected and added to the
chat buffer.


/TERMINAL ~

The `terminal` slash command shares the latest output from the last terminal
buffer with the chat buffer. This can be useful for sharing the outputs of test
runs with your LLM.


VARIABLES                                      *codecompanion-usage-variables*

Variables allow you to dynamically insert Neovim context into your chat
messages using the `#{variable_name}` syntax. They’re processed when you send
your message to the LLM, automatically including relevant content like buffer
contents, LSP diagnostics, or your current viewport. Type `#` in the chat
buffer to see available variables through code completion, or type them
manually.

Custom variables can be shared in the chat buffer by adding them to the
`interactions.chat.variables` table in your configuration.


BASIC USAGE ~

Variables use the `#{variable_name}` syntax to dynamically insert content into
your chat. For example `#{buffer}`. Variables are processed when you send your
message to the LLM.


#BUFFER ~


  [!IMPORTANT] By default, CodeCompanion automatically applies the `{diff}`
  parameter to all buffers
The `#{buffer}` variable shares buffer contents with the LLM. It has two
special parameters which control how content is shared, or `synced`, with the
LLM, on each turn:


BASIC USAGE

- `#{buffer}` - Shares the current buffer (last one you were in)


TARGET SPECIFIC BUFFERS

- `#{buffer:init.lua}` - Shares a specific file by name
- `#{buffer:src/main.rs}` - Shares a file by relative path
- `#{buffer:utils}` - Shares a file containing "utils" in the path


WITH PARAMETERS

**{all}** - Sends all of the buffer content to the LLM whenever the buffer
changes. Use this when you want the LLM to always have the complete, up-to-date
file context.

**{diff}** - Sends only the changed portions of the buffer to the LLM. Use this
for large files where you only want to share incremental changes to reduce
token usage.

Can be used in combination with targeting a specific buffer:

- `#{buffer}{all}` - Sends entire buffer on any change
- `#{buffer}{diff}` - Sends only changed portions of the buffer
- `#{buffer:config.lua}{all}` - Combines targeting with parameters


MULTIPLE BUFFERS

>
    Compare #{buffer:old_file.js} with #{buffer:new_file.js} and explain the differences.
<


  **Note:** For selecting multiple buffers with more control, use the `/buffer`
  slash command.

#LSP ~


  [!TIP] The |codecompanion-usage-action-palette| has a pre-built prompt which
  asks an LLM to explain LSP diagnostics in a visual selection
The `lsp` variable shares any information from the LSP servers that active in
the current buffer. This can serve as useful context should you wish to
troubleshoot any errors with an LLM.


#VIEWPORT ~

The `viewport` variable shares with the LLM, exactly what you see on your
screen at the point a response is sent (excluding the chat buffer of course).


EVENTS / HOOKS                            *codecompanion-usage-events-/-hooks*

In order to enable a tighter integration between CodeCompanion and your Neovim
config, the plugin fires events at various points during its lifecycle.


LIST OF EVENTS ~

The events that are fired from within the plugin are:

- `CodeCompanionChatACPModeChanged` - Fired after the ACP mode has been changed in the chat
- `CodeCompanionChatCreated` - Fired after a chat has been created for the first time
- `CodeCompanionChatOpened` - Fired after a chat has been opened
- `CodeCompanionChatHidden` - Fired after a chat has been hidden
- `CodeCompanionChatClosed` - Fired after a chat has been permanently closed
- `CodeCompanionChatSubmitted` - Fired after a chat has been submitted
- `CodeCompanionChatDone` - Fired after a chat has received the response
- `CodeCompanionChatStopped` - Fired after a chat has been stopped
- `CodeCompanionChatCleared` - Fired after a chat has been cleared
- `CodeCompanionChatAdapter` - Fired after the adapter has been set in the chat
- `CodeCompanionChatModel` - Fired after the model has been set in the chat
- `CodeCompanionContextChanged` - Fired when the context that a chat buffer follows, changes
- `CodeCompanionToolsStarted` - Fired when the tool system has been initiated
- `CodeCompanionToolsFinished` - Fired when the tool system has finished running all tools
- `CodeCompanionToolAdded` - Fired when a tool has been added to a chat
- `CodeCompanionToolStarted` - Fired when a tool has started executing
- `CodeCompanionToolFinished` - Fired when a tool has finished executing
- `CodeCompanionInlineStarted` - Fired at the start of the Inline interaction
- `CodeCompanionInlineFinished` - Fired at the end of the Inline interaction
- `CodeCompanionRequestStarted` - Fired at the start of any API request
- `CodeCompanionRequestStreaming` - Fired at the start of a streaming API request
- `CodeCompanionRequestFinished` - Fired at the end of any API request
- `CodeCompanionDiffAttached` - Fired when in Diff mode
- `CodeCompanionDiffDetached` - Fired when exiting Diff mode
- `CodeCompanionDiffAccepted` - Fired when a user accepts a change
- `CodeCompanionDiffRejected` - Fired when a user rejects a change

There are also events that can be utilized to trigger commands from within the
plugin:

- `CodeCompanionChatRefreshCache` - Used to refresh conditional elements in the chat buffer


EVENT DATA ~

Each event also comes with a data payload. For example, with
`CodeCompanionRequestStarted`:

>lua
    {
      buf = 10,
      data = {
        adapter = {
          formatted_name = "Copilot",
          model = "o3-mini-2025-01-31",
          name = "copilot"
        },
        bufnr = 10,
        id = 6107753,
        interaction = "chat"
      },
      event = "User",
      file = "CodeCompanionRequestStarted",
      group = 14,
      id = 30,
      match = "CodeCompanionRequestStarted"
    }
<

And the `CodeCompanionRequestFinished` also has a `data.status` value.


CONSUMING AN EVENT ~

Events can be hooked into as follows:

>lua
    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,
    })
<

You can trigger an event with:

>lua
    vim.api.nvim_exec_autocmds("User", {
      pattern = "CodeCompanionChatRefreshCache",
    })
<


INLINE ASSISTANT                        *codecompanion-usage-inline-assistant*

As per the |codecompanion-getting-started-inline-assistant| guide, the inline
assistant enables you to code directly into a Neovim buffer. Simply run
`:CodeCompanion <your prompt>`, or make a visual selection to send that as
context to the LLM alongside your prompt.

For convenience, you can call prompts from the
|codecompanion-configuration-prompt-library| via the assistant. For example,
`:'<,'>CodeCompanion /tests` would ask the LLM to create some unit tests from
the selected text.


ADAPTERS ~

You can specify a different adapter to that in the configuration
(`interactions.inline.adapter`) when sending an inline prompt. Simply include
the adapter via `adapter=*`. For example `:<','>CodeCompanion adapter=deepseek
can you refactor this?`. This approach can also be combined with variables.


CLASSIFICATION ~

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 uses 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
- `before` - to be added in the current buffer before the cursor position
- `new` - be placed in a new buffer
- `chat` - be placed in a chat buffer


DIFF MODE ~

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

- `gda` - Accept an inline edit
- `gdr` - Reject an inline edit

These keymaps can also be changed in your config via the
`interactions.inline.keymaps` table.


VARIABLES ~


  [!TIP] To ensure the LLM has enough context to complete a complex ask, it’s
  recommended to use the `buffer` variable
The inline assistant allows you to send context alongside your prompt via the
notion of variables:

- `buffer` - shares the contents of the current buffer
- `chat` - shares the LLM’s messages from the last chat buffer
- `clipboard` - shares the data on your clipboard with the LLM

Simply include them in your prompt. For example `:CodeCompanion #{buffer} add a
new method to this file`. Multiple variables can be sent as part of the same
prompt. You can even add your own custom variables as per the
|codecompanion-configuration-inline-assistant-variables|.

You can also have multiple variables a part of a prompt, for example:
`:CodeCompanion #{buffer} #{clipboard} analyze this code`.


PROMPT LIBRARY                            *codecompanion-usage-prompt-library*

There are numerous ways that the prompts defined in your prompt library can be
used in CodeCompanion. You can invoke them via keymaps, the Action Palette, or
slash commands in the chat buffer.


KEYMAPS ~

You can assign prompts from the prompt library to a keymap via the `prompt`
function:

>lua
    vim.keymap.set("n", "<LocalLeader>d", function()
      require("codecompanion").prompt("docs")
    end, { noremap = true, silent = true })
<

Where `docs` is the `alias` of the prompt.


USER INTERFACE                            *codecompanion-usage-user-interface*

CodeCompanion aims to keep any changes to the user’s UI to a minimum.
Aesthetics, especially in Neovim, are highly subjective. So whilst it won’t
set much by default, it does endeavour to allow users to hook into the plugin
and customize the UI to their liking via |codecompanion-usage-events|.


METADATA

CodeCompanion exposes a global dictionary, `_G.codecompanion_chat_metadata`
which users can leverage throughout their configuration. Using the chat
buffer’s buffer number as the key, the dictionary contains:

- `adapter` - The `name` and `model` of the chat buffer’s current adapter
- `context_items` - The number of context items current in the chat buffer
- `cycles` - The number of cycles (User->LLM->User) that have taken place in the chat buffer
- `id` - The ID of the chat buffer
- `tokens` - The running total of tokens for the chat buffer
- `tools` - The number of tools in the chat buffer

You can also leverage `_G.codecompanion_current_context` to fetch the number of
the buffer which the `#{buffer}` variable points at.

The video at the top of this page shows how the author has incorporated the
metadata into their statusline.


HIGHLIGHT GROUPS

The plugin sets the following highlight groups during setup:

- `CodeCompanionChatInfo` - Information messages in the chat buffer
- `CodeCompanionChatInfoBanner` - Banner showing useful information in the chat buffer
- `CodeCompanionChatError` - Error messages in the chat buffer
- `CodeCompanionChatWarn` - Warning messages in the chat buffer
- `CodeCompanionChatSubtext` - Messages that appear under the information, error or warning messages in the chat buffer
- `CodeCompanionChatFold` - For any folds in the chat buffer (not including tool output)
- `CodeCompanionChatHeader` - The headers in the chat buffer
- `CodeCompanionChatSeparator` - Separator between headings in the chat buffer
- `CodeCompanionSuperDiffDirectory` - Highlight directories in a Super Diff buffer
- `CodeCompanionSuperDiffFilename` - Highlight filenames in a Super Diff buffer
- `CodeCompanionChatTokens` - Virtual text in the chat buffer showing the token count
- `CodeCompanionChatTool` - Tools in the chat buffer
- `CodeCompanionChatToolGroups` - Tool groups in the chat buffer
- `CodeCompanionChatVariable` - Variables in the chat buffer
- `CodeCompanionVirtualText` - All other virtual text in the plugin


WORKFLOWS                                      *codecompanion-usage-workflows*

Workflows can only be initiated from the |codecompanion-usage-action-palette|.
This is because they are a complex Lua table structure which needs to be
processed and added to a new chat buffer. Simply open up the Action Palette and
select your desired workflow.

You can create your own workflows by following the
|codecompanion-configuration-prompt-library-workflows| configuration guide and
the |codecompanion-extending-agentic-workflows| guide.


==============================================================================
7. Extending                                         *codecompanion-extending*


EXTENDING WITH ADAPTERS      *codecompanion-extending-extending-with-adapters*


  [!TIP] Does your LLM state that it is "OpenAI Compatible"? If so, good news,
  you can extend from the `openai` adapter or use the `openai_compatible` one.
  Something we did with the xAI
  <https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/adapters/http/xai.lua>
  adapter
In CodeCompanion, adapters are interfaces that act as a bridge between the
plugin’s functionality and an LLM. All adapters must follow the interface,
below.

This guide is intended to serve as a reference for anyone who wishes to
contribute an adapter to the plugin or understand the inner workings of
existing adapters.

The plugin’s in-built adapters can be found here
<https://github.com/olimorris/codecompanion.nvim/tree/main/lua/codecompanion/adapters>.


THE INTERFACE ~

Let’s take a look at the interface of an adapter as per the `adapter.lua`
file:

>lua
    ---@class CodeCompanion.HTTPAdapter
    ---@field name string The name of the adapter e.g. "openai"
    ---@field formatted_name string The formatted name of the adapter e.g. "OpenAI"
    ---@field roles table The mapping of roles in the config to the LLM's defined roles
    ---@field url string The URL of the LLM to connect to
    ---@field env? table Environment variables which can be referenced in the parameters
    ---@field env_replaced? table Replacement of environment variables with their actual values
    ---@field headers table The headers to pass to the request
    ---@field parameters table The parameters to pass to the request
    ---@field body table Additional body parameters to pass to the request
    ---@field raw? table Any additional curl arguments to pass to the request
    ---@field opts? table Additional options for the adapter
    ---@field handlers CodeCompanion.HTTPAdapter.Handlers Functions which link the output from the request to CodeCompanion
    ---@field schema table Set of parameters for the LLM that the user can customise in the chat buffer
<

Everything up to the handlers should be self-explanatory. We’re simply
providing details of the LLM’s API to the curl library and executing the
request. The real intelligence of the adapter comes from the handlers table
which is a set of functions which bridge the functionality of the plugin to the
LLM.


HANDLER STRUCTURE ~

As of v17.27.0, handlers are organized into a nested structure that provides
clear separation of concerns:

>lua
    handlers = {
      -- Lifecycle hooks (side effects and initialization)
      lifecycle = {
        setup = function(self) end,      -- Called before request is sent
        on_exit = function(self, data) end,  -- Called after request completes
        teardown = function(self) end,   -- Called last, after on_exit
      },
    
      -- Request builders (pure transformations)
      request = {
        build_parameters = function(self, params, messages) end,  -- Build request parameters
        build_messages = function(self, messages) end,            -- Format messages for LLM
        build_tools = function(self, tools) end,                  -- Transform tool schemas
        build_reasoning = function(self, messages) end,           -- Build reasoning parameters
        build_body = function(self, data) end,                    -- Set additional body parameters
      },
    
      -- Response parsers (pure transformations)
      response = {
        parse_chat = function(self, data, tools) end,       -- Parse chat response
        parse_inline = function(self, data, context) end,   -- Parse inline response
        parse_tokens = function(self, data) end,            -- Extract token count
      },
    
      -- Tool handlers (grouped functionality)
      tools = {
        format_calls = function(self, tools) end,                          -- Format tool calls for request
        format_response = function(self, tool_call, output) end,           -- Format tool response for LLM
      },
    }
<


  [!NOTE] **Backwards Compatibility**: The old flat handler structure is still
  supported. Adapters using the old format (e.g., `form_parameters`,
  `form_messages`, `chat_output`) will continue to work. The plugin automatically
  detects and maps old handler names to the new structure.

ENVIRONMENT VARIABLES ~

When building an adapter, you’ll need to inject variables into different
parts of the adapter class. If we take the Google Gemini
<https://github.com/google-gemini/cookbook/blob/main/quickstarts/rest/Streaming_REST.ipynb>
endpoint as an example, we need to inject the model and API key variables into
the URL of
`https://generativelanguage.googleapis.com/v1beta/models/${model}:streamGenerateContent?alt=sse&key=${api_key}`.
Whereas with OpenAI
<https://platform.openai.com/docs/api-reference/authentication>, we need an
`Authorization` http header to contain our API key.

Let’s take a look at the `env` table from the Google Gemini adapter that
comes with the plugin:

>lua
    url = "https://generativelanguage.googleapis.com/v1beta/models/${model}:streamGenerateContent?alt=sse&key=${api_key}",
    env = {
      api_key = "GEMINI_API_KEY",
      model = "schema.model.default",
    },
<

The key `api_key` represents the name of the variable which can be injected in
the adapter via the `${}` notation, and the value can represent one of:

- A command to execute on the user’s system
- An environment variable from the user’s system
- A function to be executed at runtime
- A path to an item in the adapter’s schema table
- A plain text value


  [!NOTE] Environment variables can be injected into the `url`, `headers` and
  `parameters` fields of the adapter class at runtime
**Commands**

An environment variable can be obtained from running a command on a user’s
system. This can be accomplished by prefixing the value with `cmd:` such as:

>lua
    env = {
      api_key = "cmd:op read op://personal/Gemini_API/credential --no-newline",
    },
<

In this example, we’re running the `op read` command to get a credential from
1Password.

**Environment Variable**

An environment variable can also be obtained by using lua’s `os.getenv`
function. Simply enter the name of the variable as a string such as:

>lua
    env = {
      api_key = "GEMINI_API_KEY",
    },
<

**Functions**

An environment variable can also be resolved via the use of a function such as:

>lua
    env = {
      api_key = function()
        return os.getenv("GEMINI_API_KEY")
      end,
    },
<

**Schema Values**

An environment variable can also be resolved by entering the path to a value in
a table on the adapter class. For example:

>lua
    env = {
      model = "schema.model.default",
    },
<

In this example, we’re getting the value of a user’s chosen model from the
schema table on the adapter.


HANDLERS ~

The handlers table is organized into four main categories:


LIFECYCLE HANDLERS

These handlers manage side effects and initialization:

- `lifecycle.setup` - Called before the request is sent and before environment variables are set. Must return a boolean to indicate success
- `lifecycle.on_exit` - Called after the request completes. Useful for handling errors
- `lifecycle.teardown` - Called last, after `on_exit`


REQUEST HANDLERS

These handlers transform data for the LLM request:

- `request.build_parameters` - Set the parameters of the request
- `request.build_messages` - Format the messages array for the LLM
- `request.build_tools` - Transform tool schemas for the LLM
- `request.build_reasoning` - Build reasoning parameters (for models that support it)
- `request.build_body` - Set additional body parameters


RESPONSE HANDLERS

These handlers parse LLM responses:

- `response.parse_chat` - Format chat output for the chat buffer
- `response.parse_inline` - Format output for inline insertion
- `response.parse_tokens` - Extract token count from the response
- `response.parse_meta` - Process non-standard fields in the response (currently only supported by OpenAI-based adapters)


TOOL HANDLERS

These handlers manage tool/function calling:

- `tools.format_calls` - Format tool calls for inclusion in the request
- `tools.format_response` - Format tool responses for the LLM


  [!TIP] All of the adapters in the plugin come with their own tests. These serve
  as a great reference to understand how they’re working with the output of the
  API

OPENAI€�S API OUTPUT

If we reference the OpenAI documentation
<https://platform.openai.com/docs/guides/text-generation/chat-completions-api>
we can see that they require the messages to be in an array which consists of
`role` and `content`:

>sh
    curl https://api.openai.com/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $OPENAI_API_KEY" \
      -d '{
        "model": "gpt-4-0125-preview",
        "messages": [
          {
            "role": "user",
            "content": "Explain Ruby in two words"
          }
        ]
      }'
<


CHAT BUFFER OUTPUT

The chat buffer, which is structured like:

>markdown
    ## Me
    
    Explain Ruby in two words
<

results in the following output:

>lua
    {
      {
        role = "user",
        content = "Explain Ruby in two words"
      }
    }
<


REQUEST.BUILD_MESSAGES

The chat buffer’s output is passed to this handler in the form of the
`messages` parameter. So we can just output this as part of a messages table:

>lua
    handlers = {
      request = {
        build_messages = function(self, messages)
          return { messages = messages }
        end,
      },
    }
<


RESPONSE.PARSE_CHAT

Now let’s look at how we format the output from OpenAI. Running that request
results in:

>txt
    data: {"id":"chatcmpl-90DdmqMKOKpqFemxX0OhTVdH042gu","object":"chat.completion.chunk","created":1709839462,"model":"gpt-4-0125-preview","system_fingerprint":"fp_70b2088885","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}
<

>txt
    data: {"id":"chatcmpl-90DdmqMKOKpqFemxX0OhTVdH042gu","object":"chat.completion.chunk","created":1709839462,"model":"gpt-4-0125-preview","system_fingerprint":"fp_70b2088885","choices":[{"index":0,"delta":{"content":"Programming"},"logprobs":null,"finish_reason":null}]}
<

>txt
    data: {"id":"chatcmpl-90DdmqMKOKpqFemxX0OhTVdH042gu","object":"chat.completion.chunk","created":1709839462,"model":"gpt-4-0125-preview","system_fingerprint":"fp_70b2088885","choices":[{"index":0,"delta":{"content":" language"},"logprobs":null,"finish_reason":null}]},
<

>txt
    data: [DONE]
<


  [!IMPORTANT] Note that the `parse_chat` handler requires a table containing
  `status` and `output` to be returned.
Remember that we’re streaming from the API so the request comes through in
batches. Thankfully the `http.lua` file handles this and we just have to handle
formatting the output into the chat buffer.

The first thing to note with streaming endpoints is that they don’t return
valid JSON. In this case, the output is prefixed with `data:`. CodeCompanion
comes with some handy utility functions to work with this:

>lua
    -- Put this at the top of your adapter
    local utils = require("codecompanion.utils.adapters")
    
    handlers = {
      response = {
        parse_chat = function(self, data)
          data = utils.clean_streamed_data(data)
        end,
      },
    }
<


  [!IMPORTANT] The data passed to the `parse_chat` handler is the response from
  OpenAI
We can then decode the JSON using native vim functions:

>lua
    handlers = {
      response = {
        parse_chat = function(self, data)
          data = utils.clean_streamed_data(data)
          local ok, json = pcall(vim.json.decode, data, { luanil = { object = true } })
        end,
      },
    }
<

We want to include any nil values so we pass in `luanil = { object = true }`.

Examining the output of the API, we see that the streamed data is stored in a
`choices[1].delta` table. That’s easy to pickup:

>lua
    handlers = {
      response = {
        parse_chat = function(self, data)
          ---
          local delta = json.choices[1].delta
        end,
      },
    }
<

and we can then access the new streamed data that we want to write into the
chat buffer, with:

>lua
    handlers = {
      response = {
        parse_chat = function(self, data)
          local output = {}
          ---
          local delta = json.choices[1].delta
    
          if delta.content then
            output.content = delta.content
            output.role = delta.role or nil
          end
        end,
      },
    }
<

And then we can return the output in the following format:

>lua
    handlers = {
      response = {
        parse_chat = function(self, data)
          --
          return {
            status = "success",
            output = output,
          }
        end,
      },
    }
<

Now if we put it all together, and put some checks in place to make sure that
we have data in our response:

>lua
    handlers = {
      response = {
        parse_chat = function(self, data)
          local output = {}
    
          if data and data ~= "" then
            data = utils.clean_streamed_data(data)
            local ok, json = pcall(vim.json.decode, data, { luanil = { object = true } })
    
            local delta = json.choices[1].delta
    
            if delta.content then
              output.content = delta.content
              output.role = delta.role or nil
    
              return {
                status = "success",
                output = output,
              }
            end
          end
        end,
      },
    }
<


RESPONSE.PARSE_META

Some OpenAI-compatible API providers like deepseek, Gemini and OpenRouter
implement a superset of the standard specification, and provide reasoning
tokens/summaries within their response. The non-standard fields in the
`message` (non-streaming)
<https://platform.openai.com/docs/api-reference/chat/object#chat-object-choices-message>
or `delta` (streaming)
<https://platform.openai.com/docs/api-reference/chat-streaming/streaming#chat_streaming-streaming-choices-delta>
object are captured by the OpenAI adapter and can be used to extract the
reasoning.

For example, the DeepSeek API provides the reasoning tokens in the
`delta.reasoning_content` field. We can therefore use the following
`parse_meta` handler to extract the reasoning tokens and put them into the
appropriate output fields:

>lua
    handlers = {
      response = {
        ---@param self CodeCompanion.HTTPAdapter
        --- `data` is the output of the `parse_chat` handler
        ---@param data {status: string, output: {role: string?, content: string?}, extra: table}
        ---@return {status: string, output: {role: string?, content: string?, reasoning:{content: string?}?}}
        parse_meta = function(self, data)
          local extra = data.extra
          if extra.reasoning_content then
            -- codecompanion expect the reasoning tokens in this format
            data.output.reasoning = { content = extra.reasoning_content }
            -- so that codecompanion doesn't mistake this as a normal response with empty string as the content
            if data.output.content == "" then
              data.output.content = nil
            end
          end
          return data
        end
      }
    }
<

Notes:

1. You don’t always have to set `data.output.content` to `nil`. This is mostly intended for `streaming`, and you may encounter issues in non-stream mode if you do that.
2. It’s expected that the processed `data` table is returned at the end.
3. For adapters that are using the legacy flat handler formats, this handler should be named `handlers.parse_message_meta`. The function signature stays the same.


REQUEST.BUILD_PARAMETERS

For the purposes of the OpenAI adapter, no additional parameters need to be
created. So we just pass this through:

>lua
    handlers = {
      request = {
        build_parameters = function(self, params, messages)
          return params
        end,
      },
    }
<


RESPONSE.PARSE_INLINE

From a design perspective, the inline interaction is very similar to the chat
interaction. With the `parse_inline` handler we simply return the content we
wish to be streamed into the buffer.

In the case of OpenAI, once we’ve checked the data we have back from the LLM
and parsed it as JSON, we simply need to:

>lua
    ---Output the data from the API ready for inlining into the current buffer
    ---@param self CodeCompanion.HTTPAdapter
    ---@param data table The streamed JSON data from the API
    ---@param context table Useful context about the buffer to inline to
    ---@return string|table|nil
    handlers = {
      response = {
        parse_inline = function(self, data, context)
          -- Data cleansed, parsed and validated
          -- ..
          local content = json.choices[1].delta.content
          if content then
            return content
          end
        end,
      },
    }
<

The `parse_inline` handler also receives context from the buffer that initiated
the request.


LIFECYCLE.ON_EXIT

Handling errors from a streaming endpoint can be challenging. It’s
recommended that any errors are managed in the `on_exit` handler which is
initiated when the response has completed. In the case of OpenAI, if there is
an error, we’ll see a response back from the API like:

>sh
    data: {
    data:     "error": {
    data:         "message": "Incorrect API key provided: 1sk-F18b****************************************XdwS. You can find your API key at https://platform.openai.com/account/api-keys.",
    data:         "type": "invalid_request_error",
    data:         "param": null,
    data:         "code": "invalid_api_key"
    data:     }
    data: }
<

This would be challenging to parse! Thankfully we can leverage the `on_exit`
handler which receives the final payload, resembling:

>lua
    {
      body = '{\n    "error": {\n        "message": "Incorrect API key provided: 1sk-F18b****************************************XdwS. You can find your API key at https://platform.openai.com/account/api-keys.",\n        "type": "invalid_request_error",\n        "param": null,\n        "code": "invalid_api_key"\n    }\n}',
      exit = 0,
      headers = { "date: Thu, 03 Oct 2024 08:05:32 GMT" },
      status = 401
    }
<

and that’s much easier to work with:

>lua
    ---Function to run when the request has completed. Useful to catch errors
    ---@param self CodeCompanion.HTTPAdapter
    ---@param data table
    ---@return nil
    handlers = {
      lifecycle = {
        on_exit = function(self, data)
          if data.status >= 400 then
            log:error("Error: %s", data.body)
          end
        end,
      },
    }
<

The `log:error` call ensures that any errors are logged to the logfile as well
as displayed to the user in Neovim. It’s also important to reference that the
`parse_chat` and `parse_inline` handlers need to be able to ignore any errors
from the API and let `on_exit` handle them.


LIFECYCLE.SETUP AND LIFECYCLE.TEARDOWN

The `setup` handler will execute before the request is sent to the LLM’s
endpoint and before the environment variables have been set. This is leveraged
in the Copilot adapter to obtain the token before it’s resolved as part of
the environment variables table. The `setup` handler **must** return a boolean
value so the `http.lua` file can determine whether to proceed with the request.

The `teardown` handler will execute once the request has completed and after
`on_exit`.

Example:

>lua
    handlers = {
      lifecycle = {
        setup = function(self)
          -- Perform initialization
          return true  -- Must return boolean
        end,
    
        teardown = function(self)
          -- Clean up resources
        end,
      },
    }
<


THE UTILITY FILE

A lot of LLM endpoints claim to be "OpenAI Compatible" yet have odd quirks
which prevent you from using the OpenAI Adapter. Common issues can be:

- System messages have to be the first message (`anthropic`, `deepseek`)
- System messages have to be one message (`anthropic`, `deepseek`)
- Messages must follow a `User -> LLM -> User -> LLM` turn based flow (`deepseek`)

To address this, an adapter utilities
<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/utils/adapters.lua>
file has been created that you can leverage in building or extending your own
adapters. Finally, always refer to the pre-built adapters as a reference point.


SCHEMA ~

The schema table describes the settings/parameters for the LLM. If the user has
`display.chat.show_settings = true` then this table will be exposed at the top
of the chat buffer.

We’ll explore some of the options in the Copilot adapter’s schema table:

>lua
    schema = {
      model = {
        order = 1,
        mapping = "parameters",
        type = "enum",
        desc = "ID of the model to use. See the model endpoint compatibility table for details on which models work with the Chat API.",
        ---@type string|fun(): string
        default = "gpt-4o-2024-08-06",
        choices = {
          ["o3-mini-2025-01-31"] = { opts = { can_reason = true } },
          ["o1-2024-12-17"] = { opts = { can_reason = true } },
          ["o1-mini-2024-09-12"] = { opts = { can_reason = true } },
          "claude-3.5-sonnet",
          "claude-3.7-sonnet",
          "claude-3.7-sonnet-thought",
          "gpt-4o-2024-08-06",
          "gemini-2.0-flash-001",
        },
      },
    }
<

The model key sets out the specific model which is to be used to interact with
the Copilot endpoint. We’ve listed the default, in this example, as
`gpt-4o-2024-08-06` but we allow the user to choose from a possible five
options, via the `choices` key. We’ve given this an order value of `1` so
that it’s always displayed at the top of the chat buffer. We’ve also given
it a useful description as this is used in the virtual text when a user hovers
over it. Finally, we’ve specified that it has a mapping property of
`parameters`. This tells the adapter that we wish to map this model key to the
parameters part of the HTTP request. You’ll also notice that some of the
models have a table attached to them. This can be useful if you need to do
conditional logic in any of the handler methods at runtime.

Let’s take a look at one more schema value:

>lua
    temperature = {
      order = 2,
      mapping = "parameters",
      type = "number",
      default = 0,
      ---@param self CodeCompanion.HTTPAdapter
      enabled = function(self)
        local model = self.schema.model.default
        if type(model) == "function" then
          model = model()
        end
        return not vim.startswith(model, "o1")
      end,
      -- This isn't in the Copilot adapter but it's useful to reference!
      validate = function(n)
        return n >= 0 and n <= 2, "Must be between 0 and 2"
      end,
      desc = "What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.",
    },
<

You’ll see we’ve specified a function call for the `enabled` key. We’re
simply checking that the model name doesn’t start with `o1` as these models
don’t accept temperature as a parameter. You’ll also see we’ve specified
a function call for the `validate` key. We’re simply checking that the value
of the temperature is between 0 and 2.

For some endpoints, like OpenAI’s Responses API
<https://platform.openai.com/docs/api-reference/responses/create?api-mode=responses>,
schema values may need to be nested in the parameters:

>bash
    curl https://api.openai.com/v1/responses \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $OPENAI_API_KEY" \
      -d '{
        "model": "o3-mini",
        "input": "How much wood would a woodchuck chuck?",
        "reasoning": {
          "effort": "high"
        }
      }'
<

To accomplish this, you can use dot notation:

>lua
    ["reasoning.effort"] = {
      mapping = "parameters",
      type = "string",
      -- ...
    },
<


FUNCTION CALLING / TOOL USE ~

In order to enable your adapter to make use of Function Calling
<https://platform.openai.com/docs/guides/function-calling?api-mode=chat>, you
need to setup some additional handlers:

- `request.build_tools` - which transforms the tools provided by CodeCompanion into a schema supported by the adapter
- `tools.format_calls` - which formats <https://platform.openai.com/docs/guides/function-calling?api-mode=chat#handling-function-calls> the adapters tool calls and puts them into the http request
- `tools.format_response` - which formats and outputs the adapter’s tool call so it can be included in the chat buffer’s messages stack

You will also need to ensure that `opts.tools = true` and the `parse_chat`
handler has tools included as an optional final parameter like `parse_chat =
function(self, data, tools)`. From experience, whilst many LLMs claim to
support the OpenAI API standard for function calling, they can require some
additional configuration to work as expected.

Example:

>lua
    handlers = {
      request = {
        build_tools = function(self, tools)
          if not self.opts.tools or not tools then
            return
          end
          -- Transform tools into LLM's expected format
          return { tools = transformed_tools }
        end,
      },
    
      tools = {
        format_calls = function(self, tools)
          -- Format tool calls for the request
          return formatted_calls
        end,
    
        format_response = function(self, tool_call, output)
          -- Format tool response for LLM
          return {
            role = self.roles.tool or "tool",
            tools = {
              call_id = tool_call.id,
            },
            content = output,
            opts = { visible = false },
          }
        end,
      },
    }
<


MIGRATING FROM OLD HANDLER FORMAT ~

If you have an existing adapter using the old flat handler structure, it will
continue to work without changes. However, to migrate to the new nested
structure for better organization:

**Old format:**

>lua
    handlers = {
      setup = function(self) end,
      form_parameters = function(self, params, messages) end,
      form_messages = function(self, messages) end,
      chat_output = function(self, data, tools) end,
      inline_output = function(self, data, context) end,
      on_exit = function(self, data) end,
      teardown = function(self) end,
      tools = {
        format_tool_calls = function(self, tools) end,
        output_response = function(self, tool_call, output) end,
      },
    }
<

**New format:**

>lua
    handlers = {
      lifecycle = {
        setup = function(self) end,
        on_exit = function(self, data) end,
        teardown = function(self) end,
      },
      request = {
        build_parameters = function(self, params, messages) end,
        build_messages = function(self, messages) end,
      },
      response = {
        parse_chat = function(self, data, tools) end,
        parse_inline = function(self, data, context) end,
      },
      tools = {
        format_calls = function(self, tools) end,
        format_response = function(self, tool_call, output) end,
      },
    }
<


EXTENDING WITH AGENTIC WORKFLOWS*codecompanion-extending-extending-with-agentic-workflows*

Workflows in CodeCompanion, are successive prompts which can be automatically
sent to the LLM in a turn-based manner. This allows for actions such as
reflection and planning to be easily implemented into your workflow. They can
be combined with tools to create agentic workflows, which could be used to
automate common activities like editing files and then running a test suite.

I fully recommend reading Issue 242 of The Batch
<https://www.deeplearning.ai/the-batch/issue-242/> to understand the origin of
workflows. They were originally implemented
<https://github.com/olimorris/codecompanion.nvim/commit/73e5a27075749b3ff60cfc796438d302d4b08715>
in the plugin as an early form of Chain-of-thought
<https://en.wikipedia.org/wiki/Prompt_engineering#Chain-of-thought> prompting,
via the use of reflection and planning prompts.


HOW THEY WORK ~

Before showcasing some examples, it’s important to understand how workflows
have been implemented in the plugin.

When initiated from the |codecompanion-usage-action-palette|, workflows attach
themselves to a |codecompanion-usage-chat-buffer-index| via the notion of a
`subscription`. That is, the workflow has subscribed to the conversation and
dataflow that’s taking place in the chat buffer. After the LLM sends a
response, the chat buffer will trigger an event on the subscription class. This
will execute a callback which has been defined in the workflow itself (often
times this is simply a text prompt), and the event will duly be deleted from
the subscription to prevent it from being executed again.


CREATING AGENTIC WORKFLOWS ~

By combining a workflow with tools, we can use an LLM to act as an Agent and do
some impressive things!

A great example of that is the `Edit<->Test` workflow that originally came with
the plugin. This workflow asked the LLM to edit code in a buffer and then run a
test suite, feeding the output back to the LLM to then make future edits if
required.

::: details The full `Edit<->Test` workflow code can be found below:

>lua
    require("codecompanion").setup({
      prompt_library = {
        ["Edit<->Test workflow"] = {
          strategy = "workflow",
          description = "Use a workflow to repeatedly edit then test code",
          opts = {
            index = 5,
            is_default = true,
            short_name = "et",
          },
          prompts = {
            {
              {
                name = "Setup Test",
                role = "user",
                opts = { auto_submit = false },
                content = function()
                  -- Leverage YOLO mode which disables the requirement of approvals and automatically saves any edited buffer
                  local approvals = require("codecompanion.interactions.chat.tools.approvals")
                  approvals:toggle_yolo_mode()
    
                  return [[### Instructions
    
    Your instructions here
    
    ### Steps to Follow
    
    You are required to write code following the instructions provided above and test the correctness by running the designated test suite. Follow these steps exactly:
    
    1. Update the code in #{buffer} using the @{insert_edit_into_file} tool
    2. Then use the @{cmd_runner} tool to run the test suite with `<test_cmd>` (do this after you have updated the code)
    3. Make sure you trigger both tools in the same response
    
    We'll repeat this cycle until the tests pass. Ensure no deviations from these steps.]]
                end,
              },
            },
            {
              {
                name = "Repeat On Failure",
                role = "user",
                opts = { auto_submit = true },
                -- Scope this prompt to the cmd_runner tool
                condition = function(chat)
                  return chat.tools.tool and chat.tools.tool.name == "cmd_runner"
                end,
                -- Repeat until the tests pass, as indicated by the testing flag
                -- which the cmd_runner tool sets on the chat buffer
                repeat_until = function(chat)
                  return chat.tool_registry.flags.testing == true
                end,
                content = "The tests have failed. Can you edit the buffer and run the test suite again?",
              },
            },
          },
        },
      },
    })
<

:::

Let’s breakdown the prompts in that workflow:

>lua
    prompts = {
      {
        {
          name = "Setup Test",
          role = "user",
          opts = { auto_submit = false },
          content = function()
            -- Leverage YOLO mode which disables the requirement of approvals and automatically saves any edited buffer
            local approvals = require("codecompanion.interactions.chat.tools.approvals")
            approvals:toggle_yolo_mode()
    
            -- Some clear instructions for the LLM to follow
            return [[### Instructions
    
    Your instructions here
    
    ### Steps to Follow
    
    You are required to write code following the instructions provided above and test the correctness by running the designated test suite. Follow these steps exactly:
    
    1. Update the code in #{buffer}{watch} using the @{insert_edit_into_file} tool
    2. Then use the @{cmd_runner} tool to run the test suite with `<test_cmd>` (do this after you have updated the code)
    3. Make sure you trigger both tools in the same response
    
    We'll repeat this cycle until the tests pass. Ensure no deviations from these steps.]]
          end,
        },
      },
      --- Prompts to be continued ...
    },
<

The first prompt in a workflow should set the ask of the LLM and provide clear
instructions. In this case, we’re giving the LLM access to the
|codecompanion-usage-chat-buffer-tools.html-files| and
|codecompanion-usage-chat-buffer-tools.html-cmd-runner| tools to edit a buffer
and run tests, respectively.

We’re giving the LLM knowledge of the buffer with the `#buffer` variable and
also telling CodeCompanion to watch it for any changes with the `{watch}`
parameter. Prior to sending a response to the LLM, the plugin will share any
changes to that buffer, keeping the LLM updated.

Now let’s look at how we trigger the automated reflection prompts:

>lua
    {
      {
        --- Prompts continued...
        {
          {
            name = "Repeat On Failure",
            role = "user",
            opts = { auto_submit = true },
            -- Scope this prompt to only run when the cmd_runner tool is active
            condition = function(chat)
              return chat.tools.tool and chat.tools.tool.name == "cmd_runner"
            end,
            -- Repeat until the tests pass, as indicated by the testing flag
            repeat_until = function(chat)
              return chat.tool_registry.flags.testing == true
            end,
            content = "The tests have failed. Can you edit the buffer and run the test suite again?",
          },
        },
      },
    },
<

Now there’s a little bit more to unpack in this prompt. Firstly, we’re
automatically submitting the prompt to the LLM to save the user some time and
keypresses. Next, we’re scoping the prompt to only be sent to the chat buffer
if the currently active tool is the
|codecompanion-usage-chat-buffer-tools.html-cmd-runner|.

We’re also leveraging a function called `repeat_until`. This ensures that the
prompt is always attached to the chat buffer until a condition is met. In this
case, until the tests pass. In the
|codecompanion-usage-chat-buffer-tools.html-cmd-runner| tool, we ask the LLM to
pass a flag if it detects a test suite is being run. The plugin picks up on
that flag and puts the test outcome into the chat buffer class as a flag.

Finally, we’re letting the LLM know that the tests failed, and asking it to
fix.


EXTENDING WITH EXTENSIONS  *codecompanion-extending-extending-with-extensions*

CodeCompanion supports extensions similar to telescope.nvim, allowing users to
create functionality that can be shared with others. Extensions can either be
distributed as plugins or defined locally in your configuration.


EXTENSIONS ~

Extensions are configured in your CodeCompanion setup:

>lua
    -- Install the extension
    {
      "olimorris/codecompanion.nvim",
      dependencies = {
        "ravitemer/codecompanion-history.nvim" -- history extension
      }
    }
    
    -- Configure in your setup
    require("codecompanion").setup({
      extensions = {
        history = {
          enabled = true, -- defaults to true
          opts = {
            dir_to_save = vim.fn.stdpath("data") .. "/codecompanion_chats.json",
          }
        }
      }
    })
<


CREATING EXTENSIONS ~

Extensions are typically distributed as plugins. Create a new plugin with the
following structure:

>
    your-extension/
    ├── lua/
    │   └── codecompanion/
    │       └── _extensions/
    │           └── your_extension/
    │               └── init.lua  -- Main extension file
    └── README.md
<

The init.lua file should export a module that provides setup and optional
exports:

>lua
    ---@class CodeCompanion.Extension
    ---@field setup fun(opts: table) Function called when extension is loaded
    ---@field exports? table Functions exposed via codecompanion.extensions.your_extension
    local Extension = {}
    
    ---Setup the extension
    ---@param opts table Configuration options
    function Extension.setup(opts)
      -- Initialize extension
      -- Add actions, keymaps etc.
    end
    
    -- Optional: Functions exposed via codecompanion.extensions.your_extension
    Extension.exports = {
      clear_history = function() end
    }
    
    return Extension
<


EXTENDING CHAT FUNCTIONALITY

A common pattern is to add keymaps, slash_commands, tools to the
codecompanion.config object inside setup function.

>lua
    ---This is called on codecompanion setup.
    ---You can access config via require("codecompanion.config") and chat via require("codecompanion.chat").last_chat() etc
    function Extension.setup(opts)
      -- Add action to chat keymaps
      local chat_keymaps = require("codecompanion.config").interactions.chat.keymaps
    
      chat_keymaps.open_saved_chats = {
        modes = {
          n = opts.keymap or "gh",
        },
        description = "Open Saved Chats",
        callback = function(chat)
            -- Implementation of opening saved chats
            vim.notify("Opening saved chats for " .. chat.id)
        end
      }
    end
<

Once configured, extension exports are accessible via:

>lua
    local codecompanion = require("codecompanion")
    -- Use exported functions
    codecompanion.extensions.codecompanion_history.clear_history()
<


LOCAL EXTENSIONS ~

Extensions can also be defined directly in your configuration for simpler use
cases:

>lua
    -- Example: Adding a message editor extension
    require("codecompanion").setup({
      extensions = {
        editor = {
          enabled = true,
          opts = {},
          callback = {
            setup = function(ext_config)
              -- Add a new action to chat keymaps
              local open_editor = {
                modes = {
                  n = "ge",  -- Keymap to open editor
                },
                description = "Open Editor",
                callback = function(chat)
                  -- Implementation of editor opening logic
                  -- You have access to the chat buffer via the chat parameter
                  vim.notify("Editor opened for chat " .. chat.id)
                end,
              }
    
              -- Add the action to chat keymaps config
              local chat_keymaps = require("codecompanion.config").interactions.chat.keymaps
              chat_keymaps.open_editor = open_editor
            end,
    
            -- Optional: Expose functions
            exports = {
              is_editor_open = function()
                return false -- Implementation
              end
            }
          }
        }
      }
    })
<

The callback can be: - A function returning the extension table - The extension
table directly - A string path to a module that returns the extension


DYNAMIC REGISTRATION ~

Extensions can also be added dynamically using

>lua
    require("codecompanion").register_extension("codecompanion_history", {
        callback = {
            setup = function()
            end,
            exports = {}
        },
    })
<


BEST PRACTICES ~

1. **Namespacing**:- Use unique names for extensions to avoid conflicts
- Prefix functions and variables appropriately


2. **Configuration**:- Provide sensible defaults
- Allow customization via opts table
- Document all options


3. **Integration**:- Follow CodeCompanion’s patterns for actions and tools
- Use existing utilities like keymaps.set_keymap
- Handle errors appropriately


4. **Documentation**:- Document installation process
- List all available options
- Provide usage examples




EXTENDING WITH RULES PARSERS*codecompanion-extending-extending-with-rules-parsers*

In CodeCompanion, parsers act on the contents of a rules file, carrying out
some post-processing activities and returning the content back to the rules
class.

Parsers serve as an excellent way to apply modifications and extract metadata
prior to sharing them with an LLM.


STRUCTURE OF A PARSER ~

A parser has limited restrictions. It is simply required to return a function
that the `rules` class can execute, passing in the file to be processed as a
parameter:

>lua
    ---@class CodeCompanion.Chat.Rules.Parser
    ---@field content string The content of the rules file
    ---@field meta? { included_files: string[] } The filename of the rules file
    
    ---@param file CodeCompanion.Chat.Rules.ProcessedFile
    ---@return CodeCompanion.Chat.Rules.Parser
    return function(file)
      -- Your logic
    end
<

As an output, the function must return a table containing a `content` key.


PROCESSING FILES ~

Parsers may also return a list of files to be shared with the LLM by the
`rules` class. To enable this, ensure that the parser returns a
`meta.included_files` array in its output:

>lua
    {
      content = "Your parsed content",
      meta = {
        included_files = {
          ".codecompanion/acp/acp_json_schema.json",
          "./lua/codecompanion/acp/init.lua",
          "./lua/codecompanion/adapters/acp/claude_code.lua",
          "./lua/codecompanion/adapters/acp/helpers.lua",
          "./lua/codecompanion/acp/prompt_builder.lua",
          "./lua/codecompanion/interactions/chat/acp/handler.lua",
          "./lua/codecompanion/interactions/chat/acp/request_permission.lua",
        },
      },
    }
<


EXTENDING WITH TOOLS            *codecompanion-extending-extending-with-tools*

In CodeCompanion, tools offer pre-defined ways for LLMs to call functions on
your machine, acting as an Agent in the process. This guide walks you through
the implementation of tools, enabling you to create your own.

In the plugin, tools are a Lua table, consisting of various handler and output
functions, alongside a system prompt and an OpenAI compatible schema
<https://platform.openai.com/docs/guides/function-calling?api-mode=chat>.

When you add a tool to the chat buffer, this gives the LLM the knowledge to be
able to call the tool, when required. Once called, the plugin will parse the
LLM’s response and execute the tool accordingly, before sharing the output in
the chat buffer.


ARCHITECTURE ~

In order to create tools, you do not need to understand the underlying
architecture. However, for those who are curious about the implementation,
please see the diagram below:

>mermaid
    sequenceDiagram
        participant C as Chat Buffer
        participant L as LLM
        participant TS as Tool System
        participant O as Orchestrator
        participant T as Tool
    
        C->>L: Prompt with tool schemas
        L->>C: Response with tool call(s)
    
        C->>TS: Parse LLM response
    
        loop For each tool call detected
            TS->>TS: Tool.resolve(tool_config)
            TS->>TS: Add tool to queue
        end
    
        TS->>O: Create Orchestrator with queue
        TS->>C: Fire "ToolsStarted" autocmd
    
        loop While queue not empty
            O->>O: Pop tool from queue
            O->>O: Setup handlers and output functions
            O->>T: handlers.setup()
    
            Note over O,C: If approval required, prompt user
            O->>C: User approval (if needed)
    
            Note over O,T: If rejected/cancelled, call output handlers and continue
            Note over O,T: If approved or no approval needed, execute tool
    
            loop For each cmd in tool.cmds
                O->>T: Execute function(tool_system, args, input, output_handler)
                Note over T,O: Returns {status, data} (sync) or calls output_handler (async)
                O->>T: output.success() OR output.error()
                T->>C: add_tool_output()
            end
    
            O->>T: handlers.on_exit()
        end
    
        TS->>TS: reset()
        TS->>C: Fire "ToolsFinished" autocmd
        TS->>C: tools_done()
<


BUILDING YOUR FIRST BUILT-IN TOOL ~

Before we begin, it’s important to familiarise yourself with the directory
structure of the tools implementation:

>
    interactions/chat/tools
    ├── init.lua
    ├── orchestrator.lua
    ├── runtime/
    │   ├── queue.lua
    │   ├── runner.lua
    ├── builtin/
    │   ├── cmd_runner.lua
    │   ├── insert_edit_into_file.lua
    │   ├── create_file.lua
    │   ├── ...
<

When a tool is detected, the chat buffer sends any output to the
`tools/init.lua` file (I will commonly refer to that as the `“tool system
file”` throughout this document). The tool system file then parses the
response from the LLM, identifying the tool and duly executing it.

There are two types of tools that CodeCompanion can leverage:

1. **Command-based**: These tools can execute a series of commands in the background using `vim.system`. They’re non-blocking, meaning you can carry out other activities in Neovim whilst they run. Useful for heavy/time-consuming tasks.
2. **Function-based**: These tools, like insert_edit_into_file <https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/interactions/chat/tools/builtin/insert_edit_into_file.lua>, execute Lua functions directly in Neovim within the main process, one after another. They can also be executed asynchronously.

For the purposes of this section of the guide, we’ll be building a simple
function-based calculator tool that an LLM can use to do basic maths.


TOOL STRUCTURE

All tools must implement the following structure which the bulk of this guide
will focus on explaining:

>lua
    ---@class CodeCompanion.Tools.Tool
    ---@field name string The name of the tool
    ---@field cmds table The commands to execute
    ---@field function_call table The function call from the LLM
    ---@field schema table The schema that the LLM must use in its response to execute a tool
    ---@field system_prompt string | fun(schema: table): string The system prompt to the LLM explaining the tool and the schema
    ---@field opts? table The options for the tool
    ---@field env? fun(schema: table): table|nil Any environment variables that can be used in the *_cmd fields. Receives the parsed schema from the LLM
    ---@field handlers table Functions which handle the execution of a tool
    ---@field handlers.setup? fun(self: CodeCompanion.Tools.Tool, tools: CodeCompanion.Tools): any Function used to setup the tool. Called before any commands
    ---@field handlers.prompt_condition? fun(self: CodeCompanion.Tools.Tool, tools: CodeCompanion.Tools, config: table): boolean Function to determine whether to show the promp to the user or not
    ---@field handlers.on_exit? fun(self: CodeCompanion.Tools.Tool, tools: CodeCompanion.Tools): any Function to call at the end of a group of commands or functions
    ---@field output? table Functions which handle the output after every execution of a tool
    ---@field output.prompt fun(self: CodeCompanion.Tools.Tool, tools: CodeCompanion.Tools): string The message which is shared with the user when asking for their approval
    ---@field output.rejected? fun(self: CodeCompanion.Tools.Tool, tools: CodeCompanion.Tools, cmd: table): any Function to call if the user rejects running a command
    ---@field output.error? fun(self: CodeCompanion.Tools.Tool, tools: CodeCompanion.Tools, cmd: table, stderr: table, stdout?: table): any The function to call if an error occurs
    ---@field output.success? fun(self: CodeCompanion.Tools.Tool, tools: CodeCompanion.Tools, cmd: table, stdout: table): any Function to call if the tool is successful
    ---@field output.cancelled? fun(self: CodeCompanion.Tools.Tool, tools: CodeCompanion.Tools, cmd: table): any Function to call if the tool is cancelled
    ---@field args table The arguments sent over by the LLM when making the request
    ---@field tool table The tool configuration from the config file
<


CMDS

**Command-Based Tools**

The `cmds` table is a collection of commands which the tool system will execute
one after another, asynchronously, using `vim.system`.

>lua
    cmds = {
      { "make", "test" },
      { "echo", "hello" },
    }
<

In this example, the plugin will execute `make test` followed by `echo hello`.
After each command executes, the plugin will automatically send the output to a
corresponding table on the tool system file. If the command ran with success
the output will be written to `stdout`, otherwise it will go to `stderr`.
We’ll be covering how you access that data in the output section below.

It’s also possible to pass in environment variables (from the `env` function)
by use of ${} brackets. The now removed `@code_runner` tool used them as below:

>lua
    cmds = {
        { "docker", "pull", "${lang}" },
        {
          "docker",
          "run",
          "--rm",
          "-v",
          "${temp_dir}:${temp_dir}",
          "${lang}",
          "${lang}",
          "${temp_input}",
        },
      },
    },
    ---@param self CodeCompanion.Tools.Tool
    ---@return table
    env = function(self)
      local temp_input = vim.fn.tempname()
      local temp_dir = temp_input:match("(.*/)")
      local lang = self.args.lang
      local code = self.args.code
    
      return {
        code = code,
        lang = lang,
        temp_dir = temp_dir,
        temp_input = temp_input,
      }
    end,
<


  [!IMPORTANT] Using the `handlers.setup()` function, it’s also possible to
  create commands dynamically like in the cmd_runner
  <https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/interactions/chat/tools/builtin/cmd_runner.lua>
  tool.
**Function-based Tools**

Function-based tools use the `cmds` table to define functions that will be
executed one after another. Each function has four parameters, itself, the
actions request by the LLM, any input from a previous function call and a
`output_handler` callback for async execution. The `output_handler` handles the
result for an asynchronous tool. For a synchronous tool (like the calculator)
you can ignore it. For the purpose of our calculator example:

>lua
    cmds = {
      ---@param self CodeCompanion.Tool.Calculator The Calculator tool
      ---@param args table The arguments from the LLM's tool call
      ---@param input? any The output from the previous function call
      ---@return nil|{ status: "success"|"error", data: string }
      function(self, args, input)
        -- Get the numbers and operation requested by the LLM
        local num1 = tonumber(args.num1)
        local num2 = tonumber(args.num2)
        local operation = args.operation
    
        -- Validate input
        if not num1 then
          return { status = "error", data = "First number is missing or invalid" }
        end
    
        if not num2 then
          return { status = "error", data = "Second number is missing or invalid" }
        end
    
        if not operation then
          return { status = "error", data = "Operation is missing" }
        end
    
        -- Perform the calculation
        local result
        if operation == "add" then
          result = num1 + num2
        elseif operation == "subtract" then
          result = num1 - num2
        elseif operation == "multiply" then
          result = num1 * num2
        elseif operation == "divide" then
          if num2 == 0 then
            return { status = "error", data = "Cannot divide by zero" }
          end
          result = num1 / num2
        else
          return { status = "error", data = "Invalid operation: must be add, subtract, multiply, or divide" }
        end
    
        return { status = "success", data = result }
      end,
    },
<

For a synchronous tool, you only need to `return` the result table as
demonstrated. However, if you need to invoke some asynchronous actions in the
tool, you can use the `output_handler` to submit any results to the
orchestrator, which will then invoke `output` functions to handle the results:

>lua
    cmds = {
      function(self, args, input, output_handler)
        -- This is for demonstration only
        vim.lsp.client.request(lsp_method, lsp_param, function(err, result, _, _)
          self.tools.chat:add_message({ role = "user", content = vim.json.encode(result) })
          output_handler({ status = "success", data = result })
        end, buf_nr)
      end
    }
<

Note that:

1. The `output_handler` will be called only once. Subsequent calls will be discarded;
2. A tool function should EITHER return the result table (synchronous), OR call the `output_handler` with the result table as the only argument (asynchronous), but not both.
If a function tries to both return the result and call the `output_handler`, the result will be undefined because there’s no guarantee which output will be handled first.

Similarly with command-based tools, the output is written to the `stdout` or
`stderr` tables on the tool system file. However, with function-based tools,
the user must manually specify the outcome of the execution which in turn
redirects the output to the correct table:

>lua
    return { status = "error", data = "Invalid operation: must be add, subtract, multiply, or divide" }
<

Will cause execution of the tool to stop and populate `stderr` on the tool
system file.

>lua
    return { status = "success", data = result }
<

Will populate the `stdout` table on the tool system file and allow for
execution to continue.


SCHEMA

The function call that the LLM has sent, is parsed and sent to the `args`
parameter of any function you’ve created in
|codecompanion-extending-tools.html-cmds|, as a JSON object which is then
converted to Lua via `vim.json.decode`. If the LLM has done its job correctly,
the Lua table should be the representation of what you’ve described in the
schema. In summary, the schema represents the structure of the response that
the LLM must follow in order to call the tool.

For a tool to function correctly, your tool requires an OpenAI compatible
<https://platform.openai.com/docs/guides/function-calling?api-mode=chat>
schema. For our basic calculator tool, which does an operation on two numbers,
the schema could look something like:

>lua
    schema = {
      type = "function",
      ["function"] = {
        name = "calculator",
        description = "Perform simple mathematical operations on a user's machine",
        parameters = {
          type = "object",
          properties = {
            num1 = {
              type = "integer",
              description = "The first number in the calculation",
            },
            num2 = {
              type = "integer",
              description = "The second number in the calculation",
            },
            operation = {
              type = "string",
              enum = { "add", "subtract", "multiply", "divide" },
              description = "The mathematical operation to perform on the two numbers",
            },
          },
          required = {
            "num1",
            "num2",
            "operation"
          },
          additionalProperties = false,
        },
        strict = true,
      },
    },
<


SYSTEM_PROMPT

In the plugin, LLMs are given knowledge about a tool and how it can be used via
the schema. However, for a particularly complicated tool, you can choose to
include a system prompt. This is something that CodeCompanion does for the
`insert_edit_into_file` tool.


  [!TIP] From experience, a system prompt should be used sparingly. It’s often
  an indication that your tool is too complicated and should be split out into
  multiple tools.
For our calculator tool, we’re going to use a `system_prompt` just to
demonstrate the functionality:

>lua
    system_prompt = [[## Calculator Tool (`calculator`)
    
    ## CONTEXT
    - You have access to a calculator tool running within CodeCompanion, in Neovim.
    - You can use it to add, subtract, multiply or divide two numbers.
    
    ### OBJECTIVE
    - Do a mathematical operation on two numbers when the user asks
    
    ### RESPONSE
    - Always use the structure above for consistency.
    ]],
<


HANDLERS

The `handlers` table contains two functions that are executed before and after
a tool completes:

1. `setup` - Is called **before** anything in the |codecompanion-extending-tools.html-cmds| and |codecompanion-extending-tools.html-output| table. This is useful if you wish to set the cmds dynamically on the tool itself, like in the @cmd_runner <https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/interactions/chat/tools/builtin/cmd_runner.lua> tool.
2. `on_exit` - Is called **after** everything in the |codecompanion-extending-tools.html-cmds| and |codecompanion-extending-tools.html-output| table.
3. `prompt_condition` - Is called **before** anything in the |codecompanion-extending-tools.html-cmds| and |codecompanion-extending-tools.html-output| table and is used to determine `if` the user should be prompted for approval. This is used in the `@insert_edit_into_file` tool to allow users to determine if they’d like to apply an approval to `buffer` or `file` edits.

For the purposes of our calculator, let’s just return some notifications so
you can see the tool system and tool flow:

>lua
    handlers = {
      ---@param self CodeCompanion.Tool.Calculator
      ---@param tools CodeCompanion.Tools The tool object
      setup = function(self, tools)
        return vim.notify("setup function called", vim.log.levels.INFO)
      end,
      ---@param self CodeCompanion.Tool.Calculator
      ---@param tools CodeCompanion.Tools
      on_exit = function(self, tools)
        return vim.notify("on_exit function called", vim.log.levels.INFO)
      end,
    },
<


  [!TIP] The chat buffer can be accessed via `tools.chat` in the handler and
  output tables

OUTPUT

The `output` table enables you to manage and format output from the execution
of the |codecompanion-extending-tools.html-cmds|. It contains four functions:

1. `success` - Is called after `every` successful execution of a command/function. This can be a useful way of notifying the LLM of the success.
2. `error` - Is called when an error occurs whilst executing a command/function. It will only ever be called once as the whole execution of the |codecompanion-extending-tools.html-cmds| is halted. This can be a useful way of notifying the LLM of the failure.
3. `prompt` - Is called when user approval to execute the |codecompanion-extending-tools.html-cmds| is required. It forms the message prompt which the user is asked to confirm or reject.
4. `rejected` - Is called when a user rejects the approval to run the |codecompanion-extending-tools.html-cmds|. This method is used to inform the LLM of the rejection.

Let’s consider how me might implement this for our calculator tool:

>lua
    output = {
      ---@param self CodeCompanion.Tool.Calculator
      ---@param tools CodeCompanion.Tools
      ---@param cmd table The command that was executed
      ---@param stdout table
      success = function(self, tools, cmd, stdout)
        local chat = tools.chat
        return chat:add_tool_output(self, tostring(stdout[1]))
      end,
      ---@param self CodeCompanion.Tool.Calculator
      ---@param tools CodeCompanion.Tools
      ---@param cmd table
      ---@param stderr table The error output from the command
      error = function(self, tools, cmd, stderr)
        return vim.notify("An error occurred", vim.log.levels.ERROR)
      end,
    },
<

The `add_tool_output` method is designed to make it as easy as possible for
tool authors to update the message history on the chat buffer:

>lua
    ---Add the output from a tool to the message history and a message to the UI
    ---@param tool table The Tool that was executed
    ---@param for_llm string The output to share with the LLM
    ---@param for_user? string The output to share with the user. If empty will use the LLM's output
    ---@return nil
    function Chat:add_tool_output(tool, for_llm, for_user)
      -- Omitted for brevity
    end
<

The `for_llm` parameter is the string message that will be shared with the LLM
as part of the message history in the chat buffer, this is not made visible to
the user. The `for_user` parameter allows tool authors to customize the visible
output in the chat buffer, but if this is nil then the `for_llm` string is
used.


RUNNING THE CALCULATOR TOOL

If we put this all together in our config:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          tools = {
            calculator = {
              description = "Perform calculations",
              callback = {
                name = "calculator",
                cmds = {
                  ---@param self CodeCompanion.Tool.Calculator The Calculator tool
                  ---@param args table The arguments from the LLM's tool call
                  ---@param input? any The output from the previous function call
                  ---@return nil|{ status: "success"|"error", data: string }
                  function(self, args, input)
                    -- Get the numbers and operation requested by the LLM
                    local num1 = tonumber(args.num1)
                    local num2 = tonumber(args.num2)
                    local operation = args.operation
    
                    -- Validate input
                    if not num1 then
                      return { status = "error", data = "First number is missing or invalid" }
                    end
    
                    if not num2 then
                      return { status = "error", data = "Second number is missing or invalid" }
                    end
    
                    if not operation then
                      return { status = "error", data = "Operation is missing" }
                    end
    
                    -- Perform the calculation
                    local result
                    if operation == "add" then
                      result = num1 + num2
                    elseif operation == "subtract" then
                      result = num1 - num2
                    elseif operation == "multiply" then
                      result = num1 * num2
                    elseif operation == "divide" then
                      if num2 == 0 then
                        return { status = "error", data = "Cannot divide by zero" }
                      end
                      result = num1 / num2
                    else
                      return {
                        status = "error",
                        data = "Invalid operation: must be add, subtract, multiply, or divide",
                      }
                    end
    
                    return { status = "success", data = result }
                  end,
                },
                system_prompt = [[## Calculator Tool (`calculator`)
    
    ## CONTEXT
    - You have access to a calculator tool running within CodeCompanion, in Neovim.
    - You can use it to add, subtract, multiply or divide two numbers.
    
    ### OBJECTIVE
    - Do a mathematical operation on two numbers when the user asks
    
    ### RESPONSE
    - Always use the structure above for consistency.
    ]],
    
                schema = {
                  type = "function",
                  ["function"] = {
                    name = "calculator",
                    description = "Perform simple mathematical operations on a user's machine",
                    parameters = {
                      type = "object",
                      properties = {
                        num1 = {
                          type = "integer",
                          description = "The first number in the calculation",
                        },
                        num2 = {
                          type = "integer",
                          description = "The second number in the calculation",
                        },
                        operation = {
                          type = "string",
                          enum = { "add", "subtract", "multiply", "divide" },
                          description = "The mathematical operation to perform on the two numbers",
                        },
                      },
                      required = {
                        "num1",
                        "num2",
                        "operation",
                      },
                      additionalProperties = false,
                    },
                    strict = true,
                  },
                },
                handlers = {
                  ---@param self CodeCompanion.Tool.Calculator
                  ---@param tools CodeCompanion.Tools The tool object
                  setup = function(self, tools)
                    return vim.notify("setup function called", vim.log.levels.INFO)
                  end,
                  ---@param self CodeCompanion.Tool.Calculator
                  ---@param tools CodeCompanion.Tools
                  on_exit = function(self, tools)
                    return vim.notify("on_exit function called", vim.log.levels.INFO)
                  end,
                },
                output = {
                  ---@param self CodeCompanion.Tool.Calculator
                  ---@param tools CodeCompanion.Tools
                  ---@param cmd table The command that was executed
                  ---@param stdout table
                  success = function(self, tools, cmd, stdout)
                    local chat = tools.chat
                    return chat:add_tool_output(self, tostring(stdout[1]))
                  end,
                  ---@param self CodeCompanion.Tool.Calculator
                  ---@param tools CodeCompanion.Tools
                  ---@param cmd table
                  ---@param stderr table The error output from the command
                  error = function(self, tools, cmd, stderr)
                    return vim.notify("An error occurred", vim.log.levels.ERROR)
                  end,
                },
              },
            },
          },
        }
      }
    })
<

and with the prompt:

>
    Use the @{calculator} tool for 100*50
<

You should see: `5000`, in the chat buffer.


ADDING IN USER APPROVALS

A big concern for users when they create and deploy their own tools is `“what
if an LLM does something I’m not aware of or I don’t approve?”`. To that
end, CodeCompanion tries to make it easy for a user to be the "human in the
loop" and approve tool use before execution.

To enable this for any tool, simply add the `require_approval_before = true` in
a tool’s `opts` table:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          tools = {
            calculator = {
              description = "Perform calculations",
              callback = "as above",
              opts = {
                require_approval_before = true,
              },
            }
          }
        }
      }
    })
<


  [!NOTE] `opts.require_approval_before` can also be a function that receives the
  tool and tool system classes as parameters
To account for the user being prompted for an approval, we can add a
`output.prompt` to the tool:

>lua
    output = {
      -- success and error functions remain the same ...
    
      ---The message which is shared with the user when asking for their approval
      ---@param self CodeCompanion.Tool.Calculator
      ---@param tools CodeCompanion.Tools
      ---@return string
      prompt = function(self, tools)
        return string.format(
          "Perform the calculation `%s`?",
          self.args.num1 .. " " .. self.args.operation .. " " .. self.args.num2
        )
      end,
    },
<

This will notify the user with the message: `Perform the calculation 100
multiply 50?`. The user can choose to proceed, reject or cancel. The latter
will cancel any tools from running.

You can also customize the output if a user rejects the approval or cancels the
tool execution:

>lua
    output = {
      -- success, error and prompt functions remain the same ...
    
      ---Rejection message back to the LLM
      ---@param self CodeCompanion.Tool.Calculator
      ---@param tools CodeCompanion.Tools
      ---@param cmd table
      ---@return nil
      rejected = function(self, tools, cmd)
        tools.chat:add_tool_output(self, "The user declined to run the calculator tool")
      end,
    
      ---Cancellation message back to the LLM
      ---@param self CodeCompanion.Tool.Calculator
      ---@param tools CodeCompanion.Tools
      ---@param cmd table
      ---@return nil
      cancelled = function(self, tools, cmd)
        tools.chat:add_tool_output(self, "The user cancelled the execution of the calculator tool")
      end,
    },
<


SUPPORTING AN ADAPTER TOOL ~

Many LLM providers such as Anthropic
<https://docs.claude.com/en/docs/agents-and-tools/tool-use/computer-use-tool>
and OpenAI
<https://platform.openai.com/docs/guides/tools-web-search?api-mode=responses>
provide their own tools that clients like CodeCompanion can hook into.

Thankfully, adding support for adapter tools is trivial. The #2307
<https://github.com/olimorris/codecompanion.nvim/pull/2307> PR showed how this
can be accomplished for both Anthropic and the OpenAI responses adapters.

1. Add the tool to the structure of the adapter:

>lua
    -- openai_responses.lua
    -- ... existing code ...
    available_tools = {
      ["web_search"] = {
        description = "Allow models to search the web for the latest information before generating a response.",
        enabled = true,
        ---@param self CodeCompanion.HTTPAdapter.OpenAIResponses
        ---@param tools table The transformed tools table
        callback = function(self, tools)
          table.insert(tools, {
            type = "web_search",
          })
        end,
      },
    },
    -- ... existing code ...
<

Within the `callback` function, which will be executed in step 2, it can be
useful to carry out modifications to the adapter which may be required for the
tool to function. In the case of Anthropic, we insert additional headers.

1. Within `build_tools` or `form_tools` (depending on your adapter), ensure that when looping through a tool’s schema, you detect if the tool is an adapter tool and execute the `callback` from step 1:

>lua
    -- build_tools = function(self, tools)
    -- OR
    -- form_tools = function(self, tools)
    local transformed = {}
    for _, tool in pairs(tools) do
      for _, schema in pairs(tool) do
        -- // Add this logic
        if schema._meta and schema._meta.adapter_tool then
          if self.available_tools[schema.name] then
            self.available_tools[schema.name].callback(self, transformed)
          end
        else
        -- //
          -- Previous loop logic goes here
        end
      end
    end
<

Some adapter tools can be a `hybrid` in terms of their implementation. That is,
they’re an adapter tool that requires a client-side component (i.e.� a
built-in tool). This is the case for the
|codecompanion-usage-chat-buffer-tools-memory| tool from Anthropic. To allow
for this, ensure that the tool definition in `available_tools` has
`client_tool` defined:

>lua
    ["memory"] = {
      -- ...existing code here
      opts = {
        -- Allow a hybrid tool -> One that also has a client side implementation
        client_tool = "interactions.chat.tools.memory",
      },
    },
<


OTHER TIPS ~


USE_HANDLERS_ONCE

If an LLM calls multiple tools in the same response, it’s possible that the
same tool may be called in succession. If you’d like to ensure that the
handler functions (`setup` and `on_exit`) are only called once, you can set
this in the `opts` table in the tool itself:

>lua
    return {
      name = "editor",
      opts = {
        use_handlers_once = true,
      },
      -- More code follows...
    }
<


EXTENDING THE UI                    *codecompanion-extending-extending-the-ui*

Below are some examples of how you can extend CodeCompanion and modify the user
interface to suit your needs.


PROGRESS UPDATES WITH FIDGET.NVIM BY @JESSEVDP ~

As per the discussion over at #813
<https://github.com/olimorris/codecompanion.nvim/discussions/813>.


INLINE SPINNER WITH FIDGET.NVIM BY @YUHUA99 ~

As per the comment on #640
<https://github.com/olimorris/codecompanion.nvim/discussions/640#discussioncomment-12866279>.


STATUS COLUMN EXTMARKS WITH THE INLINE ASSISTANT BY @LUCOBELLIC ~

As per the discussion over at #1297
<https://github.com/olimorris/codecompanion.nvim/discussions/1297>.


LUALINE.NVIM INTEGRATION ~

The plugin can be integrated with lualine.nvim to show an icon in the
statusline when a request is being sent to an LLM:

>lua
    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 INTEGRATION ~

The plugin can also be integrated into heirline.nvim
<https://github.com/rebelot/heirline.nvim> to show an icon when a request is
being sent to an LLM and also to show useful meta information about the chat
buffer.

In the video at the top of this page, you can see the fidget spinner alongside
the heirline.nvim integration below:

>lua
    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" },
      },
    }
    
    local IsCodeCompanion = function()
      return package.loaded.codecompanion and vim.bo.filetype == "codecompanion"
    end
    
    local CodeCompanionCurrentContext = {
      static = {
        enabled = true,
      },
      condition = function(self)
        return IsCodeCompanion() and _G.codecompanion_current_context ~= nil and self.enabled
      end,
      provider = function()
        local bufname = vim.fn.fnamemodify(vim.api.nvim_buf_get_name(_G.codecompanion_current_context), ":t")
        return "[  " .. bufname .. " ] "
      end,
      hl = { fg = "gray", bg = "bg" },
      update = {
        "User",
        pattern = { "CodeCompanionRequest*", "CodeCompanionContextChanged" },
        callback = vim.schedule_wrap(function(self, args)
          if args.match == "CodeCompanionRequestStarted" then
            self.enabled = false
          elseif args.match == "CodeCompanionRequestFinished" then
            self.enabled = true
          end
          vim.cmd("redrawstatus")
        end),
      },
    }
    
    local CodeCompanionStats = {
      condition = function(self)
        return IsCodeCompanion()
      end,
      static = {
        chat_values = {},
      },
      init = function(self)
        local bufnr = vim.api.nvim_get_current_buf()
        self.chat_values = _G.codecompanion_chat_metadata[bufnr]
      end,
      -- Tokens block
      {
        condition = function(self)
          return self.chat_values.tokens > 0
        end,
        RightSlantStart,
        {
          provider = function(self)
            return "   " .. self.chat_values.tokens .. " "
          end,
          hl = { fg = "gray", bg = "statusline_bg" },
          update = {
            "User",
            pattern = { "CodeCompanionChatOpened", "CodeCompanionRequestFinished" },
            callback = vim.schedule_wrap(function()
              vim.cmd("redrawstatus")
            end),
          },
        },
        RightSlantEnd,
      },
      -- Cycles block
      {
        condition = function(self)
          return self.chat_values.cycles > 0
        end,
        RightSlantStart,
        {
          provider = function(self)
            return "  " .. self.chat_values.cycles .. " "
          end,
          hl = { fg = "gray", bg = "statusline_bg" },
          update = {
            "User",
            pattern = { "CodeCompanionChatOpened", "CodeCompanionRequestFinished" },
            callback = vim.schedule_wrap(function()
              vim.cmd("redrawstatus")
            end),
          },
        },
        RightSlantEnd,
      },
    }
<

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl: