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 `agent/init.lua` file. The agent triggers off a series of events, which

shared back to the LLM via the chat buffer. Depending on the tool, flags may be

inserted on the chat buffer for later processing.

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

SLASH COMMANDS *codecompanion-usage-slash-commands*

system_prompt = "Describe what the agent should do",

tools = {

"cmd_runner",

-- Add your own tools or reuse existing ones

},

opts = {

})

A tool is a [`CodeCompanion.Tool`](/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.

require("codecompanion").setup({

There are a number of diff settings available to you:

require("codecompanion").setup({

and with the prompt:

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

You can add context from your code base by using _Variables_ and _Slash Commands_ in the chat buffer.

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

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

The inline assistant enables an LLM to write code directly into a Neovim buffer.

For convenience, you can call prompts from the [prompt library](/configuration/prompt-library) via the cmd line, such as `:'<,'>CodeCompanion /explain`. The prompt library comes with the following defaults:

The section of the discussion forums which is dedicated to user created tools can be found [here](https://github.com/olimorris/codecompanion.nvim/discussions/categories/tools).

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

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 [workflows](/extending/workflows) to hook into.

Create a file within the current working directory:

This tool enables an LLM to search for files in the current working directory by glob pattern. It will return a list of relative paths for any matching files.

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:

This tool can edit buffers and files for code changes from an LLM:

Inspired by [Copilot Next Edit Suggestion](https://code.visualstudio.com/blogs/2025/02/12/next-edit-suggestions), the `@next_edit_suggestion` tool gives the LLM the ability to show the user where the next edit is. The LLM can only suggest edits in files or buffers that have been shared with it as context.

The `jump_action` can be a VimScript command (as a string), or a lua function that accepts the path to the file and optionally returns the [window ID](https://neovim.io/doc/user/windows.html#window-ID). The window ID is needed if you want the LLM to point you to a specific line in the 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.

The _@web_search_ tool enables an LLM to search the web for a specific query. This can be useful to supplement an LLMs knowledge cut off date with more up to date information.

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

CodeCompanion comes with two built-in tool groups:

If you want to show all tools as references in the chat buffer, set the `collapse_tools` option to `false`:

Consider combining tools for complex tasks: