codecompanion.txt

*codecompanion.txt*           For NVIM v0.11          Last change: 2026 May 03

==============================================================================
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|
  - Setup                                |codecompanion-getting-started-setup|
  - Usage                                |codecompanion-getting-started-usage|
  - Suggested Workflow      |codecompanion-getting-started-suggested-workflow|
4. Architecture                                   |codecompanion-architecture|
  - How Context Is Managed |codecompanion-architecture-how-context-is-managed|
5. ACP                                                     |codecompanion-acp|
  - Implementation                          |codecompanion-acp-implementation|
  - Protocol Version                      |codecompanion-acp-protocol-version|
  - Current Limitations                |codecompanion-acp-current-limitations|
  - See Also                                      |codecompanion-acp-see-also|
6. MCP                                                     |codecompanion-mcp|
  - Usage                                            |codecompanion-mcp-usage|
  - Implementation                          |codecompanion-mcp-implementation|
  - Protocol Version                      |codecompanion-mcp-protocol-version|
  - See Also                                      |codecompanion-mcp-see-also|
7. 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|
  - Command-Line Interface (CLI)|codecompanion-configuration-command-line-interface-(cli)|
  - Inline Interaction        |codecompanion-configuration-inline-interaction|
  - MCP Servers                      |codecompanion-configuration-mcp-servers|
  - 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|
8. Usage                                                 |codecompanion-usage|
  -                                                     |codecompanion-usage-|
  - Action Palette                        |codecompanion-usage-action-palette|
  - Chat Buffer                              |codecompanion-usage-chat-buffer|
  - Agents and Tools                    |codecompanion-usage-agents-and-tools|
  - Editor Context                        |codecompanion-usage-editor-context|
  - Rules                                          |codecompanion-usage-rules|
  - Slash Commands                        |codecompanion-usage-slash-commands|
  - Command-Line Interface (CLI)|codecompanion-usage-command-line-interface-(cli)|
  - Events / Hooks                        |codecompanion-usage-events-/-hooks|
  - Inline Interaction                |codecompanion-usage-inline-interaction|
  - Prompt Library                        |codecompanion-usage-prompt-library|
  - User Interface                        |codecompanion-usage-user-interface|
  - Workflows                                  |codecompanion-usage-workflows|
9. 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 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
-  Integrates Neovim with LLMs and Agents in the CLI
-  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>, Cline CLI <https://docs.cline.bot/home>, Codex <https://openai.com/codex>, Copilot CLI <https://github.com/features/copilot/cli>, Gemini CLI <https://github.com/google-gemini/gemini-cli>, Goose <https://block.github.io/goose/>, Cursor CLI <https://cursor.com/docs/cli/overview>, Kilo Code <https://kilo.ai>, Kimi CLI <https://github.com/MoonshotAI/kimi-cli>, Kiro <https://kiro.dev/cli/>, Mistral Vibe <https://github.com/mistralai/mistral-vibe> and OpenCode <https://opencode.ai>
-  User contributed and supported |codecompanion-configuration-adapters-http-community-adapters|
-  Support for |codecompanion-model-context-protocol|
-  |codecompanion-usage-inline.html|, code creation and refactoring
-  |codecompanion-usage-chat-buffer-editor-context|, |codecompanion-usage-chat-buffer-slash-commands|, |codecompanion-usage-chat-buffer-agents-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
-  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|, Editor Context 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
- Cline CLI (`cline_cli`)
- 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>
- DeepSeek (`deepseek`) - Requires an API key
- Gemini (`gemini`) - Requires an API key
- 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
- HuggingFace (`huggingface`) - Requires an API key
- Kilo Code (`kilocode`) - Requires an API key
- Kimi (`kimi`) - Moonshot's Kimi K2 family; requires an API key
- Kimi CLI (`kimi_cli`) - Requires an API key
- Mistral AI (`mistral`) - Requires an API key or a Le Chat Pro subscription
- 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-editor-context|,
|codecompanion-usage-chat-buffer-slash-commands| and
|codecompanion-usage-chat-buffer-agents-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*

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 Agent or LLM from within CodeCompanion.
There are five main types of interactions:

- **Chat** - A chat buffer where you can converse with an LLM (`:CodeCompanionChat`)
- **CLI** - A terminal wrapper around agent CLI tools such a Claude Code or Opencode (`:CodeCompanionCLI`)
- **Inline** - An inline interaction 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


SETUP                                    *codecompanion-getting-started-setup*


CHAT AND INLINE ~


  [!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|.
  |codecompanion-configuration-adapters-acp| are only supported for the chat
  interaction.
The Chat Buffer is where you can converse with an LLM from within a Neovim
buffer. It operates on a single response per turn basis. The inline interaction
enables an LLM to write code directly into a Neovim buffer.

The |codecompanion-usage-chat-buffer-| and |codecompanion-usage-inline|
interactions need an adapter to function. In CodeCompanion terminology, an
adapter is the connection between Neovim and an LLM or agent. CodeCompanion has
two `types` of adapters; HTTP adapters which connect you to an LLM via it's API
and ACP adapters which connect you to an agent via the Agent Client Protocol
<https://agentclientprotocol.com>. CodeCompanion has a number of built-in
adapters
<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/config.lua>
that you can leverage and you can find more details in the respective
|codecompanion-configuration-adapters-http| and
|codecompanion-configuration-adapters-acp| sections of the documentation.

To set an adapter:

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

**Setting an API Key**

Because most LLMs require an API key, you'll need to share that with the
adapter. By default, the built-in 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 set/change the API key by using the `extend` function:

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


CLI ~

The CLI interaction allows you to interact with agents that operate in the
command-line like Claude Code and Opencode. To use CodeCompanion with a CLI
agent, you'll need to configure an agent first:

>lua
    require("codecompanion").setup({
      interactions = {
        cli = {
          agent = "claude_code",
          agents = {
            claude_code = {
              cmd = "claude",
              args = {},
              description = "Claude Code CLI",
              provider = "terminal",
            },
          },
        },
      },
    })
<

In the example above, we're setting up Claude Code in the `agents` table,
specifying the command to run it. Then we're setting it as the default CLI
interaction with `agent = "claude_code"`.


USAGE                                    *codecompanion-getting-started-usage*

The below section has been curated from the lengthier usage documentation to
give you a quick overview of how each feature works.


CHAT ~

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 `Editor Context` and `Slash
Commands` in the chat buffer.

**Editor Context**

`Editor Context`, accessed via `#` (by default), contain data about the present
state of Neovim. You can find a list of available editor context,
|codecompanion-usage-chat-buffer-editor-context|. The buffer editor context
will automatically link a buffer to the chat buffer, by default, updating the
LLM when the buffer changes.

You can use them in your prompts 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 `/` (by default), 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 `@` (by default), 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-agents-tools-available-tools|.

You can use them in your prompts like:

>
    Can you use @{grep_search} to find occurrences of "hello world"
<


CLI ~

Running `:CodeCompanionCLI` will open a new CLI interaction. Running
`:CodeCompanionCLI <your prompt>` will send the prompt to the last CLI
interaction (or create a new one). You can also run `:CodeCompanionCLI Ask` to
use a rich prompt input field complete with |codecompanion--editor-context|.
Save with `:w` to send the prompt to the agent, or `:w!` to send and
auto-submit it.

Adding `!` to the command (e.g. `:CodeCompanionCLI! <prompt>`) will auto-submit
the prompt and keep your cursor in the current buffer. You can also specify
which agent to use with `:CodeCompanionCLI agent=<agent name>`.


INLINE ~


  [!NOTE] The diff provider in the video is mini.diff
  <https://github.com/echasnovski/mini.diff>
Run `:CodeCompanion your prompt` to call the inline interaction. The
interaction will evaluate the prompt and either write code or open a chat
buffer. You can also make a visual selection and call the inline interaction.
To send additional context alongside your prompt, you can leverage
|codecompanion-usage-inline-editor-context| 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


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 ~

The plugin has five core commands:

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

However, there are multiple options available:

- `CodeCompanion <prompt>` - Prompt the inline interaction
- `CodeCompanion adapter=<adapter> <prompt>` - Prompt the inline interaction 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
- `CodeCompanionCLI` - Open a new CLI interaction
- `CodeCompanionCLI <prompt>` - Send a prompt to the last CLI interaction (or create a new one)
- `CodeCompanionCLI! <prompt>` - Send and auto-submit a prompt, keeping focus in the current buffer
- `CodeCompanionCLI agent=<agent> <prompt>` - Start a new CLI interaction with a specific agent
- `CodeCompanionCLI Ask` - Open the rich input buffer for CLI prompts


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

For an optimum plugin workflow, the author recommends 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. Architecture                                   *codecompanion-architecture*

This section of the documentation covers architectural concepts and design
principles that underpin CodeCompanion's functionality.

This is not mandatory reading for users of CodeCompanion. It may be of interest
to those who are looking to understand some of the technical details of how
CodeCompanion works, or those who are looking to contribute to the project.


HOW CONTEXT IS MANAGED     *codecompanion-architecture-how-context-is-managed*

One of the limitations of working with LLMs is that of context, as they have a
finite window with which they can respond to a user's ask. That is, there's
only a certain amount of data that LLMs can reference in order to generate a
response. To equate this to human terms, it can be thought of as working memory
<https://en.wikipedia.org/wiki/Working_memory> and it varies greatly depending
on what model you're using. The context window is measured in tokens
<https://platform.claude.com/docs/en/about-claude/glossary#tokens>.

When a user breaches the context window, the conversation **ends** and it
**cannot** continue. This can be hugely inconvenient in the middle of a coding
session and potentially time consuming to recover from. CodeCompanion has
context awareness which means it can prevent this from happening by taking
**preventative** action.


IN THE CHAT BUFFER ~


  [!NOTE] CodeCompanion enables context management by default
If you're using the `openai_responses` or `anthropic` adapters, then
CodeCompanion will use their native server-side compaction capabilities. Please
see their respective documentation here
<https://developers.openai.com/api/docs/guides/compaction> and here
<https://platform.claude.com/docs/en/build-with-claude/compaction> for more
information.

To be updated…

Firstly, CodeCompanion manages context by paying close attention to the number
of tokens in the |codecompanion-usage-chat-buffer-index|, matching them against
a defined trigger threshold in your config, which can be
|codecompanion-configuration-chat-buffer-context-management|.


==============================================================================
5. ACP                                                     *codecompanion-acp*

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.


IMPLEMENTATION                              *codecompanion-acp-implementation*

CodeCompanion provides comprehensive support for the ACP specification:

  ------------------------------------------------------------------------
  Feature Category               Supported                 Details
  ------------------------------ ------------------------- ---------------
  Core Protocol                  ✅                        JSON-RPC 2.0,
                                                           streaming
                                                           responses,
                                                           message
                                                           buffering

  Authentication                 ✅                        Multiple auth
                                                           methods,
                                                           adapter-level
                                                           hooks

  Content Types                  ✅                        Text, images,
                                                           embedded
                                                           resources

  File System                    ✅                        Read/write text
                                                           files with line
                                                           ranges

  MCP Integration                ✅                        Stdio, HTTP,
                                                           and SSE
                                                           transports

  Permissions                    ✅                        Interactive UI
                                                           with diff
                                                           preview for
                                                           tool approval

  Session Management             ✅                        Create, list,
                                                           load, and
                                                           restore
                                                           sessions with
                                                           state tracking

  Session Modes                  ✅                        Mode switching

  Session Models                 ✅                        Select specific
                                                           models

  Tool Calls                     ✅                        Content blocks,
                                                           file diffs,
                                                           status updates

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

  Terminal Operations            ❌                        Agent has
                                                           access to a
                                                           Neovim terminal
  ------------------------------------------------------------------------

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 TYPES ~

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

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.


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.


SESSION RESUME ~

If an agent supports the `session/list` capability, you can resume a previous
session using the `/resume` slash command in a fresh chat buffer. This calls
`session/list` to discover previous sessions, then `session/load` to restore
the selected session's conversation history into the chat buffer. See
|codecompanion-usage-chat-buffer-slash-commands-resume| for usage details.


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.


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.


PROTOCOL VERSION                          *codecompanion-acp-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.


CURRENT LIMITATIONS                    *codecompanion-acp-current-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 can't be sent or received


SEE ALSO                                          *codecompanion-acp-see-also*

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


==============================================================================
6. MCP                                                     *codecompanion-mcp*

CodeCompanion implements the Model Context Protocol (MCP)
<https://modelcontextprotocol.io> to enable you to connect the plugin to
external systems and applications. The plugin only implements a subset of the
full MCP specification, focusing on the features that enable developers to
enhance their coding experience.


USAGE                                                *codecompanion-mcp-usage*

To use MCP servers within CodeCompanion, refer to the
|codecompanion-usage-chat-buffer-agents-tools-mcp| section in the chat buffer
usage section of the documentation.

If |codecompanion-configuration-mcp-enabling-servers|, the servers will be
started when you open a chat buffer for the first time. However, you can use
the |codecompanion-usage-chat-buffer-slash-commands-mcp| to start or stop
servers manually.


IMPLEMENTATION                              *codecompanion-mcp-implementation*

  ----------------------------------------------------------------------------
  Feature Category          Supported   Details
  ------------------------- ----------- --------------------------------------
  Transport: Stdio          ✅          

  Transport: Streamable     ❌          
  HTTP                                  

  Basic: Cancellation       ✅          Timeout and user can cancel manually

  Basic: Progress           ❌          

  Basic: Task               ❌          

  Client: Roots             ✅          Disabled by default

  Client: Sampling          ❌          

  Client: Elicitation       ❌          

  Server: Completion        ❌          

  Server: Pagination        ✅          

  Server: Prompts           ❌          

  Server: Resources         ❌          

  Server: Tools             ✅          Currently only supports Text Content

  Server: Tool list changed ❌          
  notification                          
  ----------------------------------------------------------------------------

PROTOCOL VERSION                          *codecompanion-mcp-protocol-version*

CodeCompanion currently supports MCP version **2025-11-25**.


SEE ALSO                                          *codecompanion-mcp-see-also*

- Model Context Protocol Specification <https://modelcontextprotocol.io/specification/2025-11-25> - Official MCP documentation


==============================================================================
7. Configuration                                 *codecompanion-configuration*

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.

- The Super Diff has now been removed from CodeCompanion (#2600 <https://github.com/olimorris/codecompanion.nvim/pull/2600>)
- CodeCompanion now only supports a built-in diff which is enabled by default (#2600 <https://github.com/olimorris/codecompanion.nvim/pull/2600>), dropping support for Mini.Diff
- The `full_stack_dev` group has been renamed to |codecompanion-usage-chat-buffer-agents-tools-agent| (#2786 <https://github.com/olimorris/codecompanion.nvim/pull/2786>)
- The `next_edit_suggestion` and `list_code_usages` tools have been removed


ADAPTERS

- For the Claude Code adapter to work, you'll need to ensure you have Zed's claude-agent-acp <https://github.com/zed-industries/claude-agent-acp> adapter installed. This has been renamed from `claude-code-acp` in recent weeks (#2779 <https://github.com/olimorris/codecompanion.nvim/pull/2779>)


CONFIG

- Diff keymaps have moved from `interactions.inline.keymaps` to `interactions.shared.keymaps` (#2600 <https://github.com/olimorris/codecompanion.nvim/pull/2600>)
- All diff config has moved to `display.diff` (#2600 <https://github.com/olimorris/codecompanion.nvim/pull/2600>)
- `variables` have been renamed to `editor_context` and the config paths are now `interactions.chat.editor_context` and `interactions.inline.editor_context` (#2719 <https://github.com/olimorris/codecompanion.nvim/pull/2719>)
- Across `editor context`, `slash commands` and `tools`, `callback` has been replaced by `path` for string values (module paths and file paths). `callback` is still used for function values, however


PROMPT LIBRARY

- The location of rules within a prompt library item has changed from `opts.rules` to `rules`:

>markdown
    ---
    name: Oli's test workflow
    strategy: chat
    description: Workflow test prompt
    rules:
      - test_rule
    ---
<


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, `adapters.[acp|http].opts.show_defaults` has been renamed to `adapters.[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>)

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


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.


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


SETTING A 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",
        },
      },
    }),
<


SETTING DEFAULT SESSION CONFIG OPTIONS ~

The ACP specification has recently added support for session config options
<https://agentclientprotocol.com/protocol/session-config-options>. These are
lists of configuration options that agents can share with CodeCompanion at the
start of a session such as models, reasoning levels, and more.


MODELS

There are numerous was you can set a model in your config and it differs
significantly from other session config options because of how CodeCompanion
integrates adapters and models into the chat interaction.



OTHERS

To set any other session config option, you can pass them in the
`defaults.session_config_options` table:

`lua {6-11} require("codecompanion").setup({ adapters = { acp = { codex =
function() return require("codecompanion.adapters").extend("codex", { defaults
= { session_config_options = { mode = "Full Access", thought_level = "Xhigh",
}, }, }) end, } }, }),`

To find out what the available session config options are for a specific
adapter you can open the |codecompanion-usage-chat-buffer--debug-window| in the
chat buffer.


MCP SERVERS ~

Some ACP adapters support
<https://agentclientprotocol.com/protocol/session-setup#mcp-servers> connecting
to Model Client Protocol (MCP) servers. If you've defined
|codecompanion-configuration-mcp|, then CodeCompanion can automatically connect
to those servers when initializing the adapter.

To enable this, set `inherit_from_config` in the ACP adapter's
`defaults.mcpServers` field:

>lua
    require("codecompanion").setup({
      adapters = {
        acp = {
          claude_code = function()
            return require("codecompanion.adapters").extend("claude_code", {
              defaults = {
                mcpServers = "inherit_from_config",
              },
            })
          end,
        },
      },
    })
<


  [!NOTE] CodeCompanion does not display the MCP servers in the chat buffer's
  context when used with an ACP adapter.
Alternatively, you can configure MCP servers manually. In the below example,
we're configuring Claude Code to connect to the sequential-thinking
<https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking>
server via stdio:

>lua
    require("codecompanion").setup({
      adapters = {
        acp = {
          claude_code = function()
            return require("codecompanion.adapters").extend("claude_code", {
              defaults = {
                mcpServers = {
                  {
                    name = "sequential-thinking",
                    command = "npx",
                    args = { "-y", "@modelcontextprotocol/server-sequential-thinking" },
                    env = {},
                  },
                },
              },
            })
          end,
        },
      },
    })
<

You can also disable this by setting `mcp.opts.acp_enabled = false` in your
configuration.


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-agent-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: CLINE CLI ~

To use Cline CLI <https://cline.bot/cli> within CodeCompanion, you'll need to
take the following steps:

1. Install <https://docs.cline.bot/getting-started/installing-cline#cli> Cline CLI.
2. Authenticate by running `cline auth`.
3. Select the `cline_cli` adapter in your chat buffer


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: COPILOT CLI ~

Install Copilot CLI
<https://docs.github.com/en/copilot/how-tos/copilot-cli/set-up-copilot-cli/install-copilot-cli>
as per the instructions and then in the terminal run `copilot` and ensure that
you're authenticated.


SETUP: CURSOR CLI ~

To use Cursor <https://www.cursor.com/> within CodeCompanion, you'll need to
take the following steps:

1. Install `agent` as per the Cursor CLI documentation <https://cursor.com/docs/cli/overview>
2. Authenticate by running `agent login` in your terminal
3. Select the `cursor_cli` adapter in your chat buffer


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: KILO CODE ~

To use Kilo Code <https://kilo.ai> in CodeCompanion, ensure you've followed
their documentation to install
<https://kilo.ai/docs/getting-started/installing#cli> and configure
<https://kilo.ai/docs/getting-started/setup-authentication#cli> it. Then ensure
that in your chat buffer you select the `kilocode` adapter.

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

>json
    {
        "$schema": "https://kilo.ai/config.json",
        "model": "kilo/kilo-auto/free",
    }
<


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 `/login` to
configure your API key. Then ensure that in your chat buffer you select the
`kimi_cli` adapter.


SETUP: KIRO CLI ~

Install Kiro cli <https://kiro.dev/docs/cli/> as per their instructions. Then
open it and login (if installation doesn't already prompt you to login). the
codecompanion adapter will execute `kiro-cli acp`, make sure to have it
available on your PATH.


SETUP: MISTRAL VIBE ~

To use Mistral Vibe <https://github.com/mistralai/mistral-vibe> in
CodeCompanion, ensure you've followed their documentation to install
<https://github.com/mistralai/mistral-vibe>. Then run `vibe --setup` in your
CLI in order to setup your API key. Then ensure that in your chat buffer you
select the `mistral_vibe` 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 PARAMETERS (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:



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


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.


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"`).


DISABLING COMPACTION ~

If you use the `anthropic` or `openai_responses` adapters, then the plugin will
look to use their server-side compaction capabilities to manage context. If you
want to disable this:

>lua
    require("codecompanion").setup({
      adapters = {
        http = {
          anthropic = function()
            return require("codecompanion.adapters").extend("anthropic", {
              opts = {
                compaction = false,
              },
            })
          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 = {
        http = {
          opts = {
            show_presets = false,
          },
        },
      },
    })
<


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


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


KIMI (MOONSHOT)

CodeCompanion ships a built-in `kimi` adapter for Moonshot's Kimi K2 family
<https://platform.kimi.ai/docs/models>. Unlike the generic `openai_compatible`
adapter, it captures and round-trips Kimi's `reasoning_content` so the
K2-thinking variants (`kimi-k2-thinking`, `kimi-k2-thinking-turbo`, and the
`can_reason` K2 generals such as `kimi-k2.6`) work correctly with tool calling
— without it, the second turn of a tool-using chat fails with `"thinking is
enabled but reasoning_content is missing in assistant tool call message"`.

For the default setup, simply set `MOONSHOT_API_KEY` and pick the adapter:

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

To override the API-key source, swap models, or disable thinking mode:

>lua
    require("codecompanion").setup({
      adapters = {
        http = {
          kimi = function()
            return require("codecompanion.adapters").extend("kimi", {
              env = {
                -- Use the 1Password CLI instead of an environment variable:
                api_key = "cmd:op read op://API/Kimi/credential --no-newline",
                -- Region override (Moonshot has separate endpoints, e.g. for China):
                -- url = "https://api.moonshot.cn",
              },
              schema = {
                model = { default = "kimi-k2.6" },
                -- Set to false to disable thinking mode (e.g. for the K2-general
                -- non-reasoning preview models, where `think` is a no-op):
                think = { default = true },
              },
            })
          end,
        },
      },
    })
<


  [!IMPORTANT] The K2-thinking models pin `temperature` to `1` and `top_p` to
  `0.95`; the adapter's defaults match. Overriding either with another value will
  yield a 400 from the API. Other K2 models accept the full ranges.

OLLAMA (REMOTELY)

The simplest way to connect to a remote Ollama instance is to set the
`OLLAMA_HOST` environment variable (the same variable used by the Ollama CLI):

>bash
    export OLLAMA_HOST="http://192.168.1.100:11434"
<

Alternatively, configure it directly in your setup using `extend()`. If you
need authentication, 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:

- DashScope <https://github.com/olimorris/codecompanion.nvim/discussions/2239>
- Fireworks.ai <https://github.com/olimorris/codecompanion.nvim/discussions/693>
- InceptionLabs - Mercury 2 <https://github.com/olimorris/codecompanion.nvim/discussions/2867>
- Nvidia NIM <https://github.com/olimorris/codecompanion.nvim/discussions/2810>
- OpenRouter <https://github.com/olimorris/codecompanion.nvim/discussions/1013>
- Venice.ai <https://github.com/olimorris/codecompanion.nvim/discussions/972>
- Vertex AI <https://github.com/viespejo/cc-adapter-vertex-ai.nvim>

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.


COMPLETION ~

By default, CodeCompanion will determine if you have one of blink.cmp
<https://github.com/saghen/blink.cmp>, nvim-cmp
<https://github.com/hrsh7th/nvim-cmp>, or coc.nvim
<https://github.com/neoclide/coc.nvim> installed, selecting it as the default
provider. Failing this, the default completion engine will be used.

You can override this with:

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


PREFIXES

You can also customize the prefixes that trigger completions for
|codecompanion-usage-chat-buffer-editor-context|,
|codecompanion-usage-chat-buffer-slash-commands|, and
|codecompanion-usage-chat-buffer-agents-tools|:

>lua
    require("codecompanion").setup({
      opts = {
        triggers = {
          acp_slash_commands = "\\",
          editor_context = "#",
          slash_commands = "/",
          tools = "@",
        },
      },
    })
<


CALLBACKS ~

Callbacks allow you to hook into the chat buffer's lifecycle and react to
specific events. They are registered per-chat and receive the chat instance as
the first argument.


AVAILABLE EVENTS

  ---------------------------------------------------------------------------------------------------------------
  Event                   Description                  Extra Args
  ----------------------- ---------------------------- ----------------------------------------------------------
  on_created              Chat buffer has been created -

  on_before_submit        Before the message is sent   { adapter }
                          to the LLM. Return false to  
                          prevent submission           

  on_submitted            After the message has been   { payload }
                          sent to the LLM              

  on_checkpoint           Fires at safe points during  { adapter, estimated_tokens, messages, reported_tokens }
                          the chat lifecycle. Messages 
                          are mutable                  

  on_tool_output          Before tool output is added  { tool, for_llm, for_user }
                          to the chat. Mutate          
                          args.for_llm/args.for_user   
                          to modify                    

  on_ready                Chat is ready for the next   -
                          turn (after LLM response)    

  on_completed            LLM response has been fully  { status }
                          processed                    

  on_cancelled            Request has been             -
                          stopped/cancelled            

  on_closed               Chat buffer has been closed  -
  ---------------------------------------------------------------------------------------------------------------

REGISTERING CALLBACKS

Callbacks can be registered in two ways:



BACKGROUND CALLBACKS

Callbacks can also be registered in the config via
`interactions.background.chat.callbacks`. These run asynchronously using a
separate background LLM instance and are suited for fire-and-forget tasks like
generating chat titles. Unlike the callbacks above, they cannot return values
to influence the chat's behavior:

>lua
    require("codecompanion").setup({
      interactions = {
        background = {
          chat = {
            callbacks = {
              ["on_ready"] = {
                actions = {
                  "interactions.background.builtin.chat_make_title",
                },
                enabled = true,
              },
            },
            opts = {
              enabled = true,
            },
          },
        },
      },
    })
<

The `actions` table contains module paths that are resolved and executed
asynchronously. See the |codecompanion-usage-chat-buffer--generating-titles|
section for a working example.


PREVENTING SUBMISSION

The `on_before_submit` callback can return `false` to prevent a message from
being sent to the LLM. When cancelled, `chat:restore()` is called
automatically, which resets the buffer to an editable state and fires a
`CodeCompanionChatRestored` event. The user's message remains in the buffer so
it can be edited and resubmitted.

This is useful for implementing safeguards such as token/context limit checks:

>lua
    vim.api.nvim_create_autocmd("User", {
      pattern = "CodeCompanionChatCreated",
      callback = function(args)
        local chat = require("codecompanion").buf_get_chat(args.data.bufnr)
        chat:add_callback("on_before_submit", function(c, data)
          local token_count = my_tokenizer.count(c.messages)
          local context_limit = 128000
    
          if token_count > context_limit then
            vim.notify(
              string.format("Token count (%d) exceeds context limit (%d)", token_count, context_limit),
              vim.log.levels.WARN
            )
            return false
          end
        end)
      end,
    })
<

The `info` table passed to `on_before_submit` contains:

- `adapter` - A safe copy of the current adapter (with name, model, features, schema, etc.)


TRUNCATING TOOL OUTPUT

The `on_tool_output` callback fires before a tool's output is added to the
chat. The `args` table contains `tool` (the tool name), `for_llm` (the content
sent to the LLM) and `for_user` (what's shown in the buffer). Mutate
`args.for_llm` and/or `args.for_user` to modify the output:

>lua
    vim.api.nvim_create_autocmd("User", {
      pattern = "CodeCompanionChatCreated",
      callback = function(args)
        local chat = require("codecompanion").buf_get_chat(args.data.bufnr)
        chat:add_callback("on_tool_output", function(c, data)
          local tokens = require("codecompanion.utils.tokens")
          local max_tokens = 10000
    
          if data.for_llm and tokens.calculate(data.for_llm) > max_tokens then
            -- Trim to roughly max_tokens worth of characters
            local max_chars = max_tokens * 6
            data.for_llm = data.for_llm:sub(1, max_chars) .. "\n\n[Output truncated]"
            data.for_user = data.for_llm
            vim.notify(
              string.format("Tool output from '%s' truncated (~%d tokens)", data.tool, max_tokens),
              vim.log.levels.WARN
            )
          end
        end)
      end,
    })
<


CHECKPOINTS

The `on_checkpoint` callback fires at various safe points during the chat
lifecycle, giving you the ability to inspect and mutate the message stack
before the chat continues. It fires:

- **Before submit** — Before a request is sent to an LLM
- **After tool output** — Once tools in the current batch have finished, ensuring no orphaned tool calls
- **After a response with no tools** — When the LLM responds, minus any tool calls

The `data` table contains:

- `adapter` — a safe copy of the current adapter (includes `meta.context_window` for HTTP adapters)
- `estimated_tokens` — client-side token estimate across all messages
- `messages` — a **mutable reference** to the chat's message stack. Changes made here persist back to the chat
- `reported_tokens` — server-reported token count (if available from the adapter)

This is useful for monitoring context window usage and compacting the message
stack:

>lua
    vim.api.nvim_create_autocmd("User", {
      pattern = "CodeCompanionChatCreated",
      callback = function(args)
        local chat = require("codecompanion").buf_get_chat(args.data.bufnr)
        chat:add_callback("on_checkpoint", function(c, data)
          local context_window = data.adapter.meta and data.adapter.meta.context_window
          if not context_window then
            return
          end
    
          local usage = data.estimated_tokens / context_window
          if usage > 0.8 then
            vim.notify(
              string.format("Context window %.0f%% full", usage * 100),
              vim.log.levels.WARN
            )
            -- Compact data.messages in-place here
          end
        end)
      end,
    })
<


CONTEXT MANAGEMENT ~

CodeCompanion can manage context in the chat buffer to try and prevent
breaching the LLM's context window. It can be enabled with:


CodeCompanion makes use of a trigger, a threshold at which the context
management begins. You can specify a `trigger` as either a decimal
(representing a percentage of the context window) or an integer (representing a
token count). When the chat buffer reaches the defined trigger, preventative
action is taken by CodeCompanion. You can read more in the
|codecompanion-architecture-manage-context| section.



DIFF ~



CodeCompanion has a built-in diff engine that's leveraged throughout the
plugin. If you utilize the `insert_edit_into_file` tool or use an ACP adapter,
then the plugin will update files and buffers, displaying the changes in a
floating window.

For small changes, the diff is shown directly in the chat buffer. This can be
controlled by `threshold_for_chat`, which corresponds to the size of the diff
in terms of changed lines. For larger changes, the diff will automatically open
in a floating window when the chat buffer is active. Or, you will be prompted
to view the diff manually (`gv` by default).

There are a number of configuration options available to you:



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.


For the chat interaction, 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`.

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

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


PROMPT DECORATOR ~

It can be useful to decorate your prompt with additional information, prior to
sending to an LLM. 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 `/` by default) 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 `@` (by default), 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 = {
                  "run_command",
                  "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
                  ignore_system_prompt = false, -- When true, remove the chat's default system prompt
                  ignore_tool_system_prompt = false, -- When true, remove the default tool system prompt
                },
              },
            },
          },
        },
      },
    })
<

When users introduce the group, `my_group`, in the chat buffer, it can call the
tools you listed (such as `run_command`) to perform tasks on your code. The
`system_prompt` field allows you to give the LLM specific instructions for how
to use the group's tools and can be a string or a function that receives the
group config table and a |codecompanion-configuration-system-prompt| (with
`language`, `date`, `nvim_version`, `os`, etc.).

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. See the |codecompanion-usage-chat-buffer-agents-tools-approvals|
section for more information.



AUTO SUBMIT (RECURSION)

When a tool executes, it can be useful to automatically send its output back to
the LLM. This is turned on by default and can be configured with:

`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 turn off.

COMPLETION

By default, CodeCompanion looks to use the fantastic blink.cmp
<https://github.com/Saghen/blink.cmp> plugin to complete editor context, 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--messages|. 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 editor context and slash commands) 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?
        },
      },
    })
<


EDITOR CONTEXT ~

Editor context
<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/config.lua#L90>
can be a inserted into the chat buffer using `#` (by default). It provides
contextual code or information about the current Neovim state. For instance,
the built-in `#{buffer}` editor context sends the current buffer's contents to
the LLM.

You can even define your own context:

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


SYNCING

Neovim buffers can be
|codecompanion-usage-chat-buffer-editor-context-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` editor context, you can
set the `default_params` option to either `diff` or `all`:

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


COMMAND-LINE INTERFACE (CLI)*codecompanion-configuration-command-line-interface-(cli)*

By default, CodeCompanion uses the `terminal` provider for CLI interactions,
which runs agents in a Neovim terminal buffer. However, the CLI system is
flexible and allows you to define custom agents and providers to suit your
workflow.


AGENTS ~

To use the CLI interaction, you need to define at least one agent in your
configuration:

>lua
    require("codecompanion").setup({
      interactions = {
        cli = {
          agent = "claude_code",
          agents = {
            claude_code = {
              cmd = "claude",
              args = {},
              description = "Claude Code CLI",
              provider = "terminal",
            },
          },
        },
      },
    })
<

The `agent` field sets the default agent. You can override it per-command with
`:CodeCompanionCLI agent=<name>`.


AGENT OPTIONS

  Option        Type     Description
  ------------- -------- ------------------------------------------------
  cmd           string   The command to run (e.g. "claude", "codex")
  args          table    Arguments to pass to the command
  description   string   Description shown in the action palette
  provider      string   Which provider to use (defaults to "terminal")

MULTIPLE AGENTS

You can define multiple agents and switch between them:

>lua
    require("codecompanion").setup({
      interactions = {
        cli = {
          agent = "claude_code",
          agents = {
            claude_code = {
              cmd = "claude",
              args = {},
              description = "Claude Code CLI",
            },
            codex = {
              cmd = "codex",
              args = {},
              description = "OpenAI Codex CLI",
            },
          },
        },
      },
    })
<

Then use `:CodeCompanionCLI agent=codex <prompt>` to use a specific agent.


PROVIDERS ~

Providers determine how the CLI agent is run. The built-in `terminal` provider
uses a Neovim terminal buffer with `jobstart()`:

>lua
    require("codecompanion").setup({
      interactions = {
        cli = {
          providers = {
            terminal = {
              path = "interactions.cli.providers.terminal",
              description = "Terminal CLI provider",
            },
          },
        },
      },
    })
<


CUSTOM PROVIDERS

You can create custom providers and reference them by module path or file path:

>lua
    require("codecompanion").setup({
      interactions = {
        cli = {
          providers = {
            my_provider = {
              -- Can be a codecompanion module, a Lua module, or a file path
              path = "my_custom.cli_provider",
              description = "My custom CLI provider",
            },
          },
          agents = {
            my_agent = {
              cmd = "my-cli",
              args = {},
              provider = "my_provider",
            },
          },
        },
      },
    })
<

If an agent's `provider` field doesn't match any entry in the `providers`
table, the `terminal` provider is used as a fallback.


KEYMAPS ~

The CLI buffer supports keymaps for navigating between interactions:

>lua
    require("codecompanion").setup({
      interactions = {
        cli = {
          keymaps = {
            next_chat = {
              modes = { n = "}" },
              callback = "keymaps.next_chat",
              description = "[Nav] Next interaction",
            },
            previous_chat = {
              modes = { n = "{" },
              callback = "keymaps.previous_chat",
              description = "[Nav] Previous interaction",
            },
          },
        },
      },
    })
<


OPTIONS ~

There are a number of options available for CLI interactions:

>lua
    require("codecompanion").setup({
      interactions = {
        cli = {
          opts = {
            auto_insert = true, -- Enter insert mode when focusing the CLI terminal
            reload = true, -- Reload buffers when an agent modifies files on disk
          },
        },
      },
    })
<

  -----------------------------------------------------------------------
  Option            Type              Default           Description
  ----------------- ----------------- ----------------- -----------------
  auto_insert       boolean           true              Automatically
                                                        enter insert mode
                                                        when the CLI
                                                        terminal is
                                                        focused

  reload            boolean           true              Watches the cwd
                                                        for file changes
                                                        and runs
                                                        :checktime to
                                                        reload buffers
  -----------------------------------------------------------------------

USER INTERFACE (UI) ~

The CLI window inherits its layout from `display.chat.window` by default. You
can override specific options via `display.cli.window`:

>lua
    require("codecompanion").setup({
      display = {
        cli = {
          window = {
            layout = "vertical",
            width = 0.4,
            height = 0.6,
            opts = {
              list = false,
            },
          },
        },
      },
    })
<

Any options set in `display.cli.window` are merged on top of the chat window
defaults. This means you only need to specify what you want to change.

You can also pass `width` and `height` overrides via the Lua API:

>lua
    require("codecompanion").cli("fix the tests", {
      width = 0.5,
      height = 0.8,
    })
<


INLINE INTERACTION            *codecompanion-configuration-inline-interaction*


  [!IMPORTANT] Only **http** adapters are supported for the inline interaction.
CodeCompanion provides an `inline` interaction for quick, direct editing of
your code. Unlike the chat buffer, the inline interaction 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
interaction. 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 interaction 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",
            },
          },
        },
      },
    })
<


EDITOR CONTEXT ~

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

>lua
    require("codecompanion").setup({
      interactions = {
        inline = {
          editor_context = {
            ["my_new_context_item"] = {
              ---@return string
              callback = "/Users/Oli/Code/my_context_item.lua",
              description = "My shiny new context item",
              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|tab|buffer
        },
      }
    })
<


DIFF ~

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


MCP SERVERS                          *codecompanion-configuration-mcp-servers*

In #2549 <https://github.com/olimorris/codecompanion.nvim/pull/2549>,
CodeCompanion added support for the Model Context Protocol (MCP)
<https://modelcontextprotocol.io>, an open-source standard for connecting AI
applications to external systems.

You can find out which parts of the protocol CodeCompanion has implemented on
the |codecompanion-model-context-protocol| page. Currently, you can leverage
MCP servers with |codecompanion-usage-chat-buffer-index|.


MCP SERVERS ~

You can give CodeCompanion knowledge of MCP servers via the `mcp.servers`
configuration option. This is a list of server definitions, each specifying how
to connect to an MCP server.


BASIC CONFIGURATION


In the environment variables example above, we're using 1Password CLI
<https://developer.1password.com/docs/cli/> tool to fetch the API key. However,
you can leverage CodeCompanion's built-in
|codecompanion-configuration-adapters-http-environment-variables| capabilities
to fetch the value from any source you like.


ROOTS


  [!IMPORTANT] The `roots` feature is a hint to MCP servers. Compliant servers
  use it to limit file system access, but CodeCompanion cannot enforce this. For
  untrusted servers, use isolation mechanisms like containers.
Roots <https://modelcontextprotocol.io/specification/2025-11-25/client/roots>
allow you to specify directories that the MCP server can access. By default,
roots are disabled for security reasons. You can enable them by adding a
`roots` field to your server configuration:



DEFAULT SERVERS ~

The `opts.default_servers` option controls which MCP servers are automatically
started with their tools added to the chat buffer. Servers not in the list can
be started on-demand via the `/mcp` slash command.



  [!NOTE] If `mcp_servers` are explicitly specified in a prompt library item,
  those take precedence and the `default_servers` logic is skipped for that chat
  buffer.

OVERRIDING TOOL BEHAVIOUR ~

An MCP server can expose multiple tools. For example, a "math" server might
provide `add`, `subtract`, `multiply`, and `divide` tools. You can override the
behaviour of individual tools using the `tool_overrides` configuration,
allowing you to customise options, output handling, system prompts, and
timeouts on a per-tool basis.

The `tool_overrides` field is a table where keys are the **MCP tool names**
(not the prefixed names used internally by CodeCompanion):



TOOL DEFAULTS

You can set default options for all tools by setting the `tool_defaults`
option. However, note that `tool_overrides` take precedence over them:

>lua
    require("codecompanion").setup({
      mcp = {
        servers = {
          ["math-server"] = {
            cmd = { "npx", "-y", "math-mcp-server" },
            tool_defaults = {
              require_approval_before = true,
            },
            -- Per-tool overrides take precedence over tool_defaults
            tool_overrides = {
              add = {
                opts = {
                  require_approval_before = false,
                },
              },
            },
          },
        },
      },
    })
<


OVERRIDE OPTIONS

Each tool override can include:

  ------------------------------------------------------------------------
  Option                Type            Description
  --------------------- --------------- ----------------------------------
  opts                  table           Tool options like
                                        require_approval_before,
                                        require_approval_after

  output                table           Custom output handlers (success,
                                        error, prompt, rejected,
                                        cancelled)

  system_prompt         string          Additional system prompt text for
                                        this tool

  timeout               number          Custom timeout in milliseconds for
                                        this tool

  enabled               boolean         Whether the tool is enabled
  ------------------------------------------------------------------------

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.
The files can be nested and symlinked.



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:



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

The format of the date can be changed in your config by altering the
`date_format` option:

>lua
    require("codecompanion").setup({
      interactions = {
        opts = {
          date_format = "%A, %d %B %Y", -- Example: "Monday, 01 January 2024"
        },
      },
    })
<


TOOL SYSTEM PROMPT ~

CodeCompanion also ships with a separate system prompt when
|codecompanion-usage-chat-buffer-agents-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 { ctx: CodeCompanion.SystemPrompt.Context, 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
      },
    }),
<


PER-PROJECT CONFIGURATION ~

Working across multiple projects, it can be useful to set different
CodeCompanion configurations.

The plugin allows you to specify a list of files which it will look for in the
current working directory. If any of the files are found, they will be loaded
and merged with the default configuration.

Alternatively, you can specify a directory as a key and the configuration as
the value.


File-based configuration must return a valid Lua table. For example:

>lua
    return {
      interactions = {
        chat = {
          adapter = {
            name = "copilot",
            model = "claude-sonnet-4.6",
          },
          tools = {
            opts = {
              default_tools = {
                "memory",
              },
            },
          },
        },
      },
    }
<


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


==============================================================================
8. Usage                                                 *codecompanion-usage*


                                                        *codecompanion-usage-*

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-agents-tools-files| tool, combined with
the |codecompanion-usage-chat-buffer-editor-context.html-buffer| editor context
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-agents-tools-run-command| 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 `@run_command` 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
`}`.


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>` in normal mode or `<C-CR>` in insert mode. This can of course be
changed as per the |codecompanion--keymaps| section.

New in `v19.12.0`, you can send a message to the LLM whilst it's executing tool
calls with the `btw` keymap which is triggered with `gm`. When safe to do so,
CodeCompanion will send the message to the LLM.


ACTION PALETTE ~

The chat buffer has its own `Action Palette` which can be accessed with
`:CodeCompanionActions` when in the chat buffer. This displays available
keymaps and slash commands and can be used to trigger them.


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


DEBUG WINDOW ~

Sometimes it's necessary to peek under the hood of the chat buffer to
understand what hyperparameters are being sent to the LLM, or what the message
history looks like. By pressing `gd`, you can open up a debug window which
contains all of the relevant information about the chat buffer, including the
message history, adapter settings and context items.


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. The keymaps
available to the user in normal mode are:

- `options`: `?` to display all available keymaps
- `send`: `<CR>|<C-s>` to send a message to the LLM
- `close`: `<C-c>` to close the chat buffer
- `stop`: `q` to stop the current request
- `change_adapter`: `ga` to change the adapter for the current chat
- `clear`: `gx` to clear the chat buffer's contents
- `copilot_stats`: `gS` to show copilot usage stats
- `btw`: `gm` type a message to the LLM whilst it's streaming
- `buffer_sync_all`: `gba` to sync the entire buffer on every turn
- `buffer_sync_diff`: `gbd` to sync only a buffers diff on every turn
- `codeblock`: `gc` to insert a codeblock in the chat buffer
- `debug`: `gd` to view/debug the chat buffer's contents
- `fold_code`: `gf` to fold any codeblocks in the chat buffer
- `goto_file_under_cursor`: `gR` to go to the file under cursor
- `next_chat`: `}` to move to the next chat
- `next_header`: `]]` to move to the next header
- `previous_chat`: `{` to move to the previous chat
- `previous_header`: `[[` to move to the previous header
- `regenerate`: `gr` to regenerate the last response
- `rules`: `gM` to clear all rules from the chat buffer
- `system_prompt`: `gs` to toggle the system prompt on/off
- `yank_code`: `gy` to yank the last codeblock in the chat buffer


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.


AGENTS AND TOOLS                        *codecompanion-usage-agents-and-tools*


  [!IMPORTANT] The built-in tools are for HTTP adapters only and not all LLMs
  support tool use. 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, by default.


  [!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|.


AGENTS / TOOL GROUPS ~

Tool groups combine multiple tools together, making them available to the LLM
in a single `@{group_name}` reference. CodeCompanion comes with two built-in
groups: `@{agent}` 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.


TURNING A GROUP INTO AN AGENT

Groups become agents when they provide their own `system_prompt`. Combined with
the `ignore_system_prompt` and `ignore_tool_system_prompt` opts, a group can
completely replace the default system prompts with its own tailored
instructions. This is how the built-in `@{agent}` group works.

When `system_prompt` is a function, it receives the group config as the first
argument and a |codecompanion-configuration-system-prompt| as the second,
giving access to `language`, `date`, `nvim_version`, `os` and more:

>lua
    groups = {
      ["my_agent"] = {
        description = "My custom agent",
        system_prompt = function(group, ctx)
          return string.format(
            "You are a coding agent. The date is %s. The user is on %s.",
            ctx.date,
            ctx.os
          )
        end,
        tools = { "read_file", "insert_edit_into_file", "run_command" },
        opts = {
          collapse_tools = true,
          ignore_system_prompt = true, -- Remove the chat's default system prompt
          ignore_tool_system_prompt = true, -- Remove the default tool system prompt
        },
      },
    },
<


AGENT

The `@{agent}` group is CodeCompanion's agent mode. It combines a curated set
of tools with its own system prompt, replacing the default chat and tool system
prompts. This gives the LLM clear instructions on how to act as an autonomous
coding agent.

It contains the following tools:

- |codecompanion-usage-chat-buffer-agents-tools-ask-questions|
- |codecompanion-usage-chat-buffer-agents-tools-create-file|
- |codecompanion-usage-chat-buffer-agents-tools-delete-file|
- |codecompanion-usage-chat-buffer-agents-tools-file-search|
- |codecompanion-usage-chat-buffer-agents-tools-get-changed-files|
- |codecompanion-usage-chat-buffer-agents-tools-get-diagnostics|
- |codecompanion-usage-chat-buffer-agents-tools-grep-search|
- |codecompanion-usage-chat-buffer-agents-tools-insert-edit-into-file|
- |codecompanion-usage-chat-buffer-agents-tools-read-file|
- |codecompanion-usage-chat-buffer-agents-tools-run-command|

You can use it with:

>md
    @{agent} Can we create a todo list app 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-agents-tools-create-file|
- |codecompanion-usage-chat-buffer-agents-tools-file-search|
- |codecompanion-usage-chat-buffer-agents-tools-get-changed-files|
- |codecompanion-usage-chat-buffer-agents-tools-grep-search|
- |codecompanion-usage-chat-buffer-agents-tools-insert-edit-into-file|
- |codecompanion-usage-chat-buffer-agents-tools-read-file|

You can use it with:

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


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
<


ASK_QUESTIONS


  [!NOTE] By default, this tool is hidden and is only accessible via the
  `@{agent}` tool group
This tool enables an LLM to ask clarifying questions before proceeding with a
task. It's useful when the LLM encounters ambiguous requirements, needs to
choose between implementation approaches, or wants to validate assumptions.
Questions can have predefined options (presented via `vim.ui.select`) or accept
free text input (via `vim.ui.input`):

>md
    @{agent} Can you refactor the authentication module?
<

The LLM may use this tool to ask which auth strategy you prefer before making
changes. The tool is limited to one call per response to prevent excessive
questioning.


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 matching file paths.

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


GET_DIAGNOSTICS


  [!WARNING] This tool relies on external language servers. It may be unreliable
  for certain filetypes.
This tool enables an LLM to retrieve LSP diagnostics for a given file. It
returns all diagnostic messages (errors, warnings, hints and information) along
with the relevant code lines. This is useful for understanding what issues
exist in a file before attempting to fix them:

>md
    Use @{get_diagnostics} to check for any issues in the current file
<

The tool accepts an optional `severity` parameter to filter diagnostics by
minimum severity level (`ERROR`, `WARNING`, `INFORMATION`, `HINT`).


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)


MEMORY


  [!IMPORTANT] For security, all memory operations are restricted to the
  `/memories` directory and any whitelisted paths
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
<


WHITELISTED PATHS

By default, the memory tool can only access files in `<cwd>/memories/`. You can
whitelist additional paths so the LLM can read and write to them. Each entry
maps a path on disk to a virtual prefix that the LLM uses:

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          tools = {
            ["memory"] = {
              opts = {
                whitelist = {
                  { path = "~/.dotfiles", as = "/dotfiles" },
                  { path = "/shared/notes", as = "/notes" },
                },
              },
            },
          },
        },
      },
    })
<

With this configuration, the LLM can use `/dotfiles/.zshrc` or `/notes/todo.md`
as paths in memory tool calls, just as it uses `/memories/file.txt`. Tilde
(`~`) is expanded automatically. Directory traversal protection applies to all
whitelisted paths.

You can also mount a single file. This is useful for a personal profile that
the LLM can learn from and update over time:

>lua
    whitelist = {
      { path = "~/.dotfiles/PERSONAL.md", as = "/personal" },
    },
<

The LLM can then view and edit it via `/personal`.


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.


RUN_COMMAND

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

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

>md
    Use @{run_command} 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)


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


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.


MCP ~

The MCP servers you've |codecompanion-configuration-mcp| in CodeCompanion
expose their own set of tools that you can use in the chat buffer. Once a
server has been started, the tools will be available to you and appear in the
completion menu, by typing `@`. They are prefixed with `mcp:`.


SECURITY ~

CodeCompanion takes security very seriously, especially in a world of agentic
code development. Tools that create or delete files validate that paths are
within the current working directory (cwd) to prevent unintended modifications
outside of your project. This ensures that the LLM can only work within the cwd
when executing destructive tools, minimizing 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 (`require_cmd_approval = true`). Taking the
`run_command` 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 `run_command` and
`delete_file` are excluded from this as they have `allowed_in_yolo_mode =
false` set.


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.

EDITOR CONTEXT                            *codecompanion-usage-editor-context*

Editor context allows you to dynamically insert Neovim context into your chat
messages using the `#{context}` 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 context through code completion, or type them manually.

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


BASIC USAGE ~

Editor context uses the `#{context}` syntax to dynamically insert content into
your chat, such as `#{buffer}`. Editor context is processed when you send your
message to the LLM.


  [!IMPORTANT] With the exception of `#{buffer}` and `#{buffers}`, editor context
  captures a point-in-time snapshot when your message is sent. If the underlying
  data changes (e.g. new diagnostics, a different quickfix list), simply use the
  context again in a new message to share the latest state.

#BUFFER ~


  [!NOTE] By default, CodeCompanion automatically applies the `{diff}` parameter
  to all buffers
The `#{buffer}` context 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 path
- `#{buffer:utils}` - Shares a file containing "utils" in the path


WITH PARAMETERS

**{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. This is the default option in CodeCompanion.

**{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.

Can be used in combination with targeting a specific buffer:

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


MULTIPLE BUFFERS


  [!NOTE] For selecting multiple buffers with more control, use the `/buffer`
  slash command.
>md
    Compare #{buffer:old_file.js} with #{buffer:new_file.js} and explain the differences.
<


#BUFFERS ~

The `buffers` context shares all currently open buffers with the LLM. Buffers
with excluded buftypes (such as `nofile`, `quickfix`, `prompt`, `popup`) and
filetypes (such as `codecompanion`, `help`, `terminal`) are automatically
filtered out.

>md
    #{buffers} can you explain what's going on in these files?
<


#DIAGNOSTICS ~


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

>md
    #{diagnostics} can you explain the LSP errors in this file and how to fix them?
<


#DIFF ~

The `diff` context shares the current git diff with the LLM, including both
staged and unstaged changes. This is useful for code review, generating commit
messages, or asking for feedback on your recent changes.

>md
    Sharing the latest git diff with you #{diff}
<


#MESSAGES ~

The `messages` context shares Neovim's message history (`:messages`) with the
LLM. This is useful when an error has been written to the message history and
you want to share it with the LLM for troubleshooting.

>md
    Can you explain the error I've just observed in Neovim? #{messages}
<


#QUICKFIX ~

The `quickfix` context shares the contents of the quickfix list with the LLM.
Files with diagnostics are formatted with smart grouping by Tree-sitter
symbols, while file-only entries show the full content. This is useful for
sharing compiler errors, search results, or LSP diagnostics across multiple
files.

>md
    The relevant output from my quickfix list has now been shared with you #{quickfix}
<


#SELECTION ~

The `selection` context shares your current or most recent visual selection
with the LLM. This is useful for asking about a specific piece of code without
sharing the entire buffer. The selection is updated when you open or toggle a
CodeCompanion chat buffer.

>md
    Sharing the relevant code with you #{selection}
<


#TERMINAL ~

The `terminal` context shares the latest output from the last terminal buffer
you entered. Subsequent uses capture only new output since the last time it was
shared. This is useful for sharing test results, build output, or command-line
errors.

>md
    This was the output in my terminal #{terminal}
<


#VIEWPORT ~

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

>md
    Sharing what I can see in Neovim #{viewport}
<


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


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


/ACP_SESSION_OPTIONS ~


  [!NOTE] This command is only relevant for users of ACP adapters
The ACP specification
<https://agentclientprotocol.com/protocol/session-config-options> allows users
to change config options for an agent session and the `acp_session_options`
slash command provides the interface to do this.


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

This slash command is also available in the
|codecompanion-usage-cli-slash-commands|, where it inserts `@path` references
instead of buffer contents.


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

This slash command is also available in the
|codecompanion-usage-cli-slash-commands|, where it inserts `@path` references
instead of file contents.

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

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


/FORK ~

The `fork` slash command, specific to `http` adapters, allows you to duplicate
the current chat buffer, copying the message history and preserving tools and
context in the process. This enables you to branch the conversation and
experiment with different prompts, models or even adapters without losing the
original conversation.


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


/MCP ~

The `mcp` slash command allows you to start and stop
|codecompanion-configuration-mcp| servers manually from within a chat buffer.
This is applied at a global level, so starting/stopping servers in one chat
buffer will affect all other chat buffers. A `snacks.nvim` and `vim.ui.select`
provider is available for selecting which MCP servers to start/stop.


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


/RESUME ~

The `resume` slash command is specific to
|codecompanion-configuration-adapters-acp| adapters that support the
`session/list` capability. It allows you to resume a previous session by
listing your past sessions and restoring the selected one into the chat buffer.
The conversation history is rendered so you can continue where you left off.


  [!NOTE] The `/resume` command must be used before sending any messages. It is
  only available on a fresh chat buffer.

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


COMMAND-LINE INTERFACE (CLI)*codecompanion-usage-command-line-interface-(cli)*

The CLI interaction allows you to interact with agents that have a command-line
interface such as Claude Code
<https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview> and
Codex <https://github.com/openai/codex>.

`Why?` Sharing context with an agent in the CLI can be cumbersome. You have to
navigate to the CLI, press `@` search for the file or trigger a slash command.
If you want to share a code snippet then that's a good ol' copy and paste job.
With CodeCompanion, you can share context from Neovim in keystrokes, without
leaving the buffer or the editor.


INITIATING A CLI INTERACTION ~

You can use `:CodeCompanionCLI` to start a new CLI interaction and
CodeCompanion will leverage the agent you've configured in your config at
`interactions.cli.agent`. If you want to specify an agent on the fly, you can
use `:CodeCompanionCLI agent=<agent_name>`.

You can toggle a CLI interaction with `require("codecompanion").toggle()`, just
as you would with a chat buffer. You can use `{` and `}` to cycle through all
the chat and CLI interactions.


WORKFLOW ~

Below are some useful workflow tips to enable you to be productive when working
with agents in the CLI with CodeCompanion:


PROMPTING THE AGENT

You can send a custom prompt to the agent from within a Neovim buffer:

>lua
    -- [C]odeCompanion [P]rompt]
    vim.keymap.set({ "n", "v" }, "<LocalLeader>cp", function()
      return require("codecompanion").cli({ prompt = true })
    end, { desc = "Prompt the CLI agent" })
<

In normal mode, this brings up the prompt input, allowing you to specify editor
context before sending to the agent. In visual mode however, it shares the
selection alongside your prompt, saving you from manually specifying editor
context.


ADDING CONTEXT

You're working in a buffer and think `“I should share this with the agent”`
or `“This code is relevant to the conversation…”`:

>lua
    -- [C]odeCompanion [A]dd
    vim.keymap.set({ "n", "v" }, "<LocalLeader>ca", function()
      return require("codecompanion").cli("#{this}", { focus = false })
    end, { desc = "Add context to the CLI agent" })
<

This keymap allows you to quickly share the current buffer or visual selection
with the agent, without needing to specify a prompt, utilising `#{this}`. This
is useful for quickly sharing context before following up with a more specific
prompt. You'll also note the inclusion of `focus = false` to ensure that the
cursor doesn't move into the CLI buffer.

This can be useful as you carefully move between buffers and code, determining
what context is relevant to share with the agent, without losing your current
position in the CLI buffer.


FIXING LSP DIAGNOSTICS

If the LSP is throwing some warnings, share them with the agent in the CLI and
ask it to fix them:

>lua
    -- [C]odeCompanion [D]iagnostics
    vim.keymap.set("n", "<LocalLeader>cd", function()
      return require("codecompanion").cli("#{diagnostics} Can you fix these?", { focus = false, submit = true })
    end, { desc = "Send diagnostics to CLI agent" })
<

This keymap shares the LSP diagnostics for the current buffer with the agent,
automatically submitting the prompt.


FIXING FAILING TESTS

You've run your test suite in the terminal and observe some failures. Share
them with the agent:

>lua
    -- [C]odeCompanion [T]erminal
    vim.keymap.set("n", "<LocalLeader>ct", function()
      return require("codecompanion").cli("#{terminal} Sharing the output from the terminal. Can you fix it?", { focus = false, submit = true })
    end, { desc = "Send terminal output to CLI agent" })
<

This keymap shares the output from the most recent terminal with the agent,
which is especially useful for sharing failing test output. Again, the prompt
is automatically submitted to save you time.


SENDING CONTEXT ~

This section covers, more broadly, the ways that you can send context to an
agent in the CLI. This should serve as inspiration for how you can leverage the
CLI for your own workflow.


VISUAL SELECTION

To start off, you can use a visual selection as a source of context, by
visually selecting some code and running:

>
    CodeCompanionCLI Can you explain this code?
<

You could also achieve this in Lua:

>lua
    require("codecompanion").cli({ prompt = true })
<

This will result in the visual selection being passed to an input prompt,
allowing you to type `“Can you explain this code?”` before sending it to
the agent.

Alternatively, you could hard code the prompt:

>lua
    require("codecompanion").cli("Can you explain this code?")
<


EDITOR CONTEXT

Similarly to the |codecompanion-usage-chat-buffer-index|, you can use
|codecompanion-usage-chat-buffer-editor-context| references in your prompts to
share information about your current Neovim session. This makes it trivial to
share the current buffer (`#{buffer}`), all currently open buffers
(`#{buffers}`), or LSP diagnostics (`#{diagnostics}`) to name but a few.

You can use the `:CodeCompanionCLI` command:

>
    CodeCompanionCLI Can you explain #{buffers}?
<

Which will be expanded in the agent CLI to be:

>log
    ❯ Can you explain the open buffers:
      @your_file_path
      @your_other_file_path?
<

Alternatively:

>lua
    require("codecompanion").cli("Can you explain #{buffers}?")
<

------------------------------------------------------------------------------
CodeCompanion also provides `#{this}` (unique to the CLI interaction) which
resolves to the current buffer in normal mode, and the visual selection in
visual mode:

>
    CodeCompanionCLI What does #{this} do?
<

In normal mode, this will resolve to be:

>log
    ❯ What does @your_file_path do?
<

and with a visual selection, will resolve to be:

>log
    ❯ What does the selected code in @your_file_path do?
    
      - Selected code from @your_file_path (lines 3-4):
      ````lua
      local new_set = MiniTest.new_set
      local T = new_set()
      ````
<


  [!NOTE] `@path` references are understood natively by CLI agents like Claude
  Code and Codex, allowing them to read files directly.

PROMPTS

There will come a time when you need to send a more complex prompt to the
agent. Whilst you can do `:CodeCompanionCLI <my long prompt>`, you can also
bring up a prompt input with:

>
    CodeCompanionCLI Ask
<

or:

>lua
    require("codecompanion").cli({ prompt = true })
<

This will toggle a `codecompanion_input` buffer. In this buffer, you have
access to all of the available |codecompanion--editor-context|, some
|codecompanion--slash-commands| and a much a larger character window. To send
the prompt to the agent, you can write the buffer with `:w`. Or, to
automatically send and submit, you can forcefully write with `:w!`.

You can scroll previous prompts with the `<up>` and `<down>` keys.


SLASH COMMANDS

The prompt input buffer also supports the
|codecompanion-usage-chat-buffer-slash-commands-buffer%5d| and
|codecompanion-usage-chat-buffer-slash-commands-file| slash commands, which
better enable you to share lots of context with a CLI agent at once. Simply
type `/` in the buffer to bring up the completion menu for your selected
provider.

Instead of sharing file contents, CLI slash commands insert `@path` references
into the prompt. For example, selecting a file via `/file` will insert:

>markdown
    @./lua/codecompanion/init.lua
<

If you select multiple files, each one is added on its own line:

>markdown
    @./lua/codecompanion/init.lua
    @./lua/codecompanion/config.lua
<


AUTO-SUBMIT

By default, prompts are sent to the agent but `not` submitted. The text appears
in the CLI and you can review it before pressing enter. To automatically submit
a prompt so the agent starts working immediately, you can:

Use the `bang` form of the command:

>
    CodeCompanionCLI! #{diagnostics} Can you fix these?
<

Or pass `submit = true` in Lua:

>lua
    require("codecompanion").cli("#{diagnostics} Can you fix these?", { submit = true })
<

This is especially useful in keymaps where you want a fire-and-forget workflow,
like the diagnostics and terminal examples in the |codecompanion--workflow|
section.


API REFERENCE ~

The `require("codecompanion").cli()` function is the main entry point for
interacting with CLI agents. It has a polymorphic signature:

>lua
    -- No args: create a new CLI instance and open it
    require("codecompanion").cli()
    
    -- Opts table: create a new instance with options
    require("codecompanion").cli({ agent = "claude_code" })
    
    -- String prompt: send to the last instance (or create one)
    require("codecompanion").cli("Can you explain this code?")
    
    -- String prompt with opts
    require("codecompanion").cli("Fix #{diagnostics}", { submit = true, focus = false })
<


OPTIONS

  -----------------------------------------------------------------------
  Option            Type              Default           Description
  ----------------- ----------------- ----------------- -----------------
  agent             string            config default    The CLI agent to
                                                        use. When sending
                                                        a prompt, reuses
                                                        an existing
                                                        instance of this
                                                        agent if one
                                                        exists

  focus             boolean           true              Whether to open
                                                        the CLI window
                                                        and move the
                                                        cursor to it. Set
                                                        to false to send
                                                        context in the
                                                        background

  submit            boolean           false             Automatically
                                                        submit the prompt
                                                        (press enter) so
                                                        the agent starts
                                                        working
                                                        immediately

  prompt            boolean           false             Open the prompt
                                                        input buffer
                                                        instead of
                                                        sending directly.
                                                        If a string
                                                        prompt is also
                                                        provided, it
                                                        pre-fills the
                                                        input

  width             number            config default    Override the CLI
                                                        window width

  height            number            config default    Override the CLI
                                                        window height
  -----------------------------------------------------------------------

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:

- `CodeCompanionACPConnected` - Fired after the ACP connection is authenticated and ready to use
- `CodeCompanionACPSessionPre` - Fired after ACP authentication completes but before a new session is established; allows subscribers to modify the connection (e.g. inject MCP servers) synchronously
- `CodeCompanionACPSessionPost` - Fired after a new ACP session has been established
- `CodeCompanionChatACPModeChanged` - Fired after the ACP mode has been changed in the chat
- `CodeCompanionACPChatRestored` - Fired after an ACP session has been restored
- `CodeCompanionChatCreated` - Fired after a chat has been created for the first time
- `CodeCompanionChatOpened` - Fired after a chat has been opened
- `CodeCompanionChatClosed` - Fired after a chat has been permanently closed
- `CodeCompanionChatHidden` - Fired after a chat has been hidden
- `CodeCompanionChatSubmitted` - Fired after a chat has been submitted
- `CodeCompanionChatDone` - Fired after a chat has received the response
- `CodeCompanionChatCompacting` - Fired after the chat begins compacting messages to reduce token usage
- `CodeCompanionChatStopped` - Fired after a chat has been stopped
- `CodeCompanionChatCleared` - Fired after a chat has been cleared
- `CodeCompanionChatRestored` - Fired after a chat has been restored to an editable state (e.g. when `on_before_submit` prevents submission)
- `CodeCompanionChatAdapter` - Fired after the adapter has been set in the chat
- `CodeCompanionChatModel` - Fired after the model has been set in the chat
- `CodeCompanionCLICreated` - Fired after a CLI buffer has been created for the first time
- `CodeCompanionCLIOpened` - Fired after a CLI buffer has been opened
- `CodeCompanionCLIClosed` - Fired after a CLI buffer has been closed
- `CodeCompanionCLIHidden` - Fired after a CLI buffer has been hidden
- `CodeCompanionCLISent` - Fired after data has been sent to a CLI buffer
- `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
- `CodeCompanionToolApprovalRequested` - Fired when a tool is requesting approval to run
- `CodeCompanionToolApprovalFinished` - Fired when a user has actioned an approval request
- `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
- `CodeCompanionMCPServerStart` - Fired when an MCP server is started
- `CodeCompanionMCPServerReady` - Fired when an MCP server is ready for requests
- `CodeCompanionMCPServerClosed` - Fired when an MCP server is closed
- `CodeCompanionMCPServerToolsLoaded` - Fired when tools are loaded for an MCP server
- `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

In addition to these events, the chat buffer has its own **callback system**
for hooking into lifecycle events like `on_before_submit`, `on_checkpoint` and
`on_tool_output`. These callbacks receive the chat instance and can inspect or
mutate chat state. See the |codecompanion-configuration-chat-buffer-callbacks|
section for details.

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 INTERACTION                    *codecompanion-usage-inline-interaction*

As per the |codecompanion-getting-started-inline| guide, the inline interaction
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 interaction. 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 interaction 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.


EDITOR CONTEXT ~


  [!TIP] To ensure the LLM has enough context to complete a complex ask, it's
  recommended to use the `buffer` editor context
The inline interaction allows you to send context alongside your prompt via the
notion of editor context. That is, context that relates to your current Neovim
session:

- `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 context items can be sent as part of the
same prompt. You can even add your own custom variables as per the
|codecompanion-configuration-inline-editor-context|.

You can also have multiple editor context as 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.


SLASH COMMANDS ~

If your prompt library entries have an `alias` defined then you can invoke them
using a slash command. In the cmd line `:CodeCompanion /<alias>` or `/<alias>`
if you're in the chat buffer.

When invoked this way, any tools declared on the prompt are added to the
current chat buffer before the prompt content is inserted.


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
- `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
- `CodeCompanionChatTokens` - Virtual text in the chat buffer showing the token count
- `CodeCompanionChatTool` - Tools in the chat buffer
- `CodeCompanionChatToolGroups` - Tool groups in the chat buffer
- `CodeCompanionChatToolText` - Tool output text in the chat buffer (overrides markdown rendering)
- `CodeCompanionChatEditorContext` - Editor context 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.


==============================================================================
9. 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 @{run_command} 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 run_command tool
                condition = function()
                  return _G.codecompanion_current_tool == "run_command"
                end,
                -- Repeat until the tests pass, as indicated by the testing flag
                -- which the run_command 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 @{run_command} 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-agents-tools-files| and
|codecompanion-usage-chat-buffer-agents-tools-run-command| tools to edit a
buffer and run tests, respectively.

We're giving the LLM knowledge of the buffer with the `#buffer` editor context
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 run_command tool is active
            condition = function(chat)
              return chat.tools.tool and chat.tools.tool.name == "run_command"
            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-agents-tools-run-command|.

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-agents-tools-run-command| 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(self, args, opts)
                Note over T,O: Returns {status, data} (sync) or calls opts.output_cb (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 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/
    │   ├── run_command.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, meta: { tools: CodeCompanion.Tools }): any Function used to setup the tool. Called before any commands
    ---@field handlers.prompt_condition? fun(self: CodeCompanion.Tools.Tool, meta: { tools: CodeCompanion.Tools }): boolean Function to determine whether to show the prompt to the user or not
    ---@field handlers.on_exit? fun(self: CodeCompanion.Tools.Tool, meta: { 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, meta: { 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, meta: { tools: CodeCompanion.Tools, cmd: table, opts: table }): any Function to call if the user rejects running a command
    ---@field output.error? fun(self: CodeCompanion.Tools.Tool, stderr: table, meta: { tools: CodeCompanion.Tools, cmd: table }): any The function to call if an error occurs
    ---@field output.success? fun(self: CodeCompanion.Tools.Tool, stdout: table, meta: { tools: CodeCompanion.Tools, cmd: table }): any Function to call if the tool is successful
    ---@field output.cancelled? fun(self: CodeCompanion.Tools.Tool, meta: { 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 run_command
  <https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/interactions/chat/tools/builtin/run_command.lua>
  tool.
**Function-based Tools**

Function-based tools use the `cmds` table to define functions that will be
executed one after another. Each function receives three parameters: `self`,
the arguments from the LLM, and an `opts` table containing `input` (output from
a previous function call) and `output_cb` (callback for async execution). For a
synchronous tool (like the calculator) you can ignore `opts`. 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 opts { input: any, output_cb: fun(result: table) }
      ---@return nil|{ status: "success"|"error", data: string }
      function(self, args, opts)
        -- 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 `opts.output_cb` to submit any results to the orchestrator,
which will then invoke `output` functions to handle the results:

>lua
    cmds = {
      function(self, args, opts)
        local cb = opts.output_cb
        -- 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) })
          cb({ status = "success", data = result })
        end, buf_nr)
      end
    }
<

Note that:

1. The `opts.output_cb` callback will be called only once. Subsequent calls will be discarded;
2. A tool function should EITHER return the result table (synchronous), OR call `opts.output_cb` with the result table as the only argument (asynchronous), but not both.
If a function tries to both return the result and call `opts.output_cb`, 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 @run_command <https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/interactions/chat/tools/builtin/run_command.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 meta { tools: CodeCompanion.Tools }
      setup = function(self, meta)
        return vim.notify("setup function called", vim.log.levels.INFO)
      end,
      ---@param self CodeCompanion.Tool.Calculator
      ---@param meta { tools: CodeCompanion.Tools }
      on_exit = function(self, meta)
        return vim.notify("on_exit function called", vim.log.levels.INFO)
      end,
    },
<


  [!TIP] The chat buffer can be accessed via `meta.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 stdout table
      ---@param meta { tools: CodeCompanion.Tools, cmd: table }
      success = function(self, stdout, meta)
        local chat = meta.tools.chat
        return chat:add_tool_output(self, tostring(stdout[1]))
      end,
      ---@param self CodeCompanion.Tool.Calculator
      ---@param stderr table The error output from the command
      ---@param meta { tools: CodeCompanion.Tools, cmd: table }
      error = function(self, stderr, meta)
        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",
              name = "calculator",
              cmds = {
                ---@param self CodeCompanion.Tool.Calculator The Calculator tool
                ---@param args table The arguments from the LLM's tool call
                ---@param opts { input: any, output_cb: fun(result: table) }
                ---@return nil|{ status: "success"|"error", data: string }
                function(self, args, opts)
                  -- 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 meta { tools: CodeCompanion.Tools }
                setup = function(self, meta)
                  return vim.notify("setup function called", vim.log.levels.INFO)
                end,
                ---@param self CodeCompanion.Tool.Calculator
                ---@param meta { tools: CodeCompanion.Tools }
                on_exit = function(self, meta)
                  return vim.notify("on_exit function called", vim.log.levels.INFO)
                end,
              },
              output = {
                ---@param self CodeCompanion.Tool.Calculator
                ---@param stdout table
                ---@param meta { tools: CodeCompanion.Tools, cmd: table }
                success = function(self, stdout, meta)
                  local chat = meta.tools.chat
                  return chat:add_tool_output(self, tostring(stdout[1]))
                end,
                ---@param self CodeCompanion.Tool.Calculator
                ---@param stderr table The error output from the command
                ---@param meta { tools: CodeCompanion.Tools, cmd: table }
                error = function(self, stderr, meta)
                  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",
              path = "path.to.calculator",
              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 meta { tools: CodeCompanion.Tools }
      ---@return string
      prompt = function(self, meta)
        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 meta { tools: CodeCompanion.Tools, cmd: table, opts: table }
      ---@return nil
      rejected = function(self, meta)
        meta.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 meta { tools: CodeCompanion.Tools, cmd: table }
      ---@return nil
      cancelled = function(self, meta)
        meta.tools.chat:add_tool_output(self, "The user cancelled the execution of the calculator tool")
      end,
    },
<


EXTENDING FROM THE RUN_COMMAND TOOL ~

For a lot of users, custom tools will often be commands that they ask an LLM to
execute on their machine. As such, the handlers and output functions that exist
in the |codecompanion-usage-chat-buffer-agents-tools-run-command| tool are
sufficient and should be reused.

To make it easy for users to create their own command-based tools,
CodeCompanion allows for extensions from `run_command`. In the example below,
we create a wrapper around the beads <https://github.com/steveyegge/beads> CLI
tool, that does just that:

**Inline in your config:**

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          tools = {
            ["beads"] = {
              extends = "cmd_tool",
              description = "Beads task management",
              opts = { require_approval_before = true },
              name = "beads",
              system_prompt = [[Beads is a local, hash-based task tracking system. Tasks have short IDs like `bd-a1b2`. Key commands:
    
    - `bd ready` — list tasks with no open blockers (i.e. ready to work on)
    - `bd show <id>` — show full details for a task
    - `bd create "<title>" -p <priority>` — create a new task (priority 0 = highest)
    - `bd update <id> --claim` — assign a task to yourself
    - `bd update <id> --status done` — mark a task as done
    - `bd dep add <child> <parent>` — make child depend on parent
    
    Output is JSON. Always use `bd ready` first to see what's available before taking action.]],
              schema = {
                properties = {
                  action = {
                    type = "string",
                    enum = { "ready", "show", "create", "update", "dep" },
                    description = "The beads action to perform",
                  },
                  task_id = {
                    type = "string",
                    description = "The task ID (e.g. bd-a1b2). Required for show, update, and dep actions",
                  },
                  args = {
                    type = "string",
                    description = "Additional arguments for the command (e.g. title for create, flags for update)",
                  },
                },
                required = { "action" },
              },
              build_cmd = function(args)
                local parts = { "bd", args.action }
                if args.task_id then
                  table.insert(parts, args.task_id)
                end
                if args.args then
                  table.insert(parts, args.args)
                end
                return table.concat(parts, " ")
              end,
            },
          },
        },
      },
    })
<

**Or via an external file:**

>lua
    require("codecompanion").setup({
      interactions = {
        chat = {
          tools = {
            ["beads"] = {
              description = "Beads task management",
              opts = { require_approval_before = true },
              path = "~/.dotfiles/.config/tools/beads.lua",
            },
          },
        },
      },
    })
<

Where the file returns a table with `extends`:

>lua
    -- ~/.dotfiles/.config/tools/beads.lua
    return {
      extends = "cmd_tool",
      name = "beads",
      description = "Manage tasks using the Beads task tracking system (bd CLI)",
      system_prompt = [[...]],
      schema = { ... },
      build_cmd = function(args)
        local parts = { "bd", args.action }
        if args.task_id then
          table.insert(parts, args.task_id)
        end
        if args.args then
          table.insert(parts, args.args)
        end
        return table.concat(parts, " ")
      end,
    }
<

In this example, the `schema` defines structured properties (`action`,
`task_id`, `args`) that constrain what the LLM can pass to `build_cmd`. The
output of `build_cmd` is what the `run_command` tool ultimately executes.
Finally, the `system_prompt` teaches the LLM what each beads command does, so
it can choose the right action for the user's request.


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 meta { tools: table }
        callback = function(self, meta)
          table.insert(meta.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, { tools = 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-agents-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 INTERACTION 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: