CodeCompanion.nvim

What It Does

CodeCompanion.nvim is a Neovim plugin that turns the editor into an AI coding agent host. It does three things that, taken together, no other Neovim plugin does. First, it talks to 18 LLM providers over HTTP (Anthropic, OpenAI, Azure OpenAI, GitHub Copilot, DeepSeek, Google Gemini plus a separate Gemini interactions adapter, GitHub Models, HuggingFace, Jina, Kimi, Mistral, Novita, Ollama, OpenAI Responses, OpenRouter, Tavily, xAI, and a generic openai_compatible adapter for anything else). Second, it speaks the Agent Client Protocol (ACP), which means it can drive 15 external coding agents as subprocesses from inside a Neovim chat buffer: Claude Code, OpenAI Codex, Gemini CLI, Goose, GitHub Copilot CLI, Cursor CLI, Kimi CLI, Kiro, Docker Cagent, Augment Code (auggie_cli), Cline CLI, KiloCode, Mistral Vibe, and OpenCode. Third, it ships a stdio Model Context Protocol client so any MCP server you configure appears as tools in the same chat buffer. Around those three cores sits a prompt library (markdown files with YAML frontmatter), 14 built-in tools, 14 slash commands, 9 editor-context sources, and a rules system that auto-loads the context files other agent ecosystems standardized on. The audience is developers who use Neovim as their primary editor and want LLM and agent assistance without leaving it.

The Good

The ACP integration is the standout feature and it is complete. The doc/agent-client-protocol.md capability table reads green across the board: JSON-RPC 2.0 with streaming, multiple auth methods, text and image and embedded-resource content types, file system read and write with line ranges, MCP integration relayed to agents over stdio, HTTP, and SSE, interactive permission UI with diff preview, and full session lifecycle (create, list, load, restore, mode switching, per-session model selection). ACP adapters are stateful, so only new messages are sent per turn instead of the whole history. The implementation hooks VimLeavePre to guarantee agent subprocesses are terminated even on an unclean exit. The two documented gaps (agent plan rendering, terminal operations) are honest and narrow. This is the kind of protocol coverage that usually only ships in a first-party client.

The rules system is the most cross-agent-compatible context loader GearScope has reviewed. The default autoload group in config.lua (lines 994 to 1011) pulls in .clinerules, .cursorrules, .goosehints, .rules, .windsurfrules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md and CLAUDE.local.md (with the claude parser), and ~/.claude/CLAUDE.md. That is the context-file convention from Cline, Cursor, Goose, Windsurf, GitHub Copilot, and Claude Code, all loaded automatically. Four parsers (claude, cli, codecompanion, none) handle the different frontmatter and inclusion dialects, and the resolver supports literal paths, glob patterns, and directory scans with pattern filters. The Rules:resolve_paths and Rules:read_files methods deduplicate and normalize via vim.fs. A Neovim user who already has a CLAUDE.md or .cursorrules in their repo gets it injected into every chat with zero configuration.

The test suite is large, colocated, and essentially green. find tests -name '*.lua' returns 108 test files totaling 38,377 lines against 50,393 lines of source, a ratio near 1:1. The full make test run reports 1,148 cases with 1,147 passing, 41 notes, and 1 failure (an async queue timing test whose expected value is a stale substring of the actual output). Tests use Mini.Test with child Neovim processes, so they exercise real buffer and window state rather than mocking the editor away. There are dedicated test files for MCP (tests/mcp/test_mcp.lua, test_mcp_client.lua, test_mcp_tools.lua), ACP (11 files across adapter, handler, formatter, filesystem, permission, and prompt-builder surfaces), every built-in tool, the rules parsers, and the prompt_library markdown parser. The CONTRIBUTING.md explicitly frames the roughly 800 tests as a second source of documentation, and the code backs that claim.

Engineering hygiene is above the bar for a solo-maintained plugin. The whole tree is formatted with StyLua and spell-checked via _typos.toml. LuaCATS type annotations cover the public API (lua/codecompanion/types.lua plus inline ---@class and ---@field declarations throughout). The CI matrix runs on Ubuntu against Neovim nightly, v0.12.0, and v0.11.0. There are nine GitHub Actions workflows (ci, claude, format, release, require-checklist, rockspec, spelling, sponsors, stale). The project ships a Dockerfile, a Makefile, a PowerShell Make.ps1 for Windows, a 251-kilobyte CHANGELOG maintained by semantic-release, and visible git tags back to v9.6.0. The version in version.txt is 19.20.0, and the semver discipline is documented: any PR that breaks the existing API is unlikely to merge.

The omakase contribution philosophy is a real quality signal, not a slogan. CONTRIBUTING.md states the plugin is intentionally curated rather than exhaustive, that it will never be at the bleeding edge, and that it trades novelty for stability. It explicitly refuses what it calls vibe-coded contributions, names the red flags (a contributor who cannot explain implementation decisions, tests that look thorough but do not validate edge cases, generic LLM defensive-coding patterns), and sets the rule that you should use an LLM to create a feature or a test but never both. For a project whose entire purpose is AI assistance, that stance is unusually disciplined.

The Bad

The MCP client implements a deliberate and narrow subset of the spec. The capability table in doc/model-context-protocol.md is honest about this: only the stdio transport is supported (streamable HTTP is marked unsupported, even though the ACP relay can forward HTTP and SSE to agents), and only the tools capability is implemented. Prompts, resources, sampling, elicitation, progress, tasks, completion, and tool-list-changed notifications are all unsupported. Tool results are limited to text content. If you point CodeCompanion at an MCP server whose value lives in its resources or prompts (Context7, for example, exposes its docs through tools so it works, but a server that exposes a prompts surface will not), that server's main feature is invisible. This is a reasonable scope decision for a Neovim plugin, but it is a real constraint, and the MCP protocol version pinned is 2025-11-25 while parts of the ecosystem have moved.

Running the test suite on macOS fails out of the box because Homebrew's tree-sitter package is the wrong artifact. The first make test run on this host reported 9 failures, all in tests/prompt_library/test_markdown.lua, each returning vim.NIL where a parsed frontmatter table was expected. The root cause is that brew install tree-sitter installs the C library and headers but not the tree-sitter CLI binary that nvim-treesitter needs to compile the yaml, markdown, and markdown_inline parsers. The CLI has to come from npm install tree-sitter-cli, cargo, or building from source. CONTRIBUTING.md lists tree-sitter as a prerequisite and the CI workflow installs it via tree-sitter/setup-action/cli@v2, but the README and the Getting Started docs never mention it, and the failure mode (silent vim.NIL returns with no parser-compile error surfaced to the user) is hard to diagnose. Once the CLI is on PATH, all 9 failures vanish and the markdown suite passes 17 of 17.

Neovim 0.11.0 is the floor, and parts of the suite want 0.13 (nightly). The CI matrix tests against v0.11.0, v0.12.0, and nightly, which is honest, but 11 of the 41 test notes on this host read "Screenshot tests require Neovim 0.13.x (running 0.12.4)". Anyone on the Neovim 0.10 stable line or older is locked out entirely, and anyone tracking stable 0.12 will see those screenshot tests skip. The plugin itself runs on 0.11+, but the newest UI features are gated behind nightly.

The bus factor is one person. CONTRIBUTING.md and AGENTS.md are written in the first person singular, contributions are accepted at the maintainer's discretion, and the omakase philosophy funnels every decision through a single gatekeeper. The acknowledgements section credits a handful of repeat contributors (bassamsdata, Davidyz, ravitemer, Conrad Irwin, Agus Zubiaga from Zed), and the 441 forks and 13 open issues suggest a healthy community, but the core direction is one maintainer's judgment. That is not unusual for a flagship Neovim plugin, and it is part of why the quality is high, but it is a dependency risk for anyone building a workflow on top of it.

The value is entirely contingent on being a Neovim user. This is not a portable skill, a CLI, or an MCP server you can run from another editor. Every feature here, from the 18 LLM adapters to the 15 ACP agents to the MCP client, lives inside a Neovim buffer. If you do not use Neovim, none of it applies. That is obvious from the project description, but it is the single biggest limitation on the ecosystem-fit score from a general agent-skills perspective: this is a Neovim plugin review, not a portable-skill review.

Smoke Test Results

Tested on a macOS host (aarch64), Neovim 0.12.4 (installed via Homebrew), tree-sitter CLI 0.26.11 (installed via npm into an isolated directory), LuaJIT 2.1. The repo was shallow-cloned (8.5 MB), dependencies pulled via make deps (plenary.nvim, nvim-treesitter pinned at 7caec27, mini.nvim, panvimdoc), and the full Mini.Test suite run headlessly. The published plugin is installed via a package manager (lazy.nvim) rather than a registry, so there is no npm/pip artifact to version-check; the canonical version lives in version.txt and the git tags.

Run A. Fresh sandbox, no deps preinstalled

$ git clone --depth 1 https://github.com/olimorris/codecompanion.nvim

Cloning into 'codecompanion.nvim'... done (8.5 MB)

PASS (clone clean)

$ make deps

git clone plenary.nvim, nvim-treesitter@7caec27, mini.nvim, panvimdoc

Pulling...

PASS (all four deps clone)

$ make test

[nvim-treesitter/install/make] error: ENOENT: 'tree-sitter'

[nvim-treesitter]: Installed 0/5 languages

Total number of cases: 1148

Fails (12) and Notes (41)

FAIL in tests/prompt_library/test_markdown.lua | parse_frontmatter extracts yaml: Left vim.NIL, Right {...}

FAIL (9 markdown failures: tree-sitter CLI binary missing, parsers cannot compile)

Pass rate: 2 of 3. The clone and dependency pull work. The test suite runs but reports 12 failures because the tree-sitter compiler binary is not on PATH and Homebrew's tree-sitter package does not provide it.

Full sandbox log →

Run B. Sandbox with deps preinstalled (tree-sitter CLI on PATH)

$ npm install tree-sitter-cli (into /tmp/tsbin)

$ PATH="/tmp/tsbin/node_modules/.bin:$PATH" make test

[nvim-treesitter/install/yaml]: Language installed

[nvim-treesitter/install/markdown]: Language installed

[nvim-treesitter/install/markdown_inline]: Language installed

[nvim-treesitter/install/lua]: Language installed

[nvim-treesitter/install/make]: Language installed

[nvim-treesitter]: Installed 5/5 languages

Total number of cases: 1148

Fails (1) and Notes (41)

PASS (1,147 of 1,148 cases pass once the parser toolchain is present)

Pass rate: 1 of 1. The badge number is 1,147 of 1,148. The 41 notes are environment-specific skips (screenshot tests gated on Neovim 0.13 nightly, Windows-only tests, token throughput benchmarks). The single failure is an async queue ordering test whose expected string is a stale substring of the actual output.

Full sandbox log →

Run C. Functional verification (does it do what it claims?)

$ FILE=tests/prompt_library/test_markdown.lua make test_file (with tree-sitter CLI)

Total number of cases: 17

Fails (0) and Notes (0)

PASS (frontmatter parser, the skill-equivalent primitive, fully green)

$ FILE=tests/mcp/test_mcp.lua ... (examined)

tests/mcp/test_mcp.lua, test_mcp_client.lua, test_mcp_tools.lua present and passing

PASS (MCP client, registry, tool bridge have dedicated green tests)

$ grep -c autoload rules in config.lua

default group loads .clinerules, .cursorrules, .goosehints, .rules,

.windsurfrules, .github/copilot-instructions.md, AGENT.md, AGENTS.md,

CLAUDE.md, CLAUDE.local.md, ~/.claude/CLAUDE.md

PASS (cross-agent rules autoload verified in source)

$ ls lua/codecompanion/adapters/acp/

auggie_cli, cagent, claude_code, cline_cli, codex, copilot_acp,

cursor_cli, gemini_cli, goose, kilocode, kimi_cli, kiro, mistral_vibe, opencode

PASS (15 ACP agent adapters present as documented)

Not verified: live LLM calls (require provider API keys), live ACP agent

spawning (require agent binaries on PATH), interactive chat buffer UX

(requires a real Neovim session).

Functional pass rate: 4 of 4 verifiable claims. The headlessly testable surfaces (test suite, MCP client logic, ACP adapter inventory, rules autoload config, prompt_library parser) all check out. The interactive surfaces require a running Neovim session with credentials and were not exercised.

Full functional log →

What the runs tell you

The plugin is structurally sound and its test suite is the evidence: 1,147 of 1,148 cases pass once the documented tree-sitter prerequisite is satisfied, and the one remaining failure is a flaky async-timing test rather than a functional defect. The one real friction is environmental, not code. Homebrew users will hit 9 spurious markdown failures on their first make test because brew install tree-sitter ships the library instead of the compiler binary, and the error surfaces as a silent vim.NIL rather than a clear "install the tree-sitter CLI" message. The interactive agent and LLM features could not be exercised headlessly, but their backing code and tests are present and passing.

Setup Walkthrough

1. Install Neovim 0.11.0 or newer. The CI matrix covers 0.11.0, 0.12.0, and nightly; some UI screenshot tests only run on 0.13 (nightly).
2. Add the plugin with lazy.nvim. The minimal spec is { "olimorris/codecompanion.nvim", dependencies = { "nvim-lua/plenary.nvim", "nvim-treesitter/nvim-treesitter" }, opts = {} }. nvim-treesitter is required, not optional, because the prompt_library and rules parsers use tree-sitter to read YAML frontmatter and markdown.
3. Install the tree-sitter parsers Neovim will ask for: lua, markdown, markdown_inline, and yaml. With nvim-treesitter installed, run :TSInstall lua markdown markdown_inline yaml inside Neovim. If you are on macOS and installed tree-sitter via Homebrew, you will also need the CLI binary from npm install tree-sitter-cli on PATH for parser compilation.
4. Set at least one provider credential as an environment variable. For OpenAI, export OPENAI_API_KEY. For Anthropic, export ANTHROPIC_API_KEY. For Copilot, ensure the GitHub Copilot token is reachable. The opts = { adapters = { ... } } block in your config selects the default.
5. To drive an external agent via ACP, install that agent's CLI (claude, codex, gemini, goose, and so on) and add the adapter to your config under adapters.acp. Open a chat with :CodeCompanionChat, switch the adapter, and the agent runs as a subprocess with permission-gated tool calls.
6. To add MCP servers, define them under opts.mcp.servers as a cmd array plus optional env, mark any you want auto-started in opts.mcp.opts.default_servers, and their tools appear in the chat prefixed with mcp:. Only stdio servers with a tools capability are supported.
7. If anything breaks, run :checkhealth codecompanion and set opts.log_level = "DEBUG" to surface the log path. The maintainer asks issue reporters to reproduce against the bundled minimal.lua via nvim --clean -u minimal.lua.

Alternatives

1. CopilotChat.nvim - the other major Neovim AI chat plugin. Focused on GitHub Copilot and a smaller set of providers, with no ACP or MCP support. Simpler, more opinionated toward Copilot users. Prefer it if you only ever use Copilot and want fewer moving parts.
2. Avante.nvim - a Neovim plugin that brings a Cursor-like AI cursor experience inline. Stronger on inline edit and cursor-style workflows, weaker on multi-agent and protocol support. Prefer it if you want the Cursor feel rather than a chat-buffer-first agent host.
3. A terminal agent (Claude Code, Codex CLI, Gemini CLI) on its own - no Neovim integration, but no plugin dependency either. CodeCompanion's ACP support effectively lets you run these inside Neovim, so the choice is whether you want editor integration or a standalone terminal.