DOCSEARCHbyAlgolia
Submit Docs

codecompanion.nvim

repository·main·Indexed 24 days ago

https://github.com/olimorris/codecompanion.nvim

A Neovim plugin providing AI coding assistance via LLMs and Agents. It features a chat interface, inline transformations, and support for the Agent Client Protocol (ACP) and Model Context Protocol (MCP). The plugin includes advanced context management through context editing and compaction to handle token limits, as well as an Action Palette for managing chat buffers and prompt libraries.

Tokens
69.1K
Snippets
182
Records
302
Agent score
92%

What's inside codecompanion.nvim

  1. Overview of CodeCompanion.nvim features

    main

    CodeCompanion.nvim is an AI coding plugin for Neovim that integrates LLMs and CLI agents directly into your workflow.

    Key capabilities include:

    • Chat & Inline Editing: Use a chat buffer for conversations or perform inline transformations, code creation, and refactoring directly in your buffers.
    • LLM & Agent Support: Out-of-the-box support for major providers (Anthropic, OpenAI, Google Gemini, DeepSeek, etc.) via HTTP adapters and CLI agents (Claude Code, Copilot CLI, etc.) via Agent Client Protocol (ACP).
    • Advanced Context: Support for Model Context Protocol (MCP), editor context, slash commands, tools, and workflows to improve LLM output.
    • Rule Integration: Support for rule files like CLAUDE.md and .cursor/rules to guide AI behavior.
    • Multimodal Input: Support for images and PDFs as input.
    • Prompt Library: A built-in library for common tasks like explaining code or fixing LSP errors.

  2. Understand Agent Client Protocol (ACP) Support

    main

    CodeCompanion implements the Agent Client Protocol (ACP) to enable structured interaction between Neovim and AI agents. This allows for stateful sessions, tool execution, and file system operations.

    Key Features Supported:

    • Core Protocol: JSON-RPC 2.0, streaming responses, and message buffering.
    • File System: Reading and writing text files with line ranges.
    • MCP Integration: Supports Stdio, HTTP, and SSE transports.
    • Permissions: Interactive UI with diff previews for approving tool execution.
    • Session Management: Create, list, load, and restore sessions with state tracking.
    • Tool Calls: Support for content blocks, file diffs, and status updates.

    Current Limitations:

    • Terminal Operations: Agents cannot access a Neovim terminal (terminal/* methods are not implemented).
    • Agent Plans: Agent execution plans are received and logged but are not currently rendered in the chat UI.
    • Audio: Audio content cannot be sent or received.

  3. Understand CodeCompanion interactions

    main

    CodeCompanion operates through different types of interactions. The two primary interaction types are:

    1. Chat: Uses a dedicated buffer to allow for direct, conversational interaction with an LLM.
    2. Inline: Allows the LLM's output to be written directly into a pre-existing Neovim buffer (useful for refactoring or code generation).

    You can specify different adapters for each interaction type and for individual entries in your prompt library.

  4. Understand Tool Groups and Agents

    main

    Tool groups combine multiple tools into a single reference in the chat buffer using the @{group_name} syntax.

    Key Concepts:

    • Tool Groups: A collection of tools available to the LLM. By default, they appear as a single <group>name</group> reference. To show all tools as individual context items, set opts.collapse_tools = false on the group.
    • Agents: A tool group becomes an agent when it provides its own system_prompt. This allows the group to replace default system prompts with tailored instructions.
    • System Prompt Function: If system_prompt is a function, it receives (group, ctx). The ctx object provides access to language, date, nvim_version, os, and more.

  5. Understand the Tool Execution Lifecycle

    main

    The tool execution process follows this sequence:

    1. Prompting: The Chat Buffer sends the prompt including tool schemas to the LLM.
    2. Detection: The LLM responds with tool call(s), which the Tool System parses.
    3. Orchestration: The Tool System creates an Orchestrator with a queue of tool calls and fires the ToolsStarted autocmd.
    4. Execution Loop:
      • The Orchestrator pops a tool from the queue and sets up handlers.
      • If approval is required, the user is prompted.
      • For each command (cmds) in the tool, the function is executed.
      • Execution returns {status, data} (sync) or calls opts.output_cb (async).
      • The Orchestrator calls output.success() or output.error() based on the result.
      • Results are added to the chat buffer via add_tool_output().
    5. Cleanup: Once the queue is empty, handlers.on_exit() is called, the Tool System resets, and the ToolsFinished autocmd is fired.

  6. Understand CodeCompanion interaction types

    main

    CodeCompanion uses five main types of interactions to communicate with LLMs or agents:

    • Chat: A chat buffer for conversing with an LLM via :CodeCompanionChat.
    • CLI: A terminal wrapper for agent CLI tools like Claude Code or Opencode via :CodeCompanionCLI.
    • Inline: An interaction that writes code directly into the current buffer via :CodeCompanion.
    • Cmd: Allows creating custom Neovim commands via :CodeCompanionCmd.
    • Background: Runs background tasks like generating chat titles or compacting messages.

  7. Understand CodeCompanion context management

    main

    CodeCompanion manages LLM context windows to prevent conversations from ending due to token limits. It uses two preventative strategies: Context Editing and Compaction.

    Thresholds

    Context management is driven by two configurable thresholds based on the model's context window:

    1. Editing trigger (default 0.65): When the chat buffer crosses this threshold, context editing begins.
    2. Compaction trigger (default 0.85): If the buffer crosses this threshold, compaction runs.

    Context Editing

    Context editing is a low-risk operation that reduces token counts by replacing the content of older tool call results with a placeholder. It operates in cycles (one user turn plus all LLM responses/tool calls) to ensure agentic loops are not interrupted mid-process. By default, the most recent 3 cycles are preserved in full.

    Compaction

    Compaction is used when editing is no longer sufficient. It performs an LLM call to summarize the conversation history, replacing the history with that summary.

    Preserved items during compaction:

    • The system prompt.
    • Project rules (tagged via /rules).
    • Reference placeholders for files, buffers, and images (e.g., <important>File content for lua/foo.lua cleared during compaction. Re-read the file if you need it.</important>).

    Manual Control

    • Automatic: Editing and Compaction run automatically based on thresholds.
    • Manual: You can manually trigger compaction at any time using the /compact slash command.

  8. Understand CodeCompanion Tool Types

    main

    CodeCompanion supports two types of tools that allow LLMs to interact with Neovim:

    1. Command-based tools: Execute a series of commands asynchronously using vim.system. These are non-blocking and ideal for heavy or time-consuming tasks (e.g., running shell commands).
    2. Function-based tools: Execute Lua functions directly within the Neovim main process. These can be synchronous or asynchronous and are useful for direct Neovim API interactions.

  9. Invoke prompt library entries via keymaps

    main

    You can assign specific prompts from your prompt library to a Neovim keymap using the require("codecompanion").prompt("alias") function. Replace "alias" with the unique alias defined for your prompt.

    vim.keymap.set("n", "<LocalLeader>d", function()
  require("codecompanion").prompt("docs")
end, { noremap = true, silent = true })

  10. Use YOLO mode to bypass tool approvals

    main

    You can enable YOLO mode to automatically approve all tool executions without manual prompts.

    Warning: YOLO mode is dangerous. Only use it in environments where potential data loss can be recovered. You are responsible for any damage caused.

    To enable YOLO mode in the chat buffer, use the gty keymap.

    Limitations:

    • Certain tools are excluded from YOLO mode by default because they are considered too dangerous. These include run_command and delete_file (which have allowed_in_yolo_mode = false set).
    • If you have configured an LLM judge, tool commands are sent to the LLM to verify safety. If the judge succeeds, the verdict is cached for that session. If the judge fails or the adapter cannot produce structured output, manual approval will be required.