buddy.nvim AGENTS.md

AGENTS.md - buddy.nvim

Guidelines for AI agents working in this Neovim plugin codebase.

Project Overview

buddy.nvim is an MCP (Model Context Protocol) server for Neovim, written in Lua. It provides a bridge between AI agents and Neovim via HTTP/SSE endpoints.

Build & Test Commands

# Dependencies (required before testing)
make deps          # Clone mini.nvim into deps/
make clean         # Remove deps/

# Testing
make test                              # Run all unit tests
make test-file FILE=tests/test_tools.lua  # Run single test file
make test-integration                  # HTTP/SSE endpoint tests (uses curl)
make test-all                          # Unit + integration tests

# Health check (inside Neovim)
:checkhealth buddy

Code Style Guidelines

Language & Runtime

• Language: Lua (LuaJIT)
• Runtime: Neovim's embedded Lua with vim.uv (libuv bindings)
• Testing: mini.test from mini.nvim
• LSP Config: .luarc.json configures LuaLS with Neovim globals

Naming Conventions

Element	Convention	Example
Variables/Functions	snake_case	tool_name, handle_request
Private functions	_snake_case	_accept, _dispatch
Modules/Classes	PascalCase	HTTPServer, JsonRpc
Constants	SCREAMING_SNAKE	MAX_BUFFER_SIZE

Module Structure

local M = {}

local dep = require("buddy.dep")  -- Core deps at top

local function _private_helper()       -- Private: underscore prefix
end

---@param arg string Description
---@return table|nil result
---@return string|nil error
function M.public_api(arg)             -- Public: on M table
  local lazy = require("buddy.lazy")  -- Lazy load optional deps
  return result, nil
end

return M

Type Annotations (LuaLS/EmmyLua)

---@class ToolDefinition
---@field name string Tool identifier
---@field description string Human-readable description
---@field args table<string, {type: string, description: string}>
---@field required? string[] Required argument names
---@field run fun(args: table, context: table): table Execution function