`: The original code content
- ``: The specific changes using truncation markers (`// ... existing code ...`)
This approach ensures that the apply model can quickly and accurately merge your changes without the overhead of full code generation.
## Ollama
Ollama is a first-class provider for avante.nvim. To start using it you need to set `provider = "ollama"`
in the configuration, set the `model` field in `ollama` to the model you want to use. Ollama is disabled
by default, you need to provide an implementation for its `is_env_set` method to properly enable it.
For example:
```lua
provider = "ollama",
providers = {
ollama = {
model = "qwq:32b",
is_env_set = require("avante.providers.ollama").check_endpoint_alive,
},
}
```
## ACP Support
Avante.nvim now supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction), enabling seamless integration with AI agents that follow this standardized communication protocol. ACP provides a unified way for AI agents to interact with development environments, offering enhanced capabilities for code editing, file operations, and tool execution.
### What is ACP?
The Agent Client Protocol (ACP) is a standardized protocol that enables AI agents to communicate with development tools and environments. It provides:
- **Standardized Communication**: A unified JSON-RPC based protocol for agent-client interactions
- **Tool Integration**: Support for various development tools like file operations, code execution, and search
- **Session Management**: Persistent sessions that maintain context across interactions
- **Permission System**: Granular control over what agents can access and modify
### Enabling ACP
To use ACP-compatible agents with Avante.nvim, you need to configure an ACP provider. Here are the currently supported ACP agents:
#### Gemini CLI with ACP
```lua
{
provider = "gemini-cli",
-- other configuration options...
}
```
#### Claude Code with ACP
```lua
{
provider = "claude-code",
-- other configuration options...
}
```
#### Goose with ACP
```lua
{
provider = "goose",
-- other configuration options...
}
```
#### Codex with ACP
```lua
{
provider = "codex",
-- other configuration options...
}
```
#### Kimi CLI with ACP
```lua
{
provider = "kimi-cli",
-- other configuration options...
}
```
### ACP Configuration
ACP providers are configured in the `acp_providers` section of your configuration:
```lua
{
acp_providers = {
["gemini-cli"] = {
command = "gemini",
args = { "--experimental-acp" },
env = {
NODE_NO_WARNINGS = "1",
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY"),
},
},
["claude-code"] = {
command = "npx",
args = { "@zed-industries/claude-code-acp" },
env = {
NODE_NO_WARNINGS = "1",
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY"),
},
},
["goose"] = {
command = "goose",
args = { "acp" },
},
["codex"] = {
command = "npx",
args = { "@zed-industries/codex-acp" },
env = {
NODE_NO_WARNINGS = "1",
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY"),
},
},
},
-- other configuration options...
}
```
### Prerequisites
Before using ACP agents, ensure you have the required tools installed:
- **For Gemini CLI**: Install the `gemini` CLI tool and set your `GEMINI_API_KEY`
- **For Claude Code**: Install the `acp-claude-code` package via npm and set your `ANTHROPIC_API_KEY`
### ACP vs Traditional Providers
ACP providers offer several advantages over traditional API-based providers:
- **Enhanced Tool Access**: Agents can directly interact with your file system, run commands, and access development tools
- **Persistent Context**: Sessions maintain state across multiple interactions
- **Fine-grained Permissions**: Control exactly what agents can access and modify
- **Standardized Protocol**: Compatible with any ACP-compliant agent
## Custom providers
Avante provides a set of default providers, but users can also create their own providers.
For more information, see [Custom Providers](https://github.com/yetone/avante.nvim/wiki/Custom-providers)
## RAG Service
Avante provides a RAG service, which is a tool for obtaining the required context for the AI to generate the codes. By default, it is not enabled. You can enable it this way:
```lua
rag_service = { -- RAG Service configuration
enabled = false, -- Enables the RAG service
host_mount = os.getenv("HOME"), -- Host mount path for the rag service (Docker will mount this path)
runner = "docker", -- Runner for the RAG service (can use docker or nix)
llm = { -- Language Model (LLM) configuration for RAG service
provider = "openai", -- LLM provider
endpoint = "https://api.openai.com/v1", -- LLM API endpoint
api_key = "OPENAI_API_KEY", -- Environment variable name for the LLM API key
model = "gpt-4o-mini", -- LLM model name
extra = nil, -- Additional configuration options for LLM
},
embed = { -- Embedding model configuration for RAG service
provider = "openai", -- Embedding provider
endpoint = "https://api.openai.com/v1", -- Embedding API endpoint
api_key = "OPENAI_API_KEY", -- Environment variable name for the embedding API key
model = "text-embedding-3-large", -- Embedding model name
extra = nil, -- Additional configuration options for the embedding model
},
docker_extra_args = "", -- Extra arguments to pass to the docker command
},
```
The RAG Service can currently configure the LLM and embedding models separately. In the `llm` and `embed` configuration blocks, you can set the following fields:
- `provider`: Model provider (e.g., "openai", "ollama", "dashscope", and "openrouter")
- `endpoint`: API endpoint
- `api_key`: Environment variable name for the API key
- `model`: Model name
- `extra`: Additional configuration options
For detailed configuration of different model providers, you can check [here](./py/rag-service/README.md).
Additionally, RAG Service also depends on Docker! (For macOS users, OrbStack is recommended as a Docker alternative).
`host_mount` is the path that will be mounted to the container, and the default is the home directory. The mount is required
for the RAG service to access the files in the host machine. It is up to the user to decide if you want to mount the whole
`/` directory, just the project directory, or the home directory. If you plan using avante and RAG event for projects
stored outside your home directory, you will need to set the `host_mount` to the root directory of your file system.
The mount will be read only.
After changing the rag_service configuration, you need to manually delete the rag_service container to ensure the new configuration is used: `docker rm -fv avante-rag-service`
## Web Search Engines
Avante's tools include some web search engines, currently support:
- [Tavily](https://tavily.com/)
- [SerpApi - Search API](https://serpapi.com/)
- Google's [Programmable Search Engine](https://developers.google.com/custom-search/v1/overview)
- [Kagi](https://help.kagi.com/kagi/api/search.html)
- [Brave Search](https://api-dashboard.search.brave.com/app/documentation/web-search/get-started)
- [SearXNG](https://searxng.github.io/searxng/)
The default is Tavily, and can be changed through configuring `Config.web_search_engine.provider`:
```lua
web_search_engine = {
provider = "tavily", -- tavily, serpapi, google, kagi, brave, or searxng
proxy = nil, -- proxy support, e.g., http://127.0.0.1:7890
}
```
Environment variables required for providers:
- Tavily: `TAVILY_API_KEY`
- SerpApi: `SERPAPI_API_KEY`
- Google:
- `GOOGLE_SEARCH_API_KEY` as the [API key](https://developers.google.com/custom-search/v1/overview)
- `GOOGLE_SEARCH_ENGINE_ID` as the [search engine](https://programmablesearchengine.google.com) ID
- Kagi: `KAGI_API_KEY` as the [API Token](https://kagi.com/settings?p=api)
- Brave Search: `BRAVE_API_KEY` as the [API key](https://api-dashboard.search.brave.com/app/keys)
- SearXNG: `SEARXNG_API_URL` as the [API URL](https://docs.searxng.org/dev/search_api.html)
## Disable Tools
Avante enables tools by default, but some LLM models do not support tools. You can disable tools by setting `disable_tools = true` for the provider. For example:
```lua
providers = {
claude = {
endpoint = "https://api.anthropic.com",
model = "claude-sonnet-4-20250514",
timeout = 30000, -- Timeout in milliseconds
disable_tools = true, -- disable tools!
extra_request_body = {
temperature = 0,
max_tokens = 4096,
}
}
}
```
In case you want to ban some tools to avoid its usage (like Claude 3.7 overusing the python tool) you can disable just specific tools
```lua
{
disabled_tools = { "python" },
}
```
Tool list
> rag_search, python, git_diff, git_commit, glob, search_keyword, read_file_toplevel_symbols,
> read_file, create_file, move_path, copy_path, delete_path, create_dir, bash, web_search, fetch
## Custom Tools
Avante allows you to define custom tools that can be used by the AI during code generation and analysis. These tools can execute shell commands, run scripts, or perform any custom logic you need.
### Example: Go Test Runner
Here's an example of a custom tool that runs Go unit tests:
```lua
{
custom_tools = {
{
name = "run_go_tests", -- Unique name for the tool
description = "Run Go unit tests and return results", -- Description shown to AI
command = "go test -v ./...", -- Shell command to execute
param = { -- Input parameters (optional)
type = "table",
fields = {
{
name = "target",
description = "Package or directory to test (e.g. './pkg/...' or './internal/pkg')",
type = "string",
optional = true,
},
},
},
returns = { -- Expected return values
{
name = "result",
description = "Result of the fetch",
type = "string",
},
{
name = "error",
description = "Error message if the fetch was not successful",
type = "string",
optional = true,
},
},
func = function(params, on_log, on_complete) -- Custom function to execute
local target = params.target or "./..."
return vim.system({ "go", "test", "-v", target }, { text = true }):wait().stdout
end,
},
},
}
```
## MCP
Now you can integrate MCP functionality for Avante through `mcphub.nvim`. For detailed documentation, please refer to [mcphub.nvim](https://ravitemer.github.io/mcphub.nvim/extensions/avante.html)
## Custom prompts
By default, `avante.nvim` provides three different modes to interact with: `planning`, `editing`, and `suggesting`, followed with three different prompts per mode.
- `planning`: Used with `require("avante").toggle()` on sidebar
- `editing`: Used with `require("avante").edit()` on selection codeblock
- `suggesting`: Used with `require("avante").get_suggestion():suggest()` on Tab flow.
- `cursor-planning`: Used with `require("avante").toggle()` on Tab flow, but only when cursor planning mode is enabled.
Users can customize the system prompts via `Config.system_prompt` or `Config.override_prompt_dir`.
`Config.system_prompt` allows you to set a global system prompt. We recommend calling this in a custom Autocmds depending on your need:
```lua
vim.api.nvim_create_autocmd("User", {
pattern = "ToggleMyPrompt",
callback = function() require("avante.config").override({system_prompt = "MY CUSTOM SYSTEM PROMPT"}) end,
})
vim.keymap.set("n", "am", function() vim.api.nvim_exec_autocmds("User", { pattern = "ToggleMyPrompt" }) end, { desc = "avante: toggle my prompt" })
```
`Config.override_prompt_dir` allows you to specify a directory containing your own custom prompt templates, which will override the built-in templates. This is useful if you want to maintain a set of custom prompts outside of your Neovim configuration. It can be a string representing the directory path, or a function that returns a string representing the directory path.
```lua
-- Example: Override with prompts from a specific directory
require("avante").setup({
override_prompt_dir = vim.fn.expand("~/.config/nvim/avante_prompts"),
})
-- Example: Override with prompts from a function (dynamic directory)
require("avante").setup({
override_prompt_dir = function()
-- Your logic to determine the prompt directory
return vim.fn.expand("~/.config/nvim/my_dynamic_prompts")
end,
})
```
> [!WARNING]
>
> If you customize `base.avanterules`, please ensure that `{% block custom_prompt %}{% endblock %}` and `{% block extra_prompt %}{% endblock %}` exist, otherwise the entire plugin may become unusable.
> If you are unsure about the specific reasons or what you are doing, please do not override the built-in prompts. The built-in prompts work very well.
If you wish to custom prompts for each mode, `avante.nvim` will check for project root based on the given buffer whether it contains
the following patterns: `*.{mode}.avanterules`.
The rules for root hierarchy:
- lsp workspace folders
- lsp root_dir
- root pattern of filename of the current buffer
- root pattern of cwd
You can also configure custom directories for your `avanterules` files using the `rules` option:
```lua
require('avante').setup({
rules = {
project_dir = '.avante/rules', -- relative to project root, can also be an absolute path
global_dir = '~/.config/avante/rules', -- absolute path
},
})
```
The loading priority is as follows:
1. `rules.project_dir`
2. `rules.global_dir`
3. Project root
Example folder structure for custom prompt
If you have the following structure:
```bash
.
├── .git/
├── typescript.planning.avanterules
├── snippets.editing.avanterules
├── suggesting.avanterules
└── src/
```
- `typescript.planning.avanterules` will be used for `planning` mode
- `snippets.editing.avanterules` will be used for `editing` mode
- `suggesting.avanterules` will be used for `suggesting` mode.
> [!important]
>
> `*.avanterules` is a jinja template file, in which will be rendered using [minijinja](https://github.com/mitsuhiko/minijinja). See [templates](https://github.com/yetone/avante.nvim/blob/main/lua/avante/templates) for example on how to extend current templates.
## Integration
Avante.nvim can be extended to work with other plugins by using its extension modules. Below is an example of integrating Avante with [`nvim-tree`](https://github.com/nvim-tree/nvim-tree.lua), allowing you to select or deselect files directly from the NvimTree UI:
```lua
{
"yetone/avante.nvim",
event = "VeryLazy",
keys = {
{
"a+",
function()
local tree_ext = require("avante.extensions.nvim_tree")
tree_ext.add_file()
end,
desc = "Select file in NvimTree",
ft = "NvimTree",
},
{
"a-",
function()
local tree_ext = require("avante.extensions.nvim_tree")
tree_ext.remove_file()
end,
desc = "Deselect file in NvimTree",
ft = "NvimTree",
},
},
opts = {
--- other configurations
selector = {
exclude_auto_select = { "NvimTree" },
},
},
}
```
## TODOs
- [x] Chat with current file
- [x] Apply diff patch
- [x] Chat with the selected block
- [x] Slash commands
- [x] Edit the selected block
- [x] Smart Tab (Cursor Flow)
- [x] Chat with project (You can use `@codebase` to chat with the whole project)
- [x] Chat with selected files
- [x] Tool use
- [x] MCP
- [x] ACP
- [ ] Better codebase indexing
## Roadmap
- **Enhanced AI Interactions**: Improve the depth of AI analysis and recommendations for more complex coding scenarios.
- **LSP + Tree-sitter + LLM Integration**: Integrate with LSP and Tree-sitter and LLM to provide more accurate and powerful code suggestions and analysis.
## FAQ
### How to disable agentic mode?
Avante.nvim provides two interaction modes:
- **`agentic`** (default): Uses AI tools to automatically generate and apply code changes
- **`legacy`**: Uses the traditional planning method without automatic tool execution
To disable agentic mode and switch to legacy mode, update your configuration:
```lua
{
mode = "legacy", -- Switch from "agentic" to "legacy"
-- ... your other configuration options
}
```
**What's the difference?**
- **Agentic mode**: AI can automatically execute tools like file operations, bash commands, web searches, etc. to complete complex tasks
- **Legacy mode**: AI provides suggestions and plans but requires manual approval for all actions
**When should you use legacy mode?**
- If you prefer more control over what actions the AI takes
- If you're concerned about security with automatic tool execution
- If you want to manually review each step before applying changes
- If you're working in a sensitive environment where automatic code changes aren't desired
You can also disable specific tools while keeping agentic mode enabled by configuring `disabled_tools`:
```lua
{
mode = "agentic",
disabled_tools = { "bash", "python" }, -- Disable specific tools
-- ... your other configuration options
}
```
## Contributing
Contributions to avante.nvim are welcome! If you're interested in helping out, please feel free to submit pull requests or open issues. Before contributing, ensure that your code has been thoroughly tested.
See [wiki](https://github.com/yetone/avante.nvim/wiki) for more recipes and tricks.
## Acknowledgments
We would like to express our heartfelt gratitude to the contributors of the following open-source projects, whose code has provided invaluable inspiration and reference for the development of avante.nvim:
| Nvim Plugin | License | Functionality | Location |
| --------------------------------------------------------------------- | ------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| [git-conflict.nvim](https://github.com/akinsho/git-conflict.nvim) | No License | Diff comparison functionality | [lua/avante/diff.lua](https://github.com/yetone/avante.nvim/blob/main/lua/avante/diff.lua) |
| [ChatGPT.nvim](https://github.com/jackMort/ChatGPT.nvim) | Apache 2.0 License | Calculation of tokens count | [lua/avante/utils/tokens.lua](https://github.com/yetone/avante.nvim/blob/main/lua/avante/utils/tokens.lua) |
| [img-clip.nvim](https://github.com/HakonHarnes/img-clip.nvim) | MIT License | Clipboard image support | [lua/avante/clipboard.lua](https://github.com/yetone/avante.nvim/blob/main/lua/avante/clipboard.lua) |
| [copilot.lua](https://github.com/zbirenbaum/copilot.lua) | MIT License | Copilot support | [lua/avante/providers/copilot.lua](https://github.com/yetone/avante.nvim/blob/main/lua/avante/providers/copilot.lua) |
| [jinja.vim](https://github.com/HiPhish/jinja.vim) | MIT License | Template filetype support | [syntax/jinja.vim](https://github.com/yetone/avante.nvim/blob/main/syntax/jinja.vim) |
| [codecompanion.nvim](https://github.com/olimorris/codecompanion.nvim) | MIT License | Secrets logic support | [lua/avante/providers/init.lua](https://github.com/yetone/avante.nvim/blob/main/lua/avante/providers/init.lua) |
| [aider](https://github.com/paul-gauthier/aider) | Apache 2.0 License | Planning mode user prompt | [lua/avante/templates/planning.avanterules](https://github.com/yetone/avante.nvim/blob/main/lua/avante/templates/planning.avanterules) |
The high quality and ingenuity of these projects' source code have been immensely beneficial throughout our development process. We extend our sincere thanks and respect to the authors and contributors of these projects. It is the selfless dedication of the open-source community that drives projects like avante.nvim forward.
## Business Sponsors

Meshy AI
The #1 AI 3D Model Generator for Creators

BabelTower API
No account needed, use any model instantly
## License
avante.nvim is licensed under the Apache 2.0 License. For more details, please refer to the [LICENSE](./LICENSE) file.
# Star History