codecompanion.nvim

CodeCompanion abstracts multiple LLM providers (OpenAI, Anthropic, Ollama, DeepSeek, Google Gemini) behind a unified adapter interface, allowing users to swap providers without changing chat logic. The adapter system decouples HTTP-based API communication from interaction handling via a modular architecture where each adapter implements schema negotiation, request/response transformation, and streaming token handling. Users configure adapters per interaction type (chat, inline, cmd, background) independently, enabling different providers for different tasks.

CodeCompanion provides a dedicated chat buffer (filetype: codecompanion) that manages a full conversation history with context injection via three mechanisms: editor variables (#), slash commands (/), and tool references (@). Messages flow through a lifecycle (creation → context assembly → submission → streaming response → buffer rendering) where context is resolved at submission time, allowing dynamic file/selection changes mid-conversation. The buffer supports multi-turn conversations with role-based message formatting (user/assistant) and maintains state across Neovim sessions via optional persistence.

CodeCompanion provides a rules system that allows users to define custom system prompts and behavior modifications without editing core plugin code. Rules are Lua-based and can be applied globally or per-interaction, enabling fine-grained control over LLM behavior. The system supports rule composition (multiple rules applied in sequence) and conditional rule application based on context (file type, buffer state, etc.).

CodeCompanion integrates with the Model Context Protocol (MCP) to expose external tools and knowledge bases to LLMs. MCP servers (e.g., for file systems, databases, APIs) are registered as tool providers, and their capabilities are automatically exposed to the LLM via the tool-calling system. This enables LLMs to access external resources (files, databases, APIs) without CodeCompanion implementing provider-specific logic.

CodeCompanion provides an inline assistant interaction that generates code-adjacent content (documentation, comments, type hints) without full code generation. This interaction is optimized for smaller, focused tasks that enhance existing code. The inline assistant uses a dedicated prompt template and adapter configuration, enabling different behavior from full code generation.

CodeCompanion provides an action palette (accessible via :CodeCompanionActions or keybinding) that enables fuzzy-searchable discovery of available commands, interactions, and workflows. The palette displays all registered actions (chat, inline, cmd, etc.) with descriptions, allowing users to discover functionality without memorizing commands. Actions are extensible via Lua, enabling custom actions to appear in the palette.

The inline interaction enables direct code generation/modification in the current buffer via the :CodeCompanion command on visual selections or full buffer context. Generated code is presented as a unified diff in a preview buffer, allowing users to review changes before applying them. The system uses tree-sitter AST parsing (where available) to identify code boundaries and preserve formatting, then applies diffs via a custom diff engine that handles merge conflicts and partial application.

CodeCompanion implements native support for the Agent Client Protocol (ACP), enabling integration with stateful AI agents like Claude Code, Cline, and Kilocode. Unlike HTTP-based LLM adapters that are stateless, ACP adapters maintain agent state across multiple interactions, allowing agents to perform multi-step tasks (file reading, execution, iteration) without user intervention. The plugin communicates with ACP agents via stdio or HTTP, marshaling tool calls and responses through the ACP schema.

CodeCompanion provides a context variable system using # syntax (e.g., #file, #selection, #git_diff) that allows users to inject editor state into prompts. Variables are resolved at message submission time (not insertion time), enabling dynamic context binding where file changes after variable insertion are reflected in the final prompt. The system supports built-in variables (file, selection, buffer, git_diff, cwd) and extensible custom variables via Lua callbacks, allowing plugins to inject domain-specific context.

CodeCompanion provides a slash command system (/ syntax) that enables prompt templating and context assembly without manual typing. Built-in commands like /buffer, /help, /tests inject predefined context or trigger specific workflows. The system is extensible via Lua, allowing users to define custom slash commands that execute arbitrary logic (file reading, command execution, API calls) and inject results into the prompt. Slash commands are resolved at submission time, similar to context variables.

CodeCompanion implements tool calling via a schema-based function registry that maps LLM function calls to Lua implementations. When an LLM generates a tool call (e.g., OpenAI's function_calling or Anthropic's tool_use), the plugin parses the schema, validates arguments, executes the corresponding Lua function, and returns results to the LLM for further processing. Built-in tools include file operations (read, write, search), command execution, and agent references (@). The system supports both synchronous and asynchronous tool execution.

CodeCompanion provides a specialized :CodeCompanionCmd interaction that generates Neovim command-line commands (ex mode) based on natural language prompts. This interaction type uses a dedicated adapter and prompt template optimized for command generation, allowing users to request complex Vim commands without memorizing syntax. Generated commands are executed directly in Neovim's command-line mode, enabling automation of editor tasks.

CodeCompanion supports multimodal inputs (images) for LLM providers that support vision (Claude, GPT-4V). Images are encoded as base64 and embedded in chat messages, allowing users to include screenshots, diagrams, or code images in conversations. The system detects image file types and automatically encodes them for transmission to the LLM. Multimodal support is provider-specific; adapters must declare vision capability.

CodeCompanion supports a background interaction type that executes LLM operations silently without user intervention. Background interactions are triggered by internal callbacks (e.g., after chat creation) and use a dedicated adapter configuration. Common use cases include auto-generating chat titles and compacting long conversations to reduce token usage. Results are applied directly to the chat buffer without user approval.