Overview
agent.nvim brings AI coding agents into Neovim via the Agent Client Protocol (ACP) — a JSON-RPC 2.0 protocol developed by Zed Industries. It ships with adapters for Claude Code, Gemini CLI, and Codex ACP, and exposes an integrated chat interface without leaving the editor.
Features
- Chat with Claude Code, Gemini, or Codex from a floating window inside Neovim
- AI agents can read and write files in your project
- Conversation history with a mouse-hoverable recent sessions overlay
- Uses existing CLI authentication — no extra API key setup
- Lua API for programmatic use
Usage
Open a chat session with :Agent or target a specific adapter:
:Agent " default adapter
:Agent claude " Claude Code
:Agent gemini " Gemini CLI
Inside the chat window, <C-CR> sends a message, q closes it, and <C-l> clears the session.
ACP protocol
The plugin implements the full ACP lifecycle: initialize, authenticate, session creation, streaming prompt/response, and file operation handlers (fs/read_text_file, fs/write_text_file). Each adapter wraps a CLI tool that already handles auth, so there's no credential management inside the plugin.
What I learned
Implementing a streaming JSON-RPC protocol inside Neovim's async model was the hardest part. Neovim's vim.loop handles I/O but the framing and partial-message handling had to be built carefully to avoid dropped chunks. The chat UI — especially the recent sessions overlay and the 80/20 window split — required more buffer management than expected to feel stable.
Stack
- Language: Lua
- Protocol: ACP (JSON-RPC 2.0)
- Adapters: Claude Code, Gemini CLI, Codex ACP
- Targets: Neovim 0.9+