codecompanion.nvim AGENTS.md

CodeCompanion.nvim

This is a Neovim plugin written in Lua, which allows developers to code with LLMs and agents from within Neovim. Tests use Mini.Test with child processes. Always run the full test suite after changes and ensure all tests pass before considering work complete.

Commands

• make format — StyLua (120 cols, 2 spaces). Run before committing.
• make test — full test suite (Mini.Test)
• make test_file FILE=path — targeted tests
• make docs — regenerate vimdoc. Run this after changing any docs pages

Code conventions

• Naming: snake_case for files/functions, PascalCase for classes, underscore prefix for private functions
• Explicit names: pattern not pat, should_include not include_ok
• Readable code: names, variables, and control flow should read like clean English. Avoid generic names like ctx — use domain-specific names (permission, request, source)
• Plain language: avoid jargon shortcuts in code, comments, commit messages, and chat. Don't say "no-op" — say what the code actually does ("returns unchanged", "does nothing", "skipped because already edited")
• Comments earn their place: don't restate what a readable line of code already says. If a guard like if type(x) ~= "number" then return end is self-evident, a comment explaining it is noise. Comment the why that isn't in the code (e.g. -- NOTE: Not handling token tables yet), not the what
• Don't narrate every change: the maintainer is an expert who knows this codebase. Do NOT add a comment to explain routine code (-- Clear the modified flag, -- Loop over the messages, -- Return early). Default to no comment. Reserve comments for genuinely non-obvious why — a subtle API quirk, a workaround, an ordering constraint — the kind of thing that would trip up even a reader who knows the codebase
• Function params: prefer a single table argument over positional args
• Error handling: pcall + log:error(), return nil on failure
• Type annotations: LuaCATS for public APIs. Keep doc blocks concise — one description line, params should be self-explanatory without inline comments
• Function descriptions: exactly one line. No multi-paragraph rationale, no usage examples, no "why we cache this" essays — that belongs in commit messages or a single inline -- comment at the relevant line. If you can't summarise the function in one line, the function is doing too much
• Functions: keep under 50 lines
• Globals: avoid; use module-local state
• Code blocks: use four backticks with language spec unless in a markdown file