# Agentic.nvim ![PR Checks](https://github.com/carlos-algms/agentic.nvim/actions/workflows/pr-check.yml/badge.svg)

Agentic.nvim logo

> ⚡ A Chat interface for AI agents in Neovim that works with any provider > supporting the [Agent Client Protocol (ACP)](https://agentclientprotocol.com) > — including Claude, Gemini, Codex, OpenCode, Cursor Agent, Copilot, Auggie, > Mistral Vibe, Cline, Goose, Kiro, Pi, and more. **Agentic.nvim** brings your AI assistant to Neovim through the implementation of the [Agent Client Protocol (ACP)](https://agentclientprotocol.com). You'll get the same results and performance as you would when using the ACP provider's official CLI directly from the terminal. Agentic.nvim is the interface, your agent is the Brain. This plugin will use all the same configurations and authentication methods you already have set up on your terminal. Including your MCP servers, commands, SKILLs, and sub-agents, you don't have to recreate your configuration to use Agentic.nvim. Sessions are interchangeable — start a conversation in Neovim and continue it in the terminal, or pick up a terminal session right inside Neovim. Your ACP provider manages sessions natively, so they're available everywhere. There're no hidden prompts or magic happening behind the scenes. Just a Chat interface, your colors, and your keymaps. ## Supported providers Works with **any** AI provider that implements the [Agent Client Protocol](https://agentclientprotocol.com), including, but not limited to:
Claude
Claude
Gemini
Gemini
Codex
Codex
OpenCode
OpenCode
Cursor
Cursor
Copilot
Copilot
Augment
Augment
Mistral Vibe
Mistral Vibe
Kiro
Kiro
Cline
Cline
Goose
Goose
Pi
Pi
_...and any future ACP-compatible provider._ ## ✨ Features - **⚡ Performance First** - Optimized for minimal overhead and fast response times - **🔌 Any ACP Provider** - Works with any AI provider that implements the Agent Client Protocol — Claude, Gemini, Codex, OpenCode, Cursor Agent, Copilot, Auggie, Mistral Vibe, Cline, Goose, Kiro, Pi, and any future ACP-compatible provider - **🔑 Zero Config Authentication** - No API keys needed - **Keep you secrets secret**: run `claude /login`, or `gemini auth login` once and, if they're working on your Terminal, they will work automatically on Agentic. - **🧠 Model Switcher** - Switch between available models mid-session (`m` in the chat widget) - **🔀 Switch Providers** - Switch between ACP providers mid-conversation without losing chat history (`s` in the chat widget) - **♻️ Session Restore** - Sessions are interchangeable between Neovim and terminal — continue any conversation anywhere - **📝 Context Control** - Add files and text selections to conversation context with one keypress - **🏞️ Image Support** - Drag-and-drop or paste images and screenshots directly into the chat - **🛡️ Permission System** - Interactive approval workflow for AI tool calls, mimicking Claude-code's approach, with 1, 2, 3, ... one-key press for quick responses - **🤖 Multiple sessions** - Run as many independent Chat sessions as you like, simultaneously, on different tasks. A session keeps working while hidden — closing its window or its tab does not stop it — and any session can be brought up in any tab - **🎯 Clean UI** - Sidebar interface with markdown rendering and syntax highlighting - **⌨️ Slash Commands** - Native Neovim completion for ACP slash commands with fuzzy filtering - Every slash command your provider has access too will apear when you type `/` in the prompt as the first character - **📁 File Picker** - Type `@` to trigger autocomplete for workspace files - Reference multiple files: `@file1.lua @file2.lua` - **🔄 Agent Mode Switching** - Switch between ACP-supported agent modes with Shift-Tab (Similar to Claude, Gemini, Cursor-agent, etc) - `Default`, `Auto Accept`, `Plan mode`, etc... (depends on the provider) - **ℹ️ Smart Context** - Automatically includes system and project information in the first message of each session, so the Agent don't spend time and tokens gathering basic info ## 🎥 Showcase ### Simple replace with tool approval: https://github.com/user-attachments/assets/4b33bb18-95f7-4fea-bc12-9a9208823911 ### Rich diff preview When editing files, if your provider asks for permission, you can see a diff preview side-by-side or inline, set your preference in your options: | Side-by-side | Inline | | ----------------------------------------------------- | ----------------------------------------- | | ![Side-by-side diff][preview-diff-side-by-side-image] | ![Inline diff][preview-diff-inline-image] | ### Dynamic layout rotation: right - bottom - left https://github.com/user-attachments/assets/000c5a9a-5469-44e3-b302-4074caa58fa9 ### Image and Screenshot support in the Chat Drag-n-Drop or paste an image from the Clipboard directly to the chat context: https://github.com/user-attachments/assets/6ae57136-9c08-4d71-bc8a-59babc49be4d ### Session restoration Start in the terminal, continue in Neovim — or the other way around! Agentic-session-restore ### 🐣 NEW: Switch agent mode: Always ask, Accept Edits, Plan mode... https://github.com/user-attachments/assets/96a11aae-3095-46e7-86f1-ccc02d21c04f ### Add files to the context: Add the current file to the Chat context or the selected text, let your agent know where you want it to work. https://github.com/user-attachments/assets/b6b43544-a91e-407f-834e-4b4de41259f8 ### Use `@` to fuzzy find any file: https://github.com/user-attachments/assets/c6653a8b-20ef-49c8-b644-db0df1b342f0 ## 📋 Requirements - **Neovim** v0.11.0 or higher - **ACP Provider CLI** - Install the CLI for any ACP-compatible provider of your choice - For security reasons, this plugin doesn't install or manage binaries for you. You must install them manually. **We recommend using `pnpm`** `pnpm` uses a constant, static global path, that's resilient to updates. While `npm` loses global packages every time you change Node versions using tools like `nvm`, `fnm`, etc... **You are free to chose** any installation method you prefer! | Provider | Install | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [claude-agent-acp][claude-agent-acp] | `pnpm add -g @agentclientprotocol/claude-agent-acp`
**OR** `npm i -g @agentclientprotocol/claude-agent-acp`
**OR** [Download binary][claude-agent-acp-releases] | | [gemini-cli][gemini-cli] | `pnpm add -g @google/gemini-cli`
**OR** `npm i -g @google/gemini-cli`
**OR** `brew install --cask gemini` | | [codex-acp][codex-acp] | `pnpm add -g @zed-industries/codex-acp`
**OR** `npm i -g @zed-industries/codex-acp`
**OR** [Download binary][codex-acp-releases] | | [opencode][opencode] | `pnpm add -g opencode-ai`
**OR** `npm i -g opencode-ai`
**OR** `brew install opencode`
**OR** `curl -fsSL https://opencode.ai/install \| bash` | | [cursor-agent][cursor-agent-docs] | `curl https://cursor.com/install -fsS \| bash` **OR** windows: `irm 'https://cursor.com/install?win32=true' \| iex`
**OR** See [Cursor docs][cursor-agent-docs] | | [copilot-cli][copilot-cli] | `pnpm add -g @github/copilot`
**OR** `npm i -g @github/copilot`
**OR** `brew install copilot-cli`
**OR** `curl -fsSL https://gh.io/copilot-install \| bash` | | [auggie][auggie] | `pnpm add -g @augmentcode/auggie`
**OR** `npm i -g @augmentcode/auggie`
**OR** See [Auggie docs][auggie-docs] | | [mistral-vibe][mistral-vibe] | `curl -LsSf https://mistral.ai/vibe/install.sh \| bash`
**OR** `uv tool install mistral-vibe`
**OR** `pip install mistral-vibe`
**OR** [Download binary][mistral-vibe-releases] | | [cline][cline] | `pnpm add -g cline`
**OR** `npm i -g cline`
**OR** See [Cline docs][cline-docs] | | [goose][goose] | `brew install block-goose-cli`
**OR** See [Goose docs][goose-docs] | | [kiro-cli][kiro-docs] | `curl -fsSL https://cli.kiro.dev/install \| bash`
**OR** See [Kiro CLI docs][kiro-docs] | | [pi-acp][pi-acp] | Requires the [`pi` CLI][pi-docs] installed first: `curl -fsSL https://pi.dev/install.sh \| sh`
**OR** `pnpm add -g @earendil-works/pi-coding-agent`
**OR** `npm i -g @earendil-works/pi-coding-agent`
Then the adapter: `pnpm add -g pi-acp` **OR** `npm i -g pi-acp` | > [!WARNING] > These install commands are here for convenience, please always refer to the > official installation instructions from the respective ACP provider. > [!NOTE] > Why install ACP provider CLIs globally? > [shai-hulud](https://www.wiz.io/blog/shai-hulud-2-0-ongoing-supply-chain-attack) > should be reason enough. 📌 Pin your versions! > But frontend projects with strict package management policies will fail to > start when using `npx ...` ## 📦 Installation ### lazy.nvim ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { -- Any ACP-compatible provider works. Built-in: "claude-agent-acp" | "gemini-acp" | "codex-acp" | "opencode-acp" | "cursor-acp" | "copilot-acp" | "auggie-acp" | "mistral-vibe-acp" | "cline-acp" | "goose-acp" | "kiro-acp" | "pi-acp" provider = "claude-agent-acp", -- setting the name here is all you need to get started }, -- these are just suggested keymaps; customize as desired keys = { { "", function() require("agentic").toggle() end, mode = { "n", "v", "i" }, desc = "Toggle Agentic Chat" }, { "", function() require("agentic").add_selection_or_file_to_context() end, mode = { "n", "v" }, desc = "Add file or selection to Agentic to Context" }, { "", function() require("agentic").new_session() end, mode = { "n", "v", "i" }, desc = "New Agentic Session" }, { "r", -- ai Restore function() require("agentic").restore_session() end, desc = "Agentic Restore session", silent = true, mode = { "n", "v", "i" }, }, { "ad", -- ai Diagnostics function() require("agentic").add_current_line_diagnostics() end, desc = "Add current line diagnostic to Agentic", mode = { "n" }, }, { "aD", -- ai all Diagnostics function() require("agentic").add_buffer_diagnostics() end, desc = "Add all buffer diagnostics to Agentic", mode = { "n" }, }, }, } ``` ## ⚙️ Configuration You don't have to copy and paste anything from the default config, linking it here for ease access and reference: [`lua/agentic/config_default.lua`](lua/agentic/config_default.lua). ### Customizing ACP Providers You can customize the built-in providers or add any new ACP-compatible provider by configuring the `acp_providers` property: > [!NOTE] > You don't have to override anything or include these in your setup! > These are just examples of how you can customize the commands, env, etc. ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { acp_providers = { -- Override existing provider (e.g., add API key) -- Agentic.nvim doesn't require API keys -- Only add it if that's how you prefer to authenticate ["claude-agent-acp"] = { env = { ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY"), }, }, -- Example of how override the ACP command to suit your installation, if needed ["codex-acp"] = { command = "~/.local/bin/codex-acp", }, -- Add any new ACP-compatible provider — the name and command are up to you ["my-cool-acp"] = { name = "My Cool ACP", command = "cool-acp", args = { "--mode", "acp" }, env = { COOL_API_KEY = os.getenv("COOL_API_KEY"), }, }, }, }, } ``` **Provider Configuration Fields:** - `command` (string) - The CLI command to execute (must be in PATH or absolute path) - `args` (table, optional) - Array of command-line arguments - `env` (table, optional) - Environment variables to set for the process - `default_mode` (string, optional) - Default mode ID to set on session creation (e.g., `"bypassPermissions"`, `"plan"`) - `initial_model` (string, optional) - Default model ID to set on session creation (e.g., `"haiku"`) - `default_thought_level` (string, optional) - Default thought effort level to apply on session creation (e.g., `"high"`, `"max"` for Claude) > [!NOTE] > Customizing a provider only requires specifying the fields you want to > override, not the entire configuration. ### Window Layout Configure the widget layout position and sizing: ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { windows = { position = "right", -- "right", "left", or "bottom" width = "40%", -- Sidebar width (position = "right" or "left") height = "30%", -- Panel height (position = "bottom") }, }, } ``` - `position` - Widget layout: `"right"` or `"left"` (vertical sidebar) or `"bottom"` (horizontal panel) - `width` - Sidebar width when `position` is right or left (percentage, decimal, or absolute) - `height` - Panel height when `position = "bottom"` (percentage, decimal, or absolute) ### Rotating Layouts dynamically at runtime You can rotate between layouts, dynamically, without closing Neovim with `rotate_layout()`. It acts on the session visible in the current tab page, and is a no-op when there is none: ```lua -- Rotates through all three layouts: right → bottom → left → right ... require("agentic").rotate_layout() -- Rotates between right and bottom only require("agentic").rotate_layout({ "right", "bottom" }) -- Rotates between right and left only require("agentic").rotate_layout({ "right", "left" }) ``` ### Customizing Window Options You can customize the behavior of individual chat widget windows by configuring the `win_opts` property for each window. These options override the default window settings. ### Customizing Window Headers You can customize the header text for each panel in the chat widget using either a table configuration or a custom render function. #### Table-Based Configuration ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { headers = { chat = { title = "󰻞 My Custom Chat Title", suffix = ": change mode", }, -- ... }, }, } ``` #### Function-Based Configuration For complete control over header rendering, provide a function that receives the header parts: ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { headers = { chat = function(parts) local header = parts.title if parts.context then header = header .. " [" .. parts.context .. "]" end if parts.suffix then header = header .. " • " .. parts.suffix end return header end, }, }, } ``` #### Live Session State Header and `buffer_name` functions receive an optional second argument, `session_state`, exposing live session data (current model, mode, thought level, context-window usage, cost, and provider name). The `session_state` argument is only provided for the **chat** and **input** panels. For every other panel it is `nil`. It is also `nil` on the very first frame and after a session restore until the next usage update arrives. Every getter is nil-able by contract — always nil-check before use. `SessionState` getters: | Getter | Returns | Notes | | -------------------------- | ------------- | ----------------------------------- | | `get_model_id()` | `string\|nil` | Current model id | | `get_model_name()` | `string\|nil` | Current model display name | | `get_mode_id()` | `string\|nil` | Current mode id | | `get_mode_name()` | `string\|nil` | Current mode display name | | `get_thought_level_id()` | `string\|nil` | Current thought level id | | `get_thought_level_name()` | `string\|nil` | Current thought level display name | | `get_context_used()` | `string\|nil` | Formatted context used | | `get_context_used_raw()` | `number\|nil` | Tokens currently in context | | `get_context_size()` | `string\|nil` | Formatted context window size | | `get_context_size_raw()` | `number\|nil` | Total context window size in tokens | | `get_cost_amount()` | `string\|nil` | Formatted cumulative session cost | | `get_cost_amount_raw()` | `number\|nil` | Cumulative session cost amount | | `get_cost_currency()` | `string\|nil` | Cost currency code (e.g. `"USD"`) | | `get_provider_name()` | `string\|nil` | Provider display name | Usage getters (`get_context_used`, `get_context_size`, `get_cost_amount`, `get_cost_currency`) stay `nil` until the agent emits the first usage update, and again after a session restore until the next one. ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { headers = { chat = function(parts, session_state) local header = parts.title if session_state then local used = session_state:get_context_used() if used then header = header .. " | " .. used .. " tok" end local cost = session_state:get_cost_amount() if cost then local currency = session_state:get_cost_currency() header = header .. " | " .. (currency and currency .. " " or "") .. cost end end return header end, }, }, } ``` ### Customizing Buffer Names By default, buffer names mirror the window header titles. You can override them independently via the `buffer_name` field in each window's config, for example to show cleaner names in your statusline or buffer switcher: ```lua { "carlos-algms/agentic.nvim", opts = { windows = { chat = { buffer_name = "Agentic Chat" }, input = { buffer_name = "Agentic Prompt" }, code = { buffer_name = "Code Snippets" }, files = { buffer_name = "Files" }, diagnostics = { buffer_name = "Diagnostics" }, todos = { buffer_name = "Tasks" }, }, }, } ``` You can also use a function that receives the header parts and returns a string: ```lua { "carlos-algms/agentic.nvim", opts = { windows = { chat = { buffer_name = function(parts) return "AI: " .. parts.title end, }, }, }, } ``` `buffer_name` functions also receive the optional `session_state` second argument (chat and input panels only, `nil` elsewhere). See [Live Session State](#live-session-state) for the getter list and nil-check rules. When a panel has no `buffer_name` set, it falls back to the header title. ### Folding Completed tool call outputs are automatically folded to keep the chat buffer readable. Failed tool calls stay open unless `fold_on_error` is enabled. ```lua --- @type agentic.PartialUserConfig opts = { folding = { tool_calls = { enabled = true, threshold = 10, fold_on_error = false, }, }, } ``` Set `threshold = 0` to always fold completed calls, and failed calls when `fold_on_error = true`. Negative values are clamped to 0. Set `enabled = false` to disable folding entirely. The fold hides the body only - the tool call header and completion status remain visible. Use standard Vim fold commands (`za`, `zo`, `zc`) to toggle individual folds, or `zR`/`zM` to open/close all folds in the chat window. ### Tool Call Titles Long non-diff titles for configured tool call kinds are truncated in the header and shown in full as the first body block. ```lua --- @type agentic.PartialUserConfig opts = { tool_calls = { title = { max_length = 50, truncate_title_kinds = { "execute", "think", "SubAgent", "fetch", "search", }, }, }, } ``` Only `truncate_title_kinds` are affected by `max_length`. Titles longer than `max_length` are truncated to `max_length` bytes plus `...`; the full title is rendered in the folded body. Set `max_length = 0` to disable title truncation. Negative values are clamped to 0. Diff tool calls keep full header-only titles. ## 🚀 Usage (Public Lua API) ### Commands | Function | Description | | ------------------------------------------------------------ | ----------------------------------------------------------------- | | `:lua require("agentic").toggle()` | Toggle chat sidebar | | `:lua require("agentic").open(opts)` | Open chat sidebar (keep open if already visible) | | `:lua require("agentic").close()` | Hide chat sidebar (session keeps running; nothing is destroyed) | | `:lua require("agentic").add_selection()` | Add visual selection to context | | `:lua require("agentic").add_file()` | Add current file to context | | `:lua require("agentic").add_selection_or_file_to_context()` | Add selection (if any) or file to the context | | `:lua require("agentic").add_files_to_context(opts)` | Add a list of file paths or buffer numbers to context | | `:lua require("agentic").add_current_line_diagnostics()` | Add diagnostics at cursor line to context | | `:lua require("agentic").add_buffer_diagnostics()` | Add all diagnostics from current buffer to context | | `:lua require("agentic").new_session()` | Start a new session; choose what happens to the current one | | `:lua require("agentic").destroy_session(opts)` | Destroy a session and its widget | | `:lua require("agentic").select_session()` | Pick any live session from a list and open it here | | `:lua require("agentic").next_session()` | Open the next session, wrapping at the end | | `:lua require("agentic").prev_session()` | Open the previous session, wrapping at the start | | `:lua require("agentic").new_session_with_provider()` | Pick a provider, then start a new session with it | | `:lua require("agentic").stop_generation()` | Stop current generation or tool execution (session stays active) | | `:lua require("agentic").restore_session()` | Show provider's session picker to restore a previous session | | `:lua require("agentic").restore_session_by_id(session_id)` | Restore a session by its ID | | `:lua require("agentic").switch_provider()` | Switch ACP provider mid-session (shows picker, preserves history) | | `:lua require("agentic").rotate_layout()` | Rotate window position through layouts (right → bottom → left) | ### Optional Parameters Open and Toggle supports optional parameter: - **auto_add_to_context** (boolean, default: `true`) - Whether to automatically add the current visual selection or file to context when opening the Chat ```lua -- Open the chat without adding anything to context require("agentic").open({ auto_add_to_context = false }) ``` When adding files or selections to context, you can also specify whether to focus the prompt input after opening the chat: - **focus_prompt** (boolean, default: `true`) - Whether to move cursor to prompt input after opening the chat Available on: `add_selection(opts)`, `add_file(opts)`, `add_selection_or_file_to_context(opts)`, `add_files_to_context(opts)`, `add_current_line_diagnostics(opts)`, `add_buffer_diagnostics(opts)` ```lua -- Add selection without focusing the prompt require("agentic").add_selection({ focus_prompt = false }) ``` `add_files_to_context(opts)` accepts a **files** field with a list of file paths (strings) or buffer numbers (integers). It can be used from anywhere, like your file picker. ```lua -- Add specific files by path require("agentic").add_files_to_context({ files = { "src/main.lua", "src/utils.lua", }, }) -- Add files by buffer number require("agentic").add_files_to_context({ files = { 1, 5 }, focus_prompt = false, }) ``` `restore_session_by_id(session_id)` accepts a **session_id** argument with the ID of the session you want to restore. Session IDs come from your provider's session storage (e.g. provider logs, project metadata, or scripts that track them). Unlike `restore_session()`, this does not require the provider to support listing sessions. ```lua -- Restore a session by ID require("agentic").restore_session_by_id("58e5cf8a-1277-4e43-bc29-10c1246a2c66") ``` ### Working with Multiple Sessions Sessions are not tied to tabs. Each one gets a **session key** — a small integer assigned at creation and stable for its whole life. - A session keeps running while hidden. `q`, closing the window, or closing the tab neither stops nor loses it - Opening a session in a tab hides whatever session was there and removes it from any other tab. At most one session is visible per tab - Use `destroy_session()` to end a session directly With a current session present, `new_session()` asks whether to keep it running in the background or destroy it after the new target session is ready. Choose one callback location for a new ACP session. Use the global callback for a default: ```lua require("agentic").setup({ acp_configs = { session_cwd = function(current_cwd) return vim.fs.root(current_cwd, ".git") end, }, }) ``` Use a per-call callback for a one-off directory: ```lua require("agentic").new_session({ cwd = function(current_cwd) return current_cwd .. "/packages/api" end, }) ``` The callback receives Neovim's current CWD and must return an absolute path or `nil`. A per-call callback overrides the global default. Invalid results fall back to the global callback, then Neovim's current CWD. This affects new ACP sessions only. `destroy_session(opts)` takes a **session** field naming the key to destroy. Without it, it destroys the session visible in the current tab, falling back to the most recently opened one. ```lua -- Destroy session 2 without opening it require("agentic").destroy_session({ session = 2 }) ``` Session keys appear in chat buffer names once more than one session exists. `select_session()` lists every live session by title, marking the one visible in the current tab. ### Built-in Keybindings These keybindings are automatically set in Agentic buffers: | Keybinding | Mode | Description | | ---------------- | ----- | --------------------------------------------------------------- | | `` | n/v/i | Switch agent mode (only available if provider supports modes) | | `` | n | Submit prompt | | `` | n/v/i | Submit prompt | | `p` | n | Paste image from clipboard in the Prompt buffer | | `` | i | Paste image from clipboard (same as Claude-code) | | `` | i | Accept file completion | | `s` | n | Switch ACP provider (preserves chat history) | | `m` | n | Switch model (keeps history) | | `t` | n | Select thought effort level (model-dependent on Claude) | | `o` | n | Open options modal | | `l` | n | List every live session and open the chosen one | | `]` | n | Open the next session | | `[` | n | Open the previous session | | `D` | n | Destroy the current session | | `q` | n | Hide chat widget (session keeps running) | | `d` | n | Remove file, code selection, or diagnostic at cursor | | `d` | v | Remove multiple selected files, code selections, or diagnostics | | `]]` | n | Navigate to next chat heading | | `[[` | n | Navigate to previous chat heading | | `]t` | n | Navigate to next tool call | | `[t` | n | Navigate to previous tool call | | `]c` | n | Navigate to next diff hunk (when diff preview is active) | | `[c` | n | Navigate to previous diff hunk (when diff preview is active) | #### Customizing Keybindings You can customize the default keybindings by configuring the `keymaps` option in your setup: ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { keymaps = { -- Keybindings for ALL buffers in the widget (chat, prompt, code, files) widget = { close = "q", -- String for a single keybinding change_mode = { { "", mode = { "i", "n", "v" }, -- Specify modes for this keybinding }, }, switch_provider = "s", -- Switch ACP provider switch_model = "m", -- Switch model change_thought_level = "t", -- Select thought effort level open_options = "o", -- Open options modal select_session = "l", -- List and open a session next_session = "]", -- Open the next session prev_session = "[", -- Open the previous session destroy_session = "D", -- Destroy the current session }, -- Keybindings for the prompt buffer only prompt = { submit = { "", -- Normal mode, just Enter { "", mode = { "n", "v", "i" }, }, }, paste_image = { { "p", mode = { "n" }, }, { "", -- Same as Claude-code in insert mode mode = { "i" }, } }, }, -- Keybindings for chat buffer navigation chat = { next_heading = "]]", prev_heading = "[[", next_tool_call = "]t", prev_tool_call = "[t", }, -- Keybindings for diff preview navigation diff_preview = { next_hunk = "]c", prev_hunk = "[c", }, -- Keybindings to cycle focus between pending permission blocks. -- Once a block is focused, per-block keys cycle the stacked button -- rows (one button per row, rendered between bottom_pad and the -- status row): -- h / / k / : focus previous button -- l / / j / : focus next button -- : submit focused button -- 1..4 : submit option N directly -- Per-block keys only fire while a block is focused. permission = { cycle_next = "", cycle_prev = "", }, }, }, } ``` **Keymap Configuration Format:** - **String:** `close = "q"` - Simple keybinding (normal mode by default) - **Array:** `submit = { "", "" }` - Multiple keybindings (normal mode only) - **Table with mode:** `{ "", mode = { "i", "v" } }` - Keybinding with specific modes The header text in the chat and prompt buffers will automatically update to show the appropriate keybinding for the current mode. ### Diff Preview When the agent makes file edits, agentic.nvim can show a preview of the changes before you accept or reject them. You can configure the diff preview layout: ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { diff_preview = { enabled = true, layout = "split", -- "split" or "inline" center_on_navigate_hunks = true, }, }, } ``` **Layout Options:** - `"split"` (default) - Side-by-side diff view - `"inline"` - Unified diff view in a single buffer **Navigation:** Use `]c` and `[c` to navigate between diff hunks (configurable). **Note:** Changing the layout requires restarting Neovim. ### Slash Commands Type `/` in the Prompt buffer to see available slash commands with auto-completion. The `/new` command is always available to start a new session. With a current session present, it asks whether to keep that session running in the background or destroy it. Other commands are provided by your ACP provider. ### File Picker You can reference and add files to the context by typing `@` in the Prompt. It will trigger the native Neovim completion menu with a list of all files in the current workspace. - **Automatic scanning**: Uses `rg`, `fd`, `git ls-files`, or lua globs as fallback - **Fuzzy filtering**: uses Neovim's native completion to filter results as you type - **Multiple files**: You can reference multiple files in one prompt: `@file1.lua @file2.lua` ### Image and Screenshots support You can drag-and-drop images into the Prompt buffer or paste images and screenshots directly from your clipboard. The support still depends on the ACP provider capabilities, but most of them support images in the conversation. Drag-and-drop should work out of the box if your terminal supports it, no need for extra configuration or plugins. In SSH/headless sessions, image paste and drag-and-drop usually do not reach remote Neovim, terminal and protocol limitations. Agentic does not copy local files into the remote filesystem; upload the image first with `scp`, `SFTP`, or your usual file-transfer workflow, then attach the remote file path using the `@...` notation. Pasting screenshots from your clipboard works out of the box on macOS, Windows, and WSL when Windows interop and `wslpath` are available. On Linux, you need one small CLI dependency: - **macOS**: no extra install. Uses the system `osascript`. - **Windows**: no extra install. Uses the bundled `powershell.exe`. - **WSL**: no extra install when Windows interop and `wslpath` are available. - **Linux (Wayland)**: install `wl-clipboard` (provides `wl-paste`). - Debian/Ubuntu: `sudo apt install wl-clipboard` - Arch: `sudo pacman -S wl-clipboard` - Fedora: `sudo dnf install wl-clipboard` - **Linux (X11)**: install `xclip`. - Debian/Ubuntu: `sudo apt install xclip` - Arch: `sudo pacman -S xclip` - Fedora: `sudo dnf install xclip` Then just press `p` in the Prompt buffer to paste the image from your clipboard. ### Session Restoration Sessions are interchangeable between Neovim and the terminal. Start a conversation in your terminal CLI, then load it in Neovim — or the other way around. Your ACP provider manages sessions natively, so they're available everywhere the provider runs. **Restoring sessions:** Call `require("agentic").restore_session()` to: 1. See a list of previous sessions from your provider for the current project (including sessions started in the terminal) 2. Select a session to restore the full conversation history If you know the session ID, call `require("agentic").restore_session_by_id(session_id)` to restore a specific session directly. This skips listing sessions, so it also works with providers that don't support session listing. With a current session present, restoration uses the same lifecycle choice as `new_session()`: keep the current session running in the background or destroy it. Selecting the ACP session already owned by the current session is a no-op; that session is never destroyed. Otherwise, the current session stays visible while the selected target loads. Success shows the target and preserves the visible widget size. The source is destroyed only when `Destroy current session` was selected. Failure or picker cancellation leaves the current session unchanged. With no current session, selecting a restore creates only the load target. The picker and session listing do not create a placeholder session. ### System Information Agentic automatically includes environment and project information in the first message of each session: - Platform information (OS, version, architecture) - Shell and Neovim version - Current date - Git repository status (if applicable): - Current branch - Changed files - Recent commits (last 3) - Project root path This helps the AI Agent understand the context of the current project without having to run additional commands or grep through files, the goals is to reduce time for the first response. To add your own text after that block, return a string from the `before_first_prompt` [event hook](#event-hooks). ### Event Hooks Agentic.nvim provides hooks that let you respond to specific events during the chat lifecycle. These are useful for logging, notifications, analytics, or integrating with other plugins. Every hook is fire-and-forget except `before_first_prompt`. That one runs synchronously while the first prompt is being built, and its return value is appended after the system information, so it can read files or run commands. A slow `before_first_prompt` delays that prompt. > [!IMPORTANT] > **Identify a session by `data.session_key`, not by `data.tab_page_id`.** > `session_key` is the session's registry key and never changes. `tab_page_id` > only says which tab the session shows in **right now**, and is **`nil` for a > session running in the background** — hidden, or in a closed tab. Hooks like > `on_session_update` and `on_response_complete` fire for background sessions, so > guard `tab_page_id` before passing it to any `nvim_tabpage_*` call; those raise > on `nil`. ```lua -- Token usage per session, keyed by session_key. A plain Lua table: a session is -- not tied to a tab and may be running in no tab at all. local agentic_usage = {} return { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { hooks = { -- Runs synchronously while the first prompt is built. Returns text -- appended after the system information, or nil for nothing. before_first_prompt = function(data) -- data.session_id: string - The ACP session ID -- data.session_key: integer - Stable session identity -- data.provider_name: string - The provider running the session if vim.fn.filereadable("AGENTS.md") == 1 then return "This project documents its conventions in AGENTS.md." end end, -- Called when a new ACP session is created (or fails to create). -- Fires on both success and failure; check `data.err` first. on_create_session_response = function(data) -- data.session_id: string|nil - The ACP session ID (nil if err is set) -- data.session_key: integer - Stable session identity -- data.tab_page_id: number|nil - Tab the session shows in right now; -- nil when it is running in the background -- data.response: table|nil - The ACP session creation response -- (nil if err is set) -- data.err: table|nil - Error details if session creation failed if data.err then vim.notify( "Session failed: " .. vim.inspect(data.err), vim.log.levels.ERROR ) return end vim.notify("New session: " .. data.response.sessionId) -- Reset this session's usage counter (set by the on_session_update -- example below). agentic_usage[data.session_key] = nil end, -- Called when the user submits a prompt on_prompt_submit = function(data) -- data.prompt: string - The user's prompt text -- data.session_id: string - The ACP session ID -- data.session_key: integer - Stable session identity -- data.tab_page_id: number|nil - nil for a background session vim.notify("Prompt submitted: " .. data.prompt:sub(1, 50)) end, -- Called when the agent finishes responding on_response_complete = function(data) -- data.session_id: string - The ACP session ID -- data.session_key: integer - Stable session identity -- data.tab_page_id: number|nil - Where the session is when the response -- completed, not where it was when the prompt was submitted -- data.success: boolean - Whether response completed without error -- data.error: table|nil - Error details if failed if data.success then vim.notify("Session " .. data.session_key .. " finished!") else vim.notify("Agent error: " .. vim.inspect(data.error), vim.log.levels.ERROR) end end, -- Called when the session is updated. -- Fires for background sessions too, so key everything off session_key. -- Skipped during session restore. on_session_update = function(data) -- data.session_id: string - The ACP session ID -- data.session_key: integer - Stable session identity -- data.tab_page_id: number|nil - nil for a background session -- data.update: table -- The update if data.update.sessionUpdate == "usage_update" then -- Use this in your status line, scoped per session. agentic_usage[data.session_key] = { used = data.update.used, size = data.update.size, } end end, -- Called after Agentic writes to a file (file-mutating tool call completed). -- Note: mutating the file here (e.g. formatters that save) can cause the -- agent to re-read or retry edits on its next action. on_file_edit = function(data) -- data.filepath: string - Absolute path to the edited file -- data.session_id: string - The ACP session ID -- data.session_key: integer - Stable session identity -- data.tab_page_id: number|nil - nil for a background session -- data.bufnr: number|nil - Buffer number if the file is loaded if data.bufnr then vim.lsp.buf.format({ bufnr = data.bufnr, timeout_ms = 5000 }) end end, -- Called when the agent needs permission to execute a tool (e.g. shell command). -- Fires for each pending permission request. on_request_permission = function(data) -- data.request: table - The ACP permission request object -- data.request.toolCall: table - contains .kind, .title, etc. -- data.session_id: string - The ACP session ID -- data.session_key: integer - Stable session identity -- data.tab_page_id: number|nil - nil for a background session local tool = data.request.toolCall local label = tool.title or tool.kind or "action" vim.notify("Agent needs permission for: " .. label) end, } } } ``` **Migrating from `tab_page_id`:** it used to be a `number` always naming a live tabpage. It is now `number|nil`, a placement hint only. Anything using it as an identity or storage key — `vim.t[data.tab_page_id]`, `nvim_tabpage_is_valid(data.tab_page_id)` — should move to `data.session_key`. If you genuinely need the tab (to render into it, say), guard it: ```lua if data.tab_page_id and vim.api.nvim_tabpage_is_valid(data.tab_page_id) then -- the session is visible in that tab end ``` ## 🍚 Customization (Ricing) Agentic.nvim uses custom highlight groups that you can override to match your colorscheme. ### Available Highlight Groups | Highlight Group | Purpose | Default | | --------------------------------- | ---------------------------------------- | ----------------------------------- | | `AgenticDiffDelete` | Deleted lines in diff view | Links to `DiffDelete` | | `AgenticDiffAdd` | Added lines in diff view | Links to `DiffAdd` | | `AgenticDiffDeleteWord` | Word-level deletions in diff | `bg=#9a3c3c, bold=true` | | `AgenticDiffAddWord` | Word-level additions in diff | `bg=#155729, bold=true` | | `AgenticStatusPending` | Pending tool call status indicator | `bg=#5f4d8f` | | `AgenticStatusCompleted` | Completed tool call status indicator | `bg=#2d5a3d` | | `AgenticStatusFailed` | Failed tool call status indicator | `bg=#7a2d2d` | | `AgenticPermissionButtonAllow` | Focused button (allow kind) | `bg=#2d5a3d, bold=true` | | `AgenticPermissionButtonReject` | Focused button (reject kind) | `bg=#7a2d2d, bold=true` | | `AgenticPermissionButtonInactive` | Non-focused permission button | `bg=#3a3a3a` | | `AgenticCodeBlockFence` | The left border decoration on tool calls | Links to `Directory` | | `AgenticTitle` | Window titles in sidebar | `bg=#2787b0, fg=#000000, bold=true` | | `AgenticThinking` | Thinking block text in chat buffer | Links to `Comment` | If any of these highlight exists, Agentic will use it instead of creating new ones. ### Customizing Diagnostic Icons You can customize the icons used for diagnostics in the context panel: ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { diagnostic_icons = { error = "❌", -- Diagnostic severity: error warn = "⚠️", -- Diagnostic severity: warning info = "ℹ️", -- Diagnostic severity: information hint = "✨", -- Diagnostic severity: hint }, }, } ``` Default icons use emoji characters (❌, ⚠️, ℹ️, ✨) but you can use any string, including Nerd Font icons or plain text. ### Customizing Status Icons You can customize the icons used to indicate tool call status in the chat: ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { status_icons = { pending = "󰔛", -- Tool call awaiting execution in_progress = "󰔛", -- Tool currently executing completed = "✔", -- Tool executed successfully failed = "", -- Tool execution failed }, }, } ``` ### Customizing Permission Icons You can customize the icons used in the permission approval workflow: ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { permission_icons = { allow_once = "", -- Allow this execution only allow_always = "", -- Allow all future executions reject_once = "", -- Reject this execution only reject_always = "󰜺", -- Reject all future executions }, }, } ``` ### Customizing Chat Icons You can customize the icons used to identify user and agent messages in the chat: ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { chat_icons = { user = " ", -- Icon shown for user messages agent = "󱚠 ", -- Icon shown for agent/AI messages }, }, } ``` ### Customizing Message Icons You can customize the icons used for messages and interaction states: ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { message_icons = { thinking = "🧠", -- Shown when the agent is thinking/reasoning finished = "🏁", -- Shown when the interaction completes successfully stopped = "🛑", -- Shown when the user cancels the generation error = "❌", -- Shown when the interaction ends with an error }, }, } ``` ## Integration with other Plugins ### Prompt suggestions with Copilot To get Copilot suggestions while you are typing your prompt, you need to tell Copilot to attach to the `AgenticInput` filetype. #### copilot.vim ```lua { "github/copilot.vim", -- .... init = function() vim.g.copilot_filetypes = { AgenticInput = true, } end, } ``` #### copilot.lua ```lua { "zbirenbaum/copilot.lua", -- .... opts = { -- Override should_attach to allow copilot in AgenticInput buffers -- AgenticInput uses buftype = "nofile" which copilot.lua rejects by default should_attach = function(bufnr, bufname) local filetype = vim.bo[bufnr].filetype if filetype == "AgenticInput" then return true end -- Delegate to default behavior for all other buffers local default_should_attach = require("copilot.config.should_attach").default return default_should_attach(bufnr, bufname) end, }, } ``` ### Lualine If you're using [lualine.nvim](https://github.com/nvim-lualine/lualine.nvim) or similar statusline plugins, configure it to ignore Agentic windows to prevent conflicts with custom window decorations: ```lua require('lualine').setup({ options = { disabled_filetypes = { statusline = { 'AgenticChat', 'AgenticInput', 'AgenticCode', 'AgenticFiles', 'AgenticDiagnostics' }, winbar = { 'AgenticChat', 'AgenticInput', 'AgenticCode', 'AgenticFiles', 'AgenticDiagnostics' }, } } }) ``` This ensures that Agentic's custom window titles and statuslines render correctly without interference from your statusline plugin. ### Markdown render plugins Only the `AgenticChat` buffer is properly set as `markdown` and starts Treesitter parser, you only need to mention it in your markdown render plugin setup. ```lua { "MeanderingProgrammer/render-markdown.nvim", -- ... opts = { file_types = { "markdown", "md", "AgenticChat" }, } } ``` ### Blink.cmp You can disable `blink.cmp` from attaching to Agentic prompt buffers by adding the following to your `blink.cmp` setup: ```lua require('blink.cmp').setup({ enabled = function() return not vim.tbl_contains({"AgenticInput"}, vim.bo.filetype) end, }) ``` Alternatively, you can disable Agentic's built-in autocomplete and let `blink.cmp` handle slash command and file picker completions in the prompt buffer: ```lua { "carlos-algms/agentic.nvim", opts = { slash_commands = { auto_trigger = false, }, file_picker = { auto_trigger = false, }, }, } ``` ```lua { 'saghen/blink.cmp', version = '1.*', opts = { -- ... completion = { menu = { draw = { components = { -- Increase the label description width to show more of the slash -- command descriptions label_description = { width = { max = 100 }, }, }, }, }, }, sources = { per_filetype = { -- You can also enable copilot here if you want copilot suggestions in the Prompt buffer AgenticInput = { 'agentic_slash', 'agentic_at' }, }, providers = { agentic_slash = { module = 'blink.cmp.sources.complete_func', name = 'AgenticSlash', -- Detect / at the start of the prompt input to trigger slash command completions enabled = function() local cursor = vim.api.nvim_win_get_cursor(0) if cursor[1] ~= 1 then return false end local before = vim.api.nvim_get_current_line():sub(1, cursor[2]) return before:match('^/[^%s]*$') ~= nil end, opts = { complete_func = function() return "v:lua.require'agentic.acp.slash_commands'.complete_func" end }, -- Fix output by removing / added in label details transform_items = function(_, items) for _, item in ipairs(items) do if item.labelDetails then item.labelDetails.detail = nil end end return items end, }, agentic_at = { module = 'blink.cmp.sources.complete_func', -- Detect @ is before the cursor to trigger file picker completions name = 'AgenticAt', enabled = function() local col = vim.api.nvim_win_get_cursor(0)[2] local before = vim.api.nvim_get_current_line():sub(1, col) return (before:match('^@[^%s]*$') or before:match('[%s]@[^%s]*$')) ~= nil end, opts = { complete_func = function() return "v:lua.require'agentic.ui.file_picker'.complete_func" end }, -- Fix output by removing @ added in label details transform_items = function(_, items) for _, item in ipairs(items) do if item.labelDetails then item.labelDetails.detail = nil end end return items end, }, }, }, }, } ``` ### nvim-cmp You can disable `nvim-cmp` from attaching to Agentic prompt buffers by using filetype-specific setup or the `enabled` option: ```lua -- Option 1: Filetype-specific setup (disable all sources) require('cmp').setup.filetype('AgenticInput', { sources = {} }) -- Option 2: Global enabled function require('cmp').setup({ enabled = function() return not vim.tbl_contains({"AgenticInput"}, vim.bo.filetype) end, }) ``` ## ❤️ Sponsor If agentic.nvim makes your day better, consider sponsoring development. Pick whichever channel you prefer - all of them help equally. [![GitHub Sponsors](https://img.shields.io/github/sponsors/carlos-algms?style=for-the-badge&logo=githubsponsors&logoColor=white&label=GitHub%20Sponsors&color=ea4aaa)](https://github.com/sponsors/carlos-algms) [![Patreon](https://img.shields.io/badge/Patreon-Support-F96854?style=for-the-badge&logo=patreon&logoColor=white)](https://www.patreon.com/cw/CarlosAlgms) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Tip-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/carlos.algms) [![Corporate Sponsor](https://img.shields.io/badge/Corporate-Sponsor-2A6FDB?style=for-the-badge&logo=github&logoColor=white)](#-for-companies) ### 🏢 For companies Does your company have the budget to sponsor open source? Sponsoring agentic.nvim gets your team: - Logo placement in this README - Direct line to the maintainer - Priority consideration on issues affecting your workflow Reach out via [GitHub Sponsors](https://github.com/sponsors/carlos-algms) or [open an issue](https://github.com/carlos-algms/agentic.nvim/issues/new) to discuss custom terms. ## 🔧 Development ### Health Check Verify your installation and dependencies: ```vim :checkhealth agentic ``` This will check: - Neovim version (≥ 0.11.0 required) - Current ACP provider installation (We don't install them for security reasons) - Optional ACP providers (so you know which ones are available and can use at any time) - Clipboard image paste tooling (`powershell.exe`, `wslpath`, `wl-paste`, or `xclip`) - Node.js and package managers (Most of the ACP CLIs require Node.js to install and run, some have native binaries too, we don't have control over that, it up to the Creators) ### Debug Mode Enable debug logging to troubleshoot issues: ```lua { "carlos-algms/agentic.nvim", --- @type agentic.PartialUserConfig opts = { debug = true, -- ... rest of your options } } ``` View debug logs with `:messages` (lost after restarting Neovim) View messages exchanged with the ACP provider in the log file at: (persistent until you delete it) - `~/.cache/nvim/agentic_debug.log` ## 📚 Resources - [Agent Client Protocol Documentation](https://agentclientprotocol.com) ## 📄 License [MIT License](LICENSE.txt) Feel free to copy, modify, and distribute, just be a good samaritan and include the the acknowledgments 😊. ## 🙏 Acknowledgments - Built on top of the [Agent Client Protocol](https://agentclientprotocol.com) specification - [CopilotChat.nvim](https://github.com/CopilotC-Nvim/CopilotChat.nvim) - for being my entrance point of chatting with AI in Neovim - [codecompanion.nvim](https://github.com/olimorris/codecompanion.nvim) - for the buffer writing inspiration - [avante.nvim](https://github.com/yetone/avante.nvim) - for the ACP client code and sidebar structured with multiple panels [claude-agent-acp]: https://github.com/agentclientprotocol/claude-agent-acp [claude-agent-acp-releases]: https://github.com/agentclientprotocol/claude-agent-acp/releases [gemini-cli]: https://github.com/gemini-cli/gemini-cli [codex-acp]: https://github.com/zed-industries/codex-acp [codex-acp-releases]: https://github.com/zed-industries/codex-acp/releases [opencode]: https://github.com/sst/opencode [cursor-agent-docs]: https://cursor.com/docs/cli/installation [auggie]: https://www.npmjs.com/package/@augmentcode/auggie [auggie-docs]: https://docs.augmentcode.com/cli/setup-auggie [mistral-vibe]: https://github.com/mistralai/mistral-vibe [mistral-vibe-releases]: https://github.com/mistralai/mistral-vibe/releases [preview-diff-side-by-side-image]: https://github.com/user-attachments/assets/aef778af-815c-412b-a514-e3dec4280b6d [preview-diff-inline-image]: https://github.com/user-attachments/assets/6f824ec9-023b-4cc4-aca6-647a6b191183 [copilot-cli]: https://github.com/github/copilot-cli [cline]: https://github.com/cline/cline [cline-docs]: https://docs.cline.bot/getting-started/installing-cline [goose]: https://github.com/block/goose [goose-docs]: https://block.github.io/goose/docs/getting-started/installation [kiro-docs]: https://kiro.dev/docs/cli/ [pi-acp]: https://github.com/svkozak/pi-acp [pi-docs]: https://pi.dev/docs/latest