agent.nvim

Overview

agent.nvim enables seamless communication with AI coding agents directly from Neovim via the Agent Client Protocol (ACP) — a JSON-RPC 2.0 protocol developed by Zed Industries. The plugin bridges Neovim and various AI agent implementations, handling complex communication while presenting a simple, user-friendly chat interface. Built-in adapters support Claude Code, Google Gemini CLI, and Zed Codex ACP.

Core Features

Multi-Provider Support

• Works with multiple AI providers through a unified adapter architecture
• Built-in adapters: Claude Code, Google Gemini CLI, Zed Codex ACP
• Extensible architecture for custom adapter implementations

Integrated Chat Interface

• Interactive chat window with message history and real-time streaming
• Input buffer with syntax awareness and customizable keybindings
• Session management with conversation history loading
• Recent chat sessions overlay for quick session access
• Status indicators and visual feedback for agent activity

File Operations

• AI agents can read file contents from the editor
• AI agents can write and modify code files
• Bidirectional file synchronization through ACP protocol
• Multiple edit strategies supported through tool implementations

Advanced UI Features

• Thinking state animations and visual indicators
• Tool call display with rich formatting
• Syntax highlighting for code blocks and messages
• Customizable window layout with configurable dimensions
• Hover-based interactive UI elements

Conversation Management

• Persistent session history with session titles
• Load and continue previous conversations
• Clear session functionality to start fresh

Completion Integration

• blink.cmp integration for intelligent autocomplete
• File path completion with @ trigger
• Chat command/slash command completion

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 Implementation

The plugin implements the full ACP lifecycle: initialize, authenticate, session creation, streaming prompt/response, and file operation handlers. Key aspects:

• Lifecycle Management: Initialize → Authenticate → Create Session → Send Prompts
• Bidirectional Messaging: Streaming updates from agent, file operations initiated by agent
• Tool Integration: Handle agent-initiated file reads/writes
• Session State Management: Track connection state, session ID, and conversation context

Each adapter wraps a CLI tool that already handles authentication, so there's no credential management inside the plugin. Supports multiple authentication methods per provider (Claude Code built-in auth, Codex with ChatGPT/OpenAI keys, Gemini with OAuth/API keys).

Use Cases

Primary Workflows:

• Code explanation and analysis with maintained conversation context
• Code generation and completion with contextual awareness
• Bug fixing and debugging with agent file access
• Refactoring and code improvement with direct modifications
• Documentation and comment generation
• Quick research and problem solving with session persistence

Target Users:

• Neovim developers seeking AI-assisted coding within their editor
• Teams using Claude, Gemini, or Codex who want editor integration
• Developers who prefer terminal/CLI workflows

Architecture

Core Modules:

• ACP Implementation (lua/agent/acp/): Connection management, protocol methods, adapter architecture, tool handlers
• Chat UI (lua/agent/interactions/chat/): State management, window layout (80/20 split), buffer management, message formatting
• UI Components (lua/agent/ui/): Syntax highlighting, message formatting, status indicators, animations
• Completion Integration (lua/blink-cmp-agent/): File path and command completion with smart triggers
• Utilities (lua/agent/utils/): Logging, async utilities, adapter resolution

Design Patterns:

• Adapter Pattern for modular AI provider support
• Event-Driven Architecture for streaming responses
• Fluent API for prompt construction
• Centralized state management
• Async/await with libuv

Stack

• Language: Lua (100% Lua-based plugin)
• Protocol: ACP (JSON-RPC 2.0)
• Target: Neovim 0.9+
• Integration: blink.cmp for autocomplete, vim.uv for async operations
• Testing: Built-in headless Neovim test runner