nvim-aider

🤖 Seamlessly integrate Aider with Neovim for an enhanced AI-assisted coding experience!

🚧 This plugin is in initial development. Expect breaking changes and rough edges.

October 17, 2024

🌟 Features

• [x] 🖥️ Aider terminal integration within Neovim
• [x] 🎨 Color theme configuration support with auto Catppuccin flavor synchronization

• [x] 📤 Quick commands to add/drop current buffer files
• [x] 📤 Send buffers or selections to Aider
• [x] ♻️ Reset command to clear session
• [x] 💬 Optional user prompt for buffer and selection sends
• [x] 🩺 Send current buffer diagnostics to Aider
• [x] 🔍 Aider command selection UI with fuzzy search and input prompt
• [x] 🔌 Fully documented Lua API for

• [x] 🛡️ Command guard with status notifications to prevent interrupting Aider while it's processing
• [x] 🔄 Auto-reload buffers on external changes (requires 'autoread')

🧩 Integrations

• [x] 🌲➕ Neo-tree offers rich context management for Aider, including files, directories, and multi-selection
• [x] 🔖 bookmarks.nvim enables adding (optionally as read-only) or dropping files from Aider using saved bookmarks
• [x] 🌳 nvim-tree.lua enables adding or dropping individual files to Aider directly from its tree interface

🎮 Commands

• :Aider - Open interactive command menu

Commands:
  health         🩺 Check plugin health status
  toggle         🎛️ Toggle Aider terminal window
  send           📤 Send text to Aider (prompt if empty)
  command        ⌨️ Show slash commands
  buffer         📄 Send current buffer
   > diagnostics 🩺 Send current buffer diagnostics
  add            ➕ Add file to session
   > readonly    👀 Add as read-only reference
  drop           🗑️ Remove file from session
  reset          ♻️ Drop all files and clear chat history

• ⚡ Direct command execution examples:

:Aider health
  :Aider add readonly
  :Aider send "Fix login validation"
  :Aider reset

🔗 Requirements

🐍 Python: Install aider-chat 📋 System: Neovim >= 0.9.4, Working clipboard thanks to @milanglacier 🌙 Lua: folke/snacks.nvim ≥ v2.24.0, optionals catppuccin/nvim, nvim-neo-tree/neo-tree.nvim, nvim-tree.lua

📦 Installation

Using lazy.nvim:

{
    "GeorgesAlkhouri/nvim-aider",
    cmd = "Aider",
    -- Example key mappings for common actions:
    keys = {
      { "<leader>a/", "<cmd>Aider toggle<cr>", desc = "Toggle Aider" },
      { "<leader>as", "<cmd>Aider send<cr>", desc = "Send to Aider", mode = { "n", "v" } },
      { "<leader>ac", "<cmd>Aider command<cr>", desc = "Aider Commands" },
      { "<leader>ab", "<cmd>Aider buffer<cr>", desc = "Send Buffer" },
      { "<leader>a+", "<cmd>Aider add<cr>", desc = "Add File" },
      { "<leader>a-", "<cmd>Aider drop<cr>", desc = "Drop File" },
      { "<leader>ar", "<cmd>Aider add readonly<cr>", desc = "Add Read-Only" },
      { "<leader>aR", "<cmd>Aider reset<cr>", desc = "Reset Session" },
      -- Example nvim-tree.lua integration if needed
      { "<leader>a+", "<cmd>AiderTreeAddFile<cr>", desc = "Add File from Tree to Aider", ft = "NvimTree" },
      { "<leader>a-", "<cmd>AiderTreeDropFile<cr>", desc = "Drop File from Tree from Aider", ft = "NvimTree" },
    },
    dependencies = {
      { "folke/snacks.nvim", version = ">=2.24.0" },
      --- The below dependencies are optional
      "catppuccin/nvim",
      "nvim-tree/nvim-tree.lua",
      --- Neo-tree integration
      {
        "nvim-neo-tree/neo-tree.nvim",
        opts = function(_, opts)
          -- Example mapping configuration (already set by default)
          -- opts.window = {
          --   mappings = {
          --     ["+"] = { "nvimaideradd", desc = "add to aider" },
          --     ["-"] = { "nvimaiderdrop", desc = "drop from aider" }
          --     ["="] = { "nvimaideraddreadonly", desc = "add read-only to aider" }
          --   }
          -- }
          require("nvimaider.neotree").setup(opts)
        end,
      },
    },
    config = true,
  }

After installing, run :Aider health to check if everything is set up correctly.

⚙️ Configuration

There is no need to call setup if you don't want to change the default options.

require("nvim_aider").setup({
  -- Command that executes Aider
  aider_cmd = "aider",
  -- Command line arguments passed to aider
  args = {
    "--no-auto-commits",
    "--pretty",
    "--stream",
  },
  -- Automatically reload buffers changed by Aider (requires vim.o.autoread = true)
  auto_reload = false,
  -- Idle timeout in ms for Aider's output.
  idle_timeout = 5000,
  -- Response timeout in ms for Aider's first output chunk.
  response_timeout = 30000,
  -- Timeout in ms for quick commands.
  quickidletimeout = 500,
  -- A list of slash-commands that should have a shorter idle timeout.
  quick_commands = {
    "/add",
    "/drop",
    "/read-only",
    "/ls",
    "/clear",
    "/reset",
    "/undo",
  },
  -- Show 'Processing...' and 'Done' notifications.
  notifications = true,
  -- Theme colors (automatically uses Catppuccin flavor if available)
  theme = {
    userinputcolor = "#a6da95",
    tooloutputcolor = "#8aadf4",
    toolerrorcolor = "#ed8796",
    toolwarningcolor = "#eed49f",
    assistantoutputcolor = "#c6a0f6",
    completionmenucolor = "#cad3f5",
    completionmenubg_color = "#24273a",
    completionmenucurrent_color = "#181926",
    completionmenucurrentbgcolor = "#f4dbd6",
  },
  -- snacks.picker.layout.Config configuration
  picker_cfg = {
    preset = "vscode",
  },
  -- Other snacks.terminal.Opts options
  config = {
    os = { editPreset = "nvim-remote" },
    gui = { nerdFontsVersion = "3" },
  },
  win = {
    wo = { winbar = "Aider" },
    style = "nvim_aider",
    position = "right",
  },
})

📚 API Reference

The plugin provides a structured API for programmatic integration. Access via require("nvim_aider").api

Core Functions

local api = require("nvim_aider").api

health_check()

Verify plugin health status

api.health_check()

toggle_terminal(opts?)

Toggle Aider terminal window

api.toggle_terminal()

Terminal Operations

sendtoterminal(text, opts?)

Send raw text directly to Aider

api.sendtoterminal("Fix the login validation")

send_command(command, input?, opts?)

Execute specific Aider command

api.send_command("/commit", "Add error handling")

reset_session(opts?)

Drop all files and clear chat history

api.reset_session()

File Management

add_file(filepath)

Add specific file to session

api.add_file("/src/utils.lua")

drop_file(filepath)

Remove file from session

api.drop_file("/outdated/legacy.py")

addcurrentfile()

Add current buffer's file (uses add_file internally)

vim.api.nvimcreateautocmd("BufWritePost", {
  callback = function()
    api.addcurrentfile()
  end
})

dropcurrentfile()

Remove current buffer's file

api.dropcurrentfile()

addreadonly_file()

Add current buffer as read-only reference

api.addreadonly_file()

Buffer Operations

sendbufferwith_prompt(opts?)

Send entire buffer content with optional prompt

api.sendbufferwith_prompt()

senddiagnosticswith_prompt(opts?)

Send current buffer's diagnostics with an optional prompt

api.senddiagnosticswith_prompt()

UI Components

opencommandpicker(opts?, callback?)

Interactive command selector with custom handling

api.opencommandpicker(nil, function(picker, item)
  if item.text == "/custom" then
    -- Implement custom command handling
  else
    -- Default behavior
    picker:close()
    api.send_command(item.text)
  end
end)

🧩 Other Aider Neovim plugins

• aider.nvim
• aider.vim