# Copilot Chat for Neovim [![Release](https://img.shields.io/github/v/release/CopilotC-Nvim/CopilotChat.nvim?logo=github&style=for-the-badge)](https://github.com/CopilotC-Nvim/CopilotChat.nvim/releases/latest) [![Build](https://img.shields.io/github/actions/workflow/status/CopilotC-Nvim/CopilotChat.nvim/ci.yml?logo=github&style=for-the-badge)](https://github.com/CopilotC-Nvim/CopilotChat.nvim/actions/workflows/ci.yml) [![Documentation](https://img.shields.io/badge/documentation-up-green.svg?logo=vim&style=for-the-badge)](https://copilotc-nvim.github.io/CopilotChat.nvim/) [![Contributors](https://img.shields.io/github/all-contributors/CopilotC-Nvim/CopilotChat.nvim?color=ee8449&logo=github&label=contributors&style=for-the-badge)](#contributors) [![Discord](https://img.shields.io/discord/1200633211236122665?logo=discord&label=discord&style=for-the-badge)](https://discord.gg/vy6hJsTWaZ) [![Dotfyle](https://dotfyle.com/plugins/CopilotC-Nvim/CopilotChat.nvim/shield?style=for-the-badge)](https://dotfyle.com/plugins/CopilotC-Nvim/CopilotChat.nvim) ![image](https://github.com/user-attachments/assets/9ee30811-0fb8-4500-91f6-34ea6b26adea) https://github.com/user-attachments/assets/8cad5643-63b2-4641-a5c4-68bc313f20e6
CopilotChat.nvim brings GitHub Copilot Chat capabilities directly into Neovim with a focus on transparency and user control. - 🤖 **Multiple AI Models** - GitHub Copilot (including GPT-4o, Gemini 2.5 Pro, Claude 4 Sonnet, Claude 3.7 Sonnet, Claude 3.5 Sonnet, o3-mini, o4-mini) + custom providers (Ollama, Mistral.ai). The exact list of available models depends on your [GitHub Copilot settings](https://github.com/settings/copilot/features) and the models provided by GitHub's API. - 🔧 **Tool Calling** - LLM can call workspace functions (file reading, git operations, search) with manual approval or automatic execution for trusted tools - 🔒 **Privacy First** - Only shares what you explicitly request - no background data collection - 📝 **Interactive Chat** - Interactive UI with completion, diffs, and quickfix integration - 🎯 **Smart Prompts** - Composable templates and sticky prompts for consistent context - ⚡ **Token Efficient** - Resource replacement prevents duplicate context, history management via tiktoken counting - 🔗 **Scriptable** - Comprehensive Lua API for automation and headless mode operation - 🔌 **Extensible** - [Custom functions](https://github.com/CopilotC-Nvim/CopilotChat.nvim/discussions/categories/functions) and [providers](https://github.com/CopilotC-Nvim/CopilotChat.nvim/discussions/categories/providers), plus integrations like [mcphub.nvim](https://github.com/ravitemer/mcphub.nvim) # Installation ## Requirements - [Neovim 0.10.0+](https://neovim.io/) - [curl 8.0.0+](https://curl.se/) - [Copilot chat in the IDE](https://github.com/settings/copilot) enabled in GitHub settings - [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) > [!WARNING] > For Neovim < 0.11.0, add `noinsert` or `noselect` to your `completeopt` otherwise chat autocompletion will not work. > For best autocompletion experience, also add `popup` to your `completeopt` (even on Neovim 0.11.0+). ## Optional Dependencies - [tiktoken_core](https://github.com/gptlang/lua-tiktoken) - For accurate token counting - Arch Linux: Install [`luajit-tiktoken-bin`](https://aur.archlinux.org/packages/luajit-tiktoken-bin) or [`lua51-tiktoken-bin`](https://aur.archlinux.org/packages/lua51-tiktoken-bin) from AUR - Via luarocks: `sudo luarocks install --lua-version 5.1 tiktoken_core` - Manual: Download from [lua-tiktoken releases](https://github.com/gptlang/lua-tiktoken/releases) and save as `tiktoken_core.so` in your Lua path - [git](https://git-scm.com/) - For git diff context features - [ripgrep](https://github.com/BurntSushi/ripgrep) - For improved search performance - [lynx](https://lynx.invisible-island.net/) - For improved URL context features ## Integration with pickers For various plugin pickers to work correctly, you need to replace `vim.ui.select` with your desired picker (as the default `vim.ui.select` is very basic). Here are some examples: - [fzf-lua](https://github.com/ibhagwan/fzf-lua?tab=readme-ov-file#neovim-api) - call `require('fzf-lua').register_ui_select()` - [telescope](https://github.com/nvim-telescope/telescope-ui-select.nvim?tab=readme-ov-file#telescope-setup-and-configuration) - setup `telescope-ui-select.nvim` plugin - [snacks.picker](https://github.com/folke/snacks.nvim/blob/main/docs/picker.md#%EF%B8%8F-config) - enable `ui_select` config - [mini.pick](https://github.com/echasnovski/mini.pick/blob/main/lua/mini/pick.lua#L1229) - set `vim.ui.select = require('mini.pick').ui_select` ## [lazy.nvim](https://github.com/folke/lazy.nvim) ```lua return { { "CopilotC-Nvim/CopilotChat.nvim", dependencies = { { "nvim-lua/plenary.nvim", branch = "master" }, }, build = "make tiktoken", opts = { -- See Configuration section for options }, }, } ``` ## [vim-plug](https://github.com/junegunn/vim-plug) ```vim call plug#begin() Plug 'nvim-lua/plenary.nvim' Plug 'CopilotC-Nvim/CopilotChat.nvim' call plug#end() lua << EOF require("CopilotChat").setup() EOF ``` # Core Concepts - **Resources** (`#`) - Add specific content (files, git diffs, URLs) to your prompt - **Tools** (`@`) - Give LLM access to functions it can call during the chat, with manual approval by default - **Sticky Prompts** (`> `) - Persist context across single chat session - **Models** (`$`) - Specify which AI model to use for the chat - **Prompts** (`/PromptName`) - Use predefined prompt templates for common tasks > [!TIP] > Press `` after typing `#` or `@` to see available options and auto-complete. This is the easiest way to discover what's available! # Usage ## Commands | Command | Description | | -------------------------- | ----------------------------- | | `:CopilotChat ?` | Open chat with optional input | | `:CopilotChatOpen` | Open chat window | | `:CopilotChatClose` | Close chat window | | `:CopilotChatToggle` | Toggle chat window | | `:CopilotChatStop` | Stop current output | | `:CopilotChatReset` | Reset chat window | | `:CopilotChatSave ?` | Save chat history | | `:CopilotChatLoad ?` | Load chat history | | `:CopilotChatPrompts` | View/select prompt templates | | `:CopilotChatModels` | View/select available models | | `:CopilotChat` | Use specific prompt template | ## Chat Key Mappings | Insert | Normal | Action | | ------- | ------- | ---------------------------------------------------- | | `` | - | **Autocomplete resources/files/options** (use this!) | | `` | `q` | Close the chat window | | `` | `` | Reset and clear the chat window | | `` | `` | Submit the current prompt | | `` | `` | Accept nearest diff | | - | `gj` | Jump to section of nearest diff | | - | `gqa` | Add all answers from chat to quickfix | | - | `gqd` | Add all diffs from chat to quickfix | | - | `gy` | Yank nearest diff to register | | - | `gd` | Show diff between source and nearest diff | | - | `gc` | Show info about current chat | | - | `gh` | Show help message | **💡 Pro tip:** After typing `#`, `@`, `#buffer:`, or `#file:`, press `` to see available options. This is the fastest way to work! > [!NOTE] > **Tab key not working?** Some plugins (e.g. `copilot.vim`) also map `` in insert mode. > To fix conflicts, disable the other plugin's `` mapping: > > ```lua > -- For copilot.vim > vim.g.copilot_no_tab_map = true > vim.keymap.set('i', '', 'copilot#Accept("\\")', { expr = true, replace_keycodes = false }) > ``` > > Or customize CopilotChat keymaps in your config. ## Predefined Functions All predefined functions belong to the `copilot` group. | Function | Manual `#...` | Description | Available Options | | ----------- | ------------- | ------------------------------------------------------ | --------------------------------------------------------------------- | | `bash` | No | Executes a bash command and returns output | Tool-only (use `@copilot`) | | `buffer` | Yes | Retrieves content from buffer(s) with diagnostics | `active`, `visible`, `listed`, `quickfix`, buffer number, or filename | | `clipboard` | Yes | Provides access to system clipboard content | No options | | `edit` | No | Applies a unified diff to a file | Tool-only (use `@copilot`) | | `file` | Yes | Reads content from a specified file path | Any file path (use `` for completion) | | `gitdiff` | Yes | Retrieves git diff information | `unstaged` (default), `staged`, or commit SHA | | `glob` | Yes | Lists filenames matching a pattern in workspace | Any glob pattern (default: `**/*`) | | `grep` | Yes | Searches for a pattern across files in workspace | Any search pattern | | `selection` | Yes | Includes the current visual selection with diagnostics | No options | | `url` | Yes | Fetches content from a specified URL | Any HTTPS URL | - **`#`** - Embeds output directly in your message (e.g., `#buffer:listed`, `#file:src/main.lua`) - **`@`** - Makes function(s) available for LLM to call when needed (e.g., `@copilot`, `@file`) ## Predefined Prompts | Prompt | Description | | ---------- | ---------------------------------------------------------------------- | | `Explain` | Write detailed explanation of selected code as paragraphs | | `Review` | Comprehensive code review with line-specific issue reporting | | `Fix` | Identify problems and rewrite code with fixes and explanation | | `Optimize` | Improve performance and readability with optimization strategy | | `Docs` | Add documentation comments to selected code | | `Tests` | Generate tests for selected code | | `Commit` | Generate commit message with commitizen convention from staged changes | ## Resource Usage ```markdown # Current buffer #buffer:active # All open buffers (replaces old #buffers) #buffer:listed # All visible buffers #buffer:visible # Specific file #file:src/main.lua # Git changes #gitdiff:staged # URL content #url:https://example.com/docs ``` ## Tool Usage When you use `@copilot`, the LLM can call functions from the `copilot` group such as `bash`, `edit`, `file`, `glob`, `grep`, and `gitdiff`. ```markdown # Give LLM access to workspace tools @copilot What files are in this project? # Sticky context with tools > #buffer:listed > @copilot > Refactor the authentication code ``` By default, tool calls require manual approval. Configure `trusted_tools` to automatically run specific tools (see [Functions](#functions)). > [!WARNING] > `trusted_tools = true` allows the model to run every enabled tool without asking. Only use it if you fully trust the tool set and workspace. # Configuration For all available configuration options, see [`lua/CopilotChat/config.lua`](lua/CopilotChat/config.lua). ## Quick Setup Most users only need to configure a few options: ```lua { model = 'gpt-5-mini', -- AI model to use temperature = 0.1, -- Lower = focused, higher = creative trusted_tools = nil, -- Require approval for all tool calls window = { layout = 'vertical', -- 'vertical', 'horizontal', 'float' width = 0.5, -- 50% of screen width }, auto_insert_mode = true, -- Enter insert mode when opening } ``` ## Window & Appearance ```lua { window = { layout = 'float', width = 80, -- Fixed width in columns height = 20, -- Fixed height in rows border = 'rounded', -- 'single', 'double', 'rounded', 'solid' title = '🤖 AI Assistant', zindex = 100, -- Ensure window stays on top }, headers = { user = '👤 You', assistant = '🤖 Copilot', tool = '🔧 Tool', }, separator = '━━', auto_fold = true, -- Automatically folds non-assistant messages } ``` `window.layout` also supports `'replace'` to reuse the current window. ## Buffer Behavior ```lua -- Auto-command to customize chat buffer behavior vim.api.nvim_create_autocmd('BufEnter', { pattern = 'copilot-chat', callback = function() vim.opt_local.relativenumber = false vim.opt_local.number = false vim.opt_local.conceallevel = 0 end, }) ``` ## Highlights You can customize colors by setting highlight groups in your config: ```lua -- In your colorscheme or init.lua vim.api.nvim_set_hl(0, 'CopilotChatHeader', { fg = '#7C3AED', bold = true }) vim.api.nvim_set_hl(0, 'CopilotChatSeparator', { fg = '#374151' }) ``` Types of copilot highlights: - `CopilotChatHeader` - Header highlight in chat buffer - `CopilotChatSeparator` - Separator highlight in chat buffer - `CopilotChatSelection` - Selection highlight in source buffer - `CopilotChatStatus` - Status and spinner in chat buffer - `CopilotChatHelp` - Help text in chat buffer - `CopilotChatResource` - Resource highlight in chat buffer (e.g. `#file`, `#gitdiff`) - `CopilotChatTool` - Tool call highlight in chat buffer (e.g. `@copilot`) - `CopilotChatPrompt` - Prompt highlight in chat buffer (e.g. `/Explain`, `/Review`) - `CopilotChatModel` - Model highlight in chat buffer (e.g. `$gpt-5-mini`) - `CopilotChatUri` - URI highlight in chat buffer (e.g. `##https://...`) - `CopilotChatAnnotation` - Annotation highlight in chat buffer (file headers, tool call headers, tool call body) - `CopilotChatAnnotationHeader` - Annotation header highlight in chat buffer ## Prompts Define your own prompts in the configuration: ```lua { prompts = { MyCustomPrompt = { prompt = 'Explain how it works.', system_prompt = 'You are very good at explaining stuff', mapping = 'ccmc', description = 'My custom prompt description', }, Yarrr = { system_prompt = 'You are fascinated by pirates, so please respond in pirate speak.', }, NiceInstructions = { system_prompt = 'You are a nice coding tutor, so please respond in a friendly and helpful manner.', } } } ``` ## Functions Use `trusted_tools` to control which tool calls are executed automatically: ```lua { trusted_tools = nil, -- default: require approval for all tool calls -- trust all functions in a group -- trusted_tools = 'copilot', -- trust specific functions by name or groups by name -- trusted_tools = { 'file', 'glob', 'grep' }, -- trust every enabled tool call -- trusted_tools = true, } ``` **How tool trust works:** A tool is trusted when any of these match: - Its function definition sets `trusted = true` - Its function name appears in `trusted_tools` - Its function group appears in `trusted_tools` - `trusted_tools = true` **Recommended setup:** Trust read-only functions like `file`, `glob`, or `grep` for a smoother workflow without compromising safety. > [!WARNING] > Trusted tools run without asking for confirmation. Be especially careful with tools like `bash` and `edit`, which can change your workspace. Define your own functions in the configuration with input handling and schema: ```lua { functions = { birthday = { description = 'Retrieves birthday information for a person', uri = 'birthday://{name}', trusted = false, schema = { type = 'object', required = { 'name' }, properties = { name = { type = 'string', enum = { 'Alice', 'Bob', 'Charlie' }, description = "Person's name", }, }, }, resolve = function(input) return { { uri = 'birthday://' .. input.name, mimetype = 'text/plain', data = input.name .. ' birthday info', }, } end, }, } } ``` If a function has a `uri`, it can be used manually with `#birthday:Alice`. Functions without a `uri` are tool-only and can only be called by the model. ## Providers Add custom AI providers: ```lua { providers = { my_provider = { get_url = function(opts) return 'https://api.example.com/chat' end, get_headers = function() return { ['Authorization'] = 'Bearer ' .. api_key } end, get_models = function() return { { id = 'gpt-5-mini', name = 'GPT-5 mini model' } } end, prepare_input = require('CopilotChat.config.providers').copilot.prepare_input, prepare_output = require('CopilotChat.config.providers').copilot.prepare_output, } } } ``` **Provider Interface:** ```lua { -- Optional: Disable provider disabled?: boolean, -- Optional: Extra info about the provider displayed in info panel get_info?(headers: table): string[] -- Optional: Get extra request headers with optional expiration time get_headers?(): table, number?, -- Optional: Get API endpoint URL get_url?(opts: CopilotChat.Provider.options): string, -- Optional: Prepare request input prepare_input?(inputs: table, opts: CopilotChat.Provider.options): table, -- Optional: Prepare response output prepare_output?(output: table, opts: CopilotChat.Provider.options): CopilotChat.Provider.output, -- Optional: Get available models get_models?(headers: table): table, -- Optional: Resolve a user-facing model id to a provider model id. -- Second return value is optional extra request headers (e.g. Copilot-Session-Token). resolve_model?(headers: table, model: string): string, table?, } ``` **Built-in providers:** - `copilot` - GitHub Copilot (default) - `github_models` - GitHub Models (disabled by default) # API Reference ## Core ```lua local chat = require('CopilotChat') -- Basic Chat Functions chat.ask(prompt, config) -- Ask a question with optional config -- Window Management chat.open(config) -- Open chat window with optional config chat.close() -- Close chat window chat.toggle(config) -- Toggle chat window visibility with optional config chat.reset() -- Reset the chat chat.stop() -- Stop current output -- Prompt & Model Management chat.select_prompt(config) -- Open prompt selector with optional config chat.select_model() -- Open model selector -- History Management chat.load(name, history_path) -- Load chat history chat.save(name, history_path) -- Save chat history -- Configuration chat.setup(config) -- Update configuration chat.log_level(level) -- Set log level (debug, info, etc.) ``` ## Chat Window You can also access the chat window UI methods through the `chat.chat` object: ```lua local window = require('CopilotChat').chat -- Chat UI State window:visible() -- Check if chat window is visible window:focused() -- Check if chat window is focused -- Message Management window:get_message(role, cursor) -- Get chat message by role, either last or closest to cursor window:add_message({ role, content }, replace) -- Add or replace a message in chat window:remove_message(role, cursor) -- Remove chat message by role, either last or closest to cursor window:get_block(role, cursor) -- Get code block by role, either last or closest to cursor -- Content Management window:append(text) -- Append text to chat window window:clear() -- Clear chat window content window:start() -- Start writing to chat window window:finish() -- Finish writing to chat window -- Source Management window:get_source() -- Get the current source buffer and window window:set_source(winnr) -- Set the source window -- Navigation window:follow() -- Move cursor to end of chat content window:focus() -- Focus the chat window -- Advanced Features window:overlay(opts) -- Show overlay with specified options ``` ## Prompt parser ```lua local parser = require('CopilotChat.prompts') parser.resolve_prompt() -- Resolve prompt references parser.resolve_tools() -- Resolve tools shared with the model via @... parser.resolve_functions() -- Resolve manual function/resource references via #... parser.resolve_model() -- Resolve model from prompt (WARN: async, requires plenary.async.run) ``` ## Example Usage ```lua -- Open chat, ask a question and handle response require('CopilotChat').open() require('CopilotChat').ask('#buffer Explain this code', { callback = function(response) vim.notify('Got response: ' .. vim.trim(response.content):sub(1, 50) .. '...') end, }) -- Save and load chat history require('CopilotChat').save('my_debugging_session') require('CopilotChat').load('my_debugging_session') -- Use custom sticky and model require('CopilotChat').ask('How can I optimize this?', { model = 'gpt-5-mini', sticky = { '#buffer', '#gitdiff:staged' }, }) -- Automatically trust a small read-only tool set require('CopilotChat').setup({ trusted_tools = { 'file', 'glob', 'grep' }, }) ``` For more examples, see the [examples wiki page](https://github.com/CopilotC-Nvim/CopilotChat.nvim/wiki/Examples-and-Tips). # Development ## Setup To set up the environment: 1. Clone the repository: ```bash git clone https://github.com/CopilotC-Nvim/CopilotChat.nvim cd CopilotChat.nvim ``` 2. Install development dependencies: ```bash make install-pre-commit ``` To run tests: ```bash make test ``` To run the same formatting check as CI: ```bash stylua --check . ``` ## Contributing 1. Fork the repository 2. Create your feature branch 3. Make your changes 4. Run tests and lint checks 5. Submit a pull request See [CONTRIBUTING.md](/CONTRIBUTING.md) for detailed guidelines. # Contributors Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
gptlang
gptlang

💻 📖
Dung Duc Huynh (Kaka)
Dung Duc Huynh (Kaka)

💻 📖
Ahmed Haracic
Ahmed Haracic

💻
Trí Thiện Nguyễn
Trí Thiện Nguyễn

💻
He Zhizhou
He Zhizhou

💻
Guruprakash Rajakkannu
Guruprakash Rajakkannu

💻
kristofka
kristofka

💻
PostCyberPunk
PostCyberPunk

📖
Katsuhiko Nishimra
Katsuhiko Nishimra

💻
Erno Hopearuoho
Erno Hopearuoho

💻
Shaun Garwood
Shaun Garwood

💻
neutrinoA4
neutrinoA4

💻 📖
Jack Muratore
Jack Muratore

💻
Adriel Velazquez
Adriel Velazquez

💻 📖
Tomas Slusny
Tomas Slusny

💻 📖
Nisal
Nisal

📖
Tobias Gårdhus
Tobias Gårdhus

📖
Petr Dlouhý
Petr Dlouhý

📖
Dylan Madisetti
Dylan Madisetti

💻
Aaron Weisberg
Aaron Weisberg

💻 📖
Jose Tlacuilo
Jose Tlacuilo

💻 📖
Kevin Traver
Kevin Traver

💻 📖
dTry
dTry

💻
Arata Furukawa
Arata Furukawa

💻
Ling
Ling

💻
Ivan Frolov
Ivan Frolov

💻
Folke Lemaitre
Folke Lemaitre

💻 📖
GitMurf
GitMurf

💻
Dmitrii Lipin
Dmitrii Lipin

💻
jinzhongjia
jinzhongjia

📖
guill
guill

💻
Sjon-Paul Brown
Sjon-Paul Brown

💻
Renzo Mondragón
Renzo Mondragón

💻 📖
fjchen7
fjchen7

💻
Radosław Woźniak
Radosław Woźniak

💻
JakubPecenka
JakubPecenka

💻
thomastthai
thomastthai

📖
Tomáš Janoušek
Tomáš Janoušek

💻
Toddneal Stallworth
Toddneal Stallworth

📖
Sergey Alexandrov
Sergey Alexandrov

💻
Léopold Mebazaa
Léopold Mebazaa

💻
JunKi Jin
JunKi Jin

💻
abdennourzahaf
abdennourzahaf

📖
Josiah
Josiah

💻
Tony Fischer
Tony Fischer

💻 📖
Kohei Wada
Kohei Wada

💻
Sebastian Yaghoubi
Sebastian Yaghoubi

📖
johncming
johncming

💻
Rokas Brazdžionis
Rokas Brazdžionis

💻
Sola
Sola

📖 💻
Mani Chandra
Mani Chandra

💻
Nischal Basuti
Nischal Basuti

📖
Teo Ljungberg
Teo Ljungberg

💻
Joe Price
Joe Price

💻
Yufan You
Yufan You

📖 💻
Manish Kumar
Manish Kumar

💻
Anton Ždanov
Anton Ždanov

📖 💻
Fredrik Averpil
Fredrik Averpil

💻
Aaron D Borden
Aaron D Borden

💻
Md. Iftakhar Awal Chowdhury
Md. Iftakhar Awal Chowdhury

💻 📖
Danilo Horta
Danilo Horta

💻
Mihamina Rakotomandimby
Mihamina Rakotomandimby

📖 💻
Ajmal S
Ajmal S

💻
Samiul Islam
Samiul Islam

💻
Rui Costa
Rui Costa

💻
CTCHEN
CTCHEN

💻
Tobias Wölfel
Tobias Wölfel

💻
Alexander Garcia
Alexander Garcia

💻
Max Kharandziuk
Max Kharandziuk

💻
Xinyu Xiang
Xinyu Xiang

💻
junqizhang
junqizhang

💻
Calum Lynch
Calum Lynch

💻
sirjls
sirjls

💻
Vladimir Kolchurin
Vladimir Kolchurin

💻
RoseSecurity
RoseSecurity

📖 💻
Abhraneel Mukherjee
Abhraneel Mukherjee

💻
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome! # Stargazers [![Stargazers over time](https://starchart.cc/CopilotC-Nvim/CopilotChat.nvim.svg?variant=adaptive)](https://starchart.cc/CopilotC-Nvim/CopilotChat.nvim)