Problem: You Want AI in Neovim Without Browser Context Switching

You're tired of copy-pasting code between Neovim and Claude.ai. You want AI suggestions, refactoring, and chat directly in your Terminal where you already live.

You'll learn:

Install Avante.nvim with Lazy.nvim package manager
Configure Claude API integration
Use AI chat, inline edits, and smart completions
Set up keybindings that don't conflict with your workflow

Time: 15 min | Level: Intermediate

Why This Matters

Avante.nvim brings Claude (or other AI models) into your editor as a native plugin. No more alt-tabbing to browsers, no context loss, no manual copy-paste.

What makes Avante different:

Inline edits: AI modifies code in your buffer directly
Sidebar chat: Ask questions without leaving your file
Context-aware: Sends visible buffer content automatically
Model flexibility: Works with Claude, GPT-4, or local models

Common friction before Avante:

Breaking flow to use web UI
Losing cursor position when switching apps
Manually copying error messages to chat

Prerequisites

You need these installed first:

# Check versions
nvim --version  # Should be 0.9.0+
curl --version  # Any recent version

Required:

Neovim 0.9.0 or later
Lazy.nvim package manager (most common in 2026)
Anthropic API key (free tier works)

If you don't have Lazy.nvim:

# Install Lazy.nvim
git clone --filter=blob:none https://github.com/folke/lazy.nvim.git \
  ~/.local/share/nvim/lazy/lazy.nvim

Solution

Step 1: Get Your API Key

# Open Anthropic console
xdg-open https://console.anthropic.com/settings/keys 2>/dev/null || \
open https://console.anthropic.com/settings/keys

Create a new API key
Copy it (starts with sk-ant-)
Store it securely:

# Add to your shell profile
echo 'export ANTHROPIC_API_KEY="sk-ant-your-key-here"' >> ~/.bashrc
source ~/.bashrc

# Verify
echo $ANTHROPIC_API_KEY  # Should print your key

Why environment variable: Keeps secrets out of dotfiles you might push to GitHub.

Step 2: Add Avante to Lazy.nvim Config

Edit ~/.config/nvim/lua/plugins/avante.lua (or add to your existing plugins file):

return {
  "yetone/avante.nvim",
  event = "VeryLazy",  -- Load only when needed, not at startup
  
  dependencies = {
    "nvim-tree/nvim-web-devicons",  -- File icons
    "stevearc/dressing.nvim",       -- Better UI inputs
    "nvim-lua/plenary.nvim",        -- Utility functions
    "MunifTanjim/nui.nvim",         -- UI components
    
    -- Optional but recommended
    "nvim-treesitter/nvim-treesitter",  -- Better syntax understanding
  },
  
  opts = {
    provider = "claude",  -- Use Claude by default
    
    claude = {
      endpoint = "https://api.anthropic.com",
      model = "claude-sonnet-4-20250514",  -- Latest Sonnet
      temperature = 0,  -- Deterministic for code
      max_tokens = 8000,
    },
    
    -- UI behavior
    behaviour = {
      auto_suggestions = false,  -- Don't auto-trigger (can be distracting)
      auto_set_highlight_group = true,
      auto_apply_diff_after_generation = false,  -- Review before applying
    },
    
    -- Keybindings (customize these)
    mappings = {
      ask = "<leader>aa",        -- Open AI chat sidebar
      edit = "<leader>ae",       -- Inline edit selection
      refresh = "<leader>ar",    -- Regenerate response
      toggle = {
        default = "<leader>at",  -- Toggle sidebar
        debug = "<leader>ad",    -- Debug mode
      },
    },
    
    -- What to send as context
    windows = {
      wrap = true,  -- Wrap long lines in chat
      width = 30,   -- Sidebar width (% of screen)
      sidebar_header = {
        align = "center",
        rounded = true,
      },
    },
  },
}

Expected: When you run :Lazy sync, Avante installs with all dependencies.

If it fails:

Error: "treesitter not found": Install with :TSInstall lua markdown
API key error: Check echo $ANTHROPIC_API_KEY shows your key
Lazy.nvim issues: Update Lazy first with :Lazy update lazy.nvim

Step 3: Sync and Verify Installation

:Lazy sync

Wait for installation to complete (30-60 seconds), then:

:checkhealth avante

You should see:

✓ Anthropic API key found
✓ All dependencies installed
✓ Treesitter parsers available

Common warnings you can ignore:

"Optional dependency X not found" (unless you need that feature)

Step 4: Test Basic Usage

Open any code file:

nvim test.py

Try the chat:

Press <leader>aa (default: \aa if you haven't remapped leader)
Type: "Explain what this code does"
Press Enter

Expected: Sidebar opens on the right with AI response.

Try inline editing:

Select code in visual mode (V to select lines)
Press <leader>ae
Type: "Add error handling"
Review the diff, press <CR> to apply

Step 5: Customize for Your Workflow

Disable auto-context if you have large files:

-- In opts table
behaviour = {
  auto_set_keymaps = true,
  auto_apply_diff_after_generation = false,
  support_paste_from_clipboard = true,
},

-- Limit context size
hints = {
  enabled = true,
},

-- Only send visible lines, not entire buffer
windows = {
  position = "right",  -- or "left"
  width = 35,
  sidebar_header = {
    align = "center",
    rounded = true,
  },
},

Why limit context: Files over 1000 lines can hit token limits or slow down responses.

Advanced Configuration

Use Multiple Models

opts = {
  provider = "claude",  -- Default provider
  
  -- Define multiple providers
  providers = {
    claude = {
      model = "claude-sonnet-4-20250514",
      temperature = 0,
    },
    openai = {
      endpoint = "https://api.openai.com/v1",
      model = "gpt-4-turbo",
      api_key_name = "OPENAI_API_KEY",
    },
  },
  
  -- Switch with :AvanteProvider <name>
}

To switch models mid-session:

:AvanteProvider openai
:AvanteProvider claude

Custom Keybindings

Add to your main Neovim config:

-- In your init.lua or keys.lua
vim.keymap.set("n", "<C-a>", ":AvanteAsk<CR>", { desc = "AI: Quick ask" })
vim.keymap.set("v", "<C-a>", ":AvanteEdit<CR>", { desc = "AI: Edit selection" })

-- Quick prompts
vim.keymap.set("n", "<leader>ax", function()
  require("avante").ask("Explain this function")
end, { desc = "AI: Explain code" })

vim.keymap.set("n", "<leader>af", function()
  require("avante").ask("Find bugs in this code")
end, { desc = "AI: Find bugs" })

Per-Language Prompts

-- In opts table
system_prompt = function()
  local ft = vim.bo.filetype
  
  if ft == "rust" then
    return "You are a Rust expert. Focus on memory safety and idiomatic patterns."
  elseif ft == "python" then
    return "You are a Python expert. Use type hints and modern syntax."
  else
    return "You are a Coding Assistant. Be concise."
  end
end,

Verification

Test each feature:

" 1. Chat works
:AvanteAsk What does this function do?

" 2. Inline edit works
" Select code in visual mode, then:
:AvanteEdit Add docstrings

" 3. Model switching works
:AvanteProvider claude
:AvanteProvider openai  " If configured

" 4. Check health
:checkhealth avante

You should see:

Sidebar opens without errors
Code diffs appear in buffer
API calls succeed (check with :messages)

What You Learned

Avante.nvim brings AI directly into Neovim without browser context switching
Configuration lives in your Lua plugin files, not cluttering init.lua
Environment variables keep API keys secure
You can use multiple AI models and switch between them

Limitations:

Requires internet connection (unless using local models)
Context is limited to visible buffer—doesn't read entire project
API costs apply (though Claude's free tier is generous)

When NOT to use this:

You need AI to analyze 50+ files at once (use web UI with Projects)
Your terminal doesn't support proper color rendering
You're on a metered connection (API calls use bandwidth)

Troubleshooting

"API key not found"

# Verify environment variable
echo $ANTHROPIC_API_KEY

# If empty, add to shell profile
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc

Restart Neovim after setting the variable.

" Check if plugin loaded
:Lazy

" Look for avante.nvim in the list
" If not loaded, check for errors:
:messages

Common causes:

Lazy.nvim not installed in correct path
Dependencies missing (run :Lazy sync again)
Keybinding conflict (check with :map <leader>a)

Slow responses or timeouts

-- Increase timeout in config
claude = {
  timeout = 60000,  -- 60 seconds (default is 30)
  max_tokens = 4000,  -- Lower if hitting rate limits
}

Or reduce context size:

behaviour = {
  auto_suggestions = false,
  support_paste_from_clipboard = false,  -- Less data sent
}

Model version errors

" Check available models
:AvanteModels

" Update to latest model string
" Edit your config and change to current model name
" As of Feb 2026: claude-sonnet-4-20250514

Performance Tips

1. Lazy load the plugin:

event = "VeryLazy",  -- Don't load at startup
-- OR
keys = {
  { "<leader>aa", desc = "Avante Ask" },
  { "<leader>ae", desc = "Avante Edit", mode = "v" },
},

2. Disable if working offline:

-- In your init.lua
vim.g.avante_enabled = false  -- Toggle with :let g:avante_enabled=1

3. Clear chat history regularly:

:AvanteClear  " Clears sidebar history

Real-World Usage Examples

Debugging with AI

" 1. Hit an error
" 2. Copy error message
" 3. Press <leader>aa
" 4. Type: "Fix this error: <paste>"
" 5. Review suggested fix
" 6. Apply with <CR> or modify

Refactoring

" 1. Visual select old function (V motion)
" 2. Press <leader>ae
" 3. Type: "Extract into smaller functions"
" 4. Review diff
" 5. Apply or iterate

Learning New APIs

" 1. Paste API example code
" 2. <leader>aa: "Explain each parameter"
" 3. Get inline documentation without leaving editor

Tested on Neovim 0.10.0, Lazy.nvim 10.x, macOS Sonoma & Ubuntu 24.04 Avante.nvim version: 0.0.9 (Feb 2026) Claude API: claude-sonnet-4-20250514

Configure Avante.nvim AI Assistant in 15 Minutes