documents/dev/Avante Neovim.md

Table of Contents

Avante in Neovim

Personal reference for Avante.nvim: AI assistant inside Neovim, wired here through Cursor via ACP (Agent Client Protocol). Official concepts and usage: Avante docs.

Config paths

What Path
Lazy plugin spec (providers, Cursor ACP, keys, slash stubs) ~/.config/nvim/lua/plugins/avante.lua
Cursor mode shortcut helper ~/.config/nvim/lua/config/avante_cursor_mode.lua
Per-project instructions (optional) avante.md at repo root (see instructions_file in plugin opts)

Stack: LazyVim-style layout (lazy.nvim), leader is Space.

Cursor provider and ACP

The active backend is provider = "cursor". Neovim spawns the Cursor CLI in ACP mode:

  • Binary: ~/.local/bin/agent with args { "acp" }
  • Auth: cursor_login — run agent login in a terminal when needed
  • Env forwards HOME and PATH so the subprocess matches your shell

Official Cursor CLI docs (modes, slash commands, ACP overview):

Two different “modes”

Do not confuse:

  1. Avante mode (agentic vs legacy in plugin opts) — how Avante runs tools vs legacy chat/apply flow inside the plugin. See Agentic vs Legacy.
  2. Cursor session modes — Agent / Plan / Ask on the Cursor side when using ACP. In the CLI these align with slash commands such as /plan and /ask (see Cursor docs above).

This setup adds Neovim keymaps that submit those slash lines into the Avante input so the Cursor session switches mode without relying on Shift+Tab (which Avante maps to sidebar window switching).

Slash commands passthrough (slash_commands)

In lua/plugins/avante.lua, slash_commands lists agent, plan, and ask with no callback.

In Avante, slash entries without a handler are still recognized so the line is forwarded to the LLM/ACP session instead of failing as “Unknown command”. That keeps /agent usable even though Cursor’s published slash table emphasizes /plan and /ask.

You can still type /plan or /ask manually in the Avante input; the keymaps only automate that.

Keyboard shortcuts

Cursor session modes (custom)

Mapping Sends
<leader>ama /agent
<leader>amp /plan
<leader>amq /ask

Examples with Space as leader: Space a m a, Space a m p, Space a m q.

Implementation: lazy.nvim keys in avante.lua call require("config.avante_cursor_mode").submit_slash(...), which opens the sidebar, fills the input, and submits.

Typical Avante / LazyVim defaults

Subject to LazyVim/plugin defaults and behaviour.auto_set_keymaps; common mappings include:

Mapping Action
<leader>aa Open ask / chat sidebar
<leader>an New chat
<leader>ar Refresh
<leader>ae Edit selection (visual)
<leader>at Toggle sidebar
<leader>a? Model picker (when enabled)

Basic usage

This is the short version I actually need day to day:

  • On Mac ssh, unlock keychain: run security unlock-keychain if using ACP servers which require auth
  • Start a fresh chat: press <leader>an.
  • Ask about selected text: select text in visual mode, then press <leader>aa to send that selection into Avante chat.
  • Edit selected text: select text in visual mode, then use <leader>ae.
  • Open/toggle the sidebar: <leader>aa or <leader>at depending on whether you want to ask immediately or just show the panel.
  • Switch Cursor session mode inside Avante:
    • <leader>ama for Agent
    • <leader>amp for Plan
    • <leader>amq for Ask

Typical flow:

  1. Open a file or select code.
  2. Press <leader>aa to ask about it, or <leader>an to start clean.
  3. Type the prompt in the Avante input and submit.
  4. If needed, switch the Cursor-side mode with <leader>ama, <leader>amp, or <leader>amq before asking the next thing.

Also useful commands:

:AvanteAsk
:AvanteChat
:AvanteToggle
:AvanteModels

Full command list lives in the plugin: lazy/avante.nvim/plugin/avante.lua (user commands prefixed with Avante).

Providers and models (this repo)

Default provider is Cursor via ACP. The active provider is selected by the AVANTE_PROVIDER environment variable at Neovim startup.

Shell aliases (~/.extras.bash)

alias vim-cursor="AVANTE_PROVIDER=cursor nvim"
alias vim-claude="AVANTE_PROVIDER=claude nvim"
alias vim-codex="AVANTE_PROVIDER=codex nvim"
alias vim-ollama="AVANTE_PROVIDER=ollama nvim"

vim-cursor   # Cursor via ACP (default)
vim-claude   # Claude Sonnet
vim-codex    # OpenAI Codex
vim-ollama   # Local Ollama (https://ollama.dph.am)

Each alias deletes ~/.config/avante.nvim/config.json before launching so Avante's persisted last-provider doesn't override the profile. You can also pass the variable inline: AVANTE_PROVIDER=ollama nvim.

Named provider presets defined in avante.lua: openai-gpt, openai-codex, claude-haiku, claude-sonnet, ollama. Stock providers (openai, claude, copilot, vertex) are hidden from the model selector via hide_in_model_selector.

To switch provider or model programmatically inside Neovim: require("avante.api").switch_provider("…") or :AvanteSwitchProvider <name>.

UI integrations (this repo)

  • Input: Snacks.nvim (folke/snacks.nvim)
  • File picker for @ mentions: Telescope

Adding files to context

There are two practical ways to give Avante more context than the current buffer:

1. Add files from Neo-tree

From Neo-tree, press oa on a file to add that file to the current Avante context.

This is wired in lua/plugins/neo-tree.lua:

  • It opens Avante if needed
  • Adds the selected file via sidebar.file_selector:add_selected_file(...)
  • Leaves you in the Avante flow with that file attached

This is the fastest way to attach a couple of repo files before asking something like "compare these two modules" or "refactor based on both files".

2. Use @ file mentions

Avante is configured with Telescope as the file selector provider, so in the Avante input you can use @ mentions to search for and attach files.

Use this when:

  • Neo-tree is not open
  • You want to search by filename
  • You want to add more files while already typing a prompt

Good pattern:

  1. Start chat with <leader>an or <leader>aa.
  2. Add one or more files with Neo-tree oa or @ mentions.
  3. Then ask the question after the files are attached.

Troubleshooting

  • ACP / auth: Confirm agent login and agent status (or equivalent) in the terminal. On Mac over SSH, run security unlock-keychain first.
  • Binary path: Plugin expects ~/.local/bin/agent; adjust acp_providers.cursor.command if yours differs.
  • Provider not switching: Avante persists the last-used provider to ~/.config/avante.nvim/config.json and restores it on startup, overriding the config. The vim-* aliases delete this file automatically; if launching with nvim directly, remove it manually.
  • Plugin health: :Lazy for install/build (build = "make"), :checkhealth as usual.
  • /agent: If a Cursor release treats /agent differently, change the string in lua/plugins/avante.lua under the keys section or type the mode switch manually in the Avante input.

References