Copilot Chat for Neovim

cchat.mp4

CopilotChat.nvim is a Neovim plugin that brings GitHub Copilot Chat capabilities directly into your editor. It provides:

• 🤖 Native GitHub Copilot Chat integration with official model and agent support (GPT-4o, Claude 3.5 Sonnet, Gemini 2.0 Flash, and more)
• 💻 Rich workspace context powered by smart embeddings system
• 🔒 Explicit context sharing - only sends what you specifically request, either as context or selection
• 🔌 Modular provider architecture supporting both official and custom LLM backends (Ollama, LM Studio, and more)
• 📝 Interactive chat UI with completion, diffs and quickfix integration
• 🎯 Powerful prompt system with composable templates and sticky prompts
• 🔄 Extensible context providers for granular workspace understanding (buffers, files, git diffs, URLs, and more)
• ⚡ Efficient token usage with tiktoken optimization

Requirements

• Neovim 0.10.0+ - Older versions are not officially supported
• curl - Version 8.0.0+ recommended for best compatibility
• Copilot chat in the IDE enabled in GitHub settings

Note

For Neovim < 0.11.0, add noinsert and popup to your completeopt for proper chat completion behavior.

Optional Dependencies

• tiktoken_core - For accurate token counting

  • Arch Linux: Install luajit-tiktoken-bin or lua51-tiktoken-bin from AUR
  • Via luarocks: sudo luarocks install --lua-version 5.1 tiktoken_core
  • Manual: Download from lua-tiktoken releases and save as tiktoken_core.so in your Lua path

• git - For git diff context features

  • Arch Linux: Install from official repositories
  • Other systems: Use system package manager or official installer

• lynx - For improved URL context features

  • Arch Linux: Install from official repositories
  • Other systems: Use system package manager or official installer

Installation

lazy.nvim

return {
  {
    "CopilotC-Nvim/CopilotChat.nvim",
    dependencies = {
      { "github/copilot.vim" }, -- or zbirenbaum/copilot.lua
      { "nvim-lua/plenary.nvim", branch = "master" }, -- for curl, log and async functions
    },
    build = "make tiktoken", -- Only on MacOS or Linux
    opts = {
      -- See Configuration section for options
    },
    -- See Commands section for default commands if you want to lazy load on them
  },
}

See @jellydn for configuration

vim-plug

Similar to the lazy setup, you can use the following configuration:

call plug#begin()
Plug 'github/copilot.vim'
Plug 'nvim-lua/plenary.nvim'
Plug 'CopilotC-Nvim/CopilotChat.nvim'
call plug#end()

lua << EOF
require("CopilotChat").setup {
  -- See Configuration section for options
}
EOF

Manual

1. Put the files in the right place

mkdir -p ~/.config/nvim/pack/copilotchat/start
cd ~/.config/nvim/pack/copilotchat/start

git clone https://github.com/github/copilot.vim
git clone https://github.com/nvim-lua/plenary.nvim

git clone https://github.com/CopilotC-Nvim/CopilotChat.nvim

2. Add to your configuration (e.g. ~/.config/nvim/init.lua)

require("CopilotChat").setup {
  -- See Configuration section for options
}

See @deathbeam for configuration

Features

Commands

Commands are used to control the chat interface:

Command	Description
:CopilotChat <input>?	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 <name>?	Save chat history
:CopilotChatLoad <name>?	Load chat history
:CopilotChatModels	View/select available models
:CopilotChatAgents	View/select available agents
:CopilotChat<PromptName>	Use specific prompt template

Key Mappings

Default mappings in the chat interface:

Insert	Normal	Action
<Tab>	<Tab>	Trigger/accept completion menu for tokens
<C-c>	q	Close the chat window
<C-l>	<C-l>	Reset and clear the chat window
<C-s>	<CR>	Submit the current prompt
-	gr	Toggle sticky prompt for line under cursor
<C-y>	<C-y>	Accept nearest diff (best with COPILOT_GENERATE)
-	gj	Jump to section of nearest diff
-	gqa	Add all answers from chat to quickfix list
-	gqd	Add all diffs from chat to quickfix list
-	gy	Yank nearest diff to register
-	gd	Show diff between source and nearest diff
-	gi	Show info about current chat
-	gc	Show current chat context
-	gh	Show help message

The mappings can be customized by setting the mappings table in your configuration. Each mapping can have:

• normal: Key for normal mode
• insert: Key for insert mode
• detail: Description of what the mapping does

For example, to change the submit prompt mapping or show_diff full diff option:

{
    mappings = {
      submit_prompt = {
        normal = '<Leader>s',
        insert = '<C-s>'
      }
      show_diff = {
        full_diff = true
      }
    }
}

Prompts

Predefined Prompts

Predefined prompt templates for common tasks. Reference them with /PromptName in chat or use :CopilotChat<PromptName>:

Prompt	Description
Explain	Write an explanation for the selected code
Review	Review the selected code
Fix	Rewrite the code with bug fixes
Optimize	Optimize code for performance and readability
Docs	Add documentation comments to the code
Tests	Generate tests for the code
Commit	Write commit message using commitizen convention

Define your own prompts in the configuration:

{
  prompts = {
    MyCustomPrompt = {
      prompt = 'Explain how it works.',
      system_prompt = 'You are very good at explaining stuff',
      mapping = '<leader>ccmc',
      description = 'My custom prompt description',
    }
  }
}

System Prompts

System prompts define the AI model's behavior. Reference them with /PROMPT_NAME in chat:

Prompt	Description
COPILOT_INSTRUCTIONS	Base GitHub Copilot instructions
COPILOT_EXPLAIN	Adds coding tutor behavior
COPILOT_REVIEW	Adds code review behavior with diagnostics
COPILOT_GENERATE	Adds code generation behavior and rules

Define your own system prompts in the configuration (similar to prompts):

{
  prompts = {
    Yarrr = {
      system_prompt = 'You are fascinated by pirates, so please respond in pirate speak.',
    }
  }
}

Sticky Prompts

Sticky prompts persist across chat sessions. They're useful for maintaining context or agent selection. They work as follows:

1. Prefix text with > using markdown blockquote syntax
2. The prompt will be copied at the start of every new chat prompt
3. Edit sticky prompts freely while maintaining the > prefix

Examples:

> #files
> List all files in the workspace

> @models Using Mistral-small
> What is 1 + 11

You can also set default sticky prompts in the configuration:

{
  sticky = {
    '@models Using Mistral-small',
    '#files',
  }
}

Models and Agents

Models

You can control which AI model to use in three ways:

1. List available models with :CopilotChatModels
2. Set model in prompt with $model_name
3. Configure default model via model config key

For supported models, see:

• Copilot Chat Models
• GitHub Marketplace Models (experimental, limited usage)

Agents

Agents determine the AI assistant's capabilities. Control agents in three ways:

1. List available agents with :CopilotChatAgents
2. Set agent in prompt with @agent_name
3. Configure default agent via agent config key

The default "noop" agent is none. For more information:

• Extension Agents Documentation
• Available Agents

Contexts

Contexts provide additional information to the chat. Add context using #context_name[:input] syntax:

Context	Input Support	Description
buffer	✓ (number)	Current or specified buffer content
buffers	✓ (type)	All buffers content (listed/all)
file	✓ (path)	Content of specified file
files	✓ (glob)	Workspace files
filenames	✓ (glob)	Workspace file names
git	✓ (ref)	Git diff (unstaged/staged/commit)
url	✓ (url)	Content from URL
register	✓ (name)	Content of vim register
quickfix	-	Quickfix list file contents

Examples:

> #buffer
> #buffer:2
> #files:.lua
> #filenames
> #git:staged
> #url:https://example.com

Define your own contexts in the configuration with input handling and resolution:

{
  contexts = {
    birthday = {
      input = function(callback)
        vim.ui.select({ 'user', 'napoleon' }, {
          prompt = 'Select birthday> ',
        }, callback)
      end,
      resolve = function(input)
        return {
          {
            content = input .. ' birthday info',
            filename = input .. '_birthday',
            filetype = 'text',
          }
        }
      end
    }
  }
}

Selections

Selections determine the source content for chat interactions. Configure them globally or per-prompt.

Available selections are located in local select = require("CopilotChat.select"):

Selection	Description
visual	Current visual selection
buffer	Current buffer content
line	Current line content
unnamed	Unnamed register (last deleted/changed/yanked content)

You can set a default selection in the configuration:

{
  -- Default uses visual selection or falls back to buffer
  selection = function(source)
    return select.visual(source) or select.buffer(source)
  end
}

Providers

Providers are modules that implement integration with different AI providers.

Built-in Providers

• copilot - Default GitHub Copilot provider used for chat and embeddings
• github_models - Provider for GitHub Marketplace models
• copilot_embeddings - Provider for Copilot embeddings, not standalone

Provider Interface

Custom providers can implement these methods:

{
  -- Optional: Disable provider
  disabled?: boolean,

  -- Optional: Embeddings provider name or function
  embed?: string|function,

  -- Optional: Get extra request headers with optional expiration time
  get_headers(?): table<string,string>, number?,

  -- Optional: Get API endpoint URL
  get_url?(opts: CopilotChat.Provider.options): string,

  -- Optional: Prepare request input
  prepare_input?(inputs: table<CopilotChat.Provider.input>, 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<CopilotChat.Provider.model>,

  -- Optional: Get available agents
  get_agents?(headers: table): table<CopilotChat.Provider.agent>,
}

External Providers

For external providers (Ollama, LM Studio), see the external providers wiki page.

Configuration

Default Configuration

Below are all available configuration options with their default values:

{

  -- Shared config starts here (can be passed to functions at runtime and configured via setup function)

  system_prompt = prompts.COPILOT_INSTRUCTIONS.system_prompt, -- System prompt to use (can be specified manually in prompt via /).

  model = 'gpt-4o', -- Default model to use, see ':CopilotChatModels' for available models (can be specified manually in prompt via $).
  agent = 'copilot', -- Default agent to use, see ':CopilotChatAgents' for available agents (can be specified manually in prompt via @).
  context = nil, -- Default context or array of contexts to use (can be specified manually in prompt via #).
  sticky = nil, -- Default sticky prompt or array of sticky prompts to use at start of every new chat.

  temperature = 0.1, -- GPT result temperature
  headless = false, -- Do not write to chat buffer and use history(useful for using callback for custom processing)
  callback = nil, -- Callback to use when ask response is received

  -- default selection
  selection = function(source)
    return select.visual(source) or select.buffer(source)
  end,

  -- default window options
  window = {
    layout = 'vertical', -- 'vertical', 'horizontal', 'float', 'replace'
    width = 0.5, -- fractional width of parent, or absolute width in columns when > 1
    height = 0.5, -- fractional height of parent, or absolute height in rows when > 1
    -- Options below only apply to floating windows
    relative = 'editor', -- 'editor', 'win', 'cursor', 'mouse'
    border = 'single', -- 'none', single', 'double', 'rounded', 'solid', 'shadow'
    row = nil, -- row position of the window, default is centered
    col = nil, -- column position of the window, default is centered
    title = 'Copilot Chat', -- title of chat window
    footer = nil, -- footer of chat window
    zindex = 1, -- determines if window is on top or below other floating windows
  },

  show_help = true, -- Shows help message as virtual lines when waiting for user input
  show_folds = true, -- Shows folds for sections in chat
  highlight_selection = true, -- Highlight selection
  highlight_headers = true, -- Highlight headers in chat, disable if using markdown renderers (like render-markdown.nvim)
  auto_follow_cursor = true, -- Auto-follow cursor in chat
  auto_insert_mode = false, -- Automatically enter insert mode when opening window and on new prompt
  insert_at_end = false, -- Move cursor to end of buffer when inserting text
  clear_chat_on_new_prompt = false, -- Clears chat on every new prompt

  -- Static config starts here (can be configured only via setup function)

  debug = false, -- Enable debug logging (same as 'log_level = 'debug')
  log_level = 'info', -- Log level to use, 'trace', 'debug', 'info', 'warn', 'error', 'fatal'
  proxy = nil, -- [protocol://]host[:port] Use this proxy
  allow_insecure = false, -- Allow insecure server connections

  chat_autocomplete = true, -- Enable chat autocompletion (when disabled, requires manual `mappings.complete` trigger)

  log_path = vim.fn.stdpath('state') .. '/CopilotChat.log', -- Default path to log file
  history_path = vim.fn.stdpath('data') .. '/copilotchat_history', -- Default path to stored history

  question_header = '# User ', -- Header to use for user questions
  answer_header = '# Copilot ', -- Header to use for AI answers
  error_header = '# Error ', -- Header to use for errors
  separator = '───', -- Separator to use in chat

  -- default providers
  -- see config/providers.lua for implementation
  providers = {
    copilot = {
    },
    github_models = {
    },
    copilot_embeddings = {
    },
  }

  -- default contexts
  -- see config/contexts.lua for implementation
  contexts = {
    buffer = {
    },
    buffers = {
    },
    file = {
    },
    files = {
    },
    git = {
    },
    url = {
    },
    register = {
    },
    quickfix = {
    },
  },

  -- default prompts
  -- see config/prompts.lua for implementation
  prompts = {
    Explain = {
      prompt = '> /COPILOT_EXPLAIN\n\nWrite an explanation for the selected code as paragraphs of text.',
    },
    Review = {
      prompt = '> /COPILOT_REVIEW\n\nReview the selected code.',
    },
    Fix = {
      prompt = '> /COPILOT_GENERATE\n\nThere is a problem in this code. Rewrite the code to show it with the bug fixed.',
    },
    Optimize = {
      prompt = '> /COPILOT_GENERATE\n\nOptimize the selected code to improve performance and readability.',
    },
    Docs = {
      prompt = '> /COPILOT_GENERATE\n\nPlease add documentation comments to the selected code.',
    },
    Tests = {
      prompt = '> /COPILOT_GENERATE\n\nPlease generate tests for my code.',
    },
    Commit = {
      prompt = '> #git:staged\n\nWrite commit message for the change with commitizen convention. Make sure the title has maximum 50 characters and message is wrapped at 72 characters. Wrap the whole message in code block with language gitcommit.',
    },
  },

  -- default mappings
  -- see config/mappings.lua for implementation
  mappings = {
    complete = {
      insert = '<Tab>',
    },
    close = {
      normal = 'q',
      insert = '<C-c>',
    },
    reset = {
      normal = '<C-l>',
      insert = '<C-l>',
    },
    submit_prompt = {
      normal = '<CR>',
      insert = '<C-s>',
    },
    toggle_sticky = {
      detail = 'Makes line under cursor sticky or deletes sticky line.',
      normal = 'gr',
    },
    accept_diff = {
      normal = '<C-y>',
      insert = '<C-y>',
    },
    jump_to_diff = {
      normal = 'gj',
    },
    quickfix_answers = {
      normal = 'gqa',
    },
    quickfix_diffs = {
      normal = 'gqd',
    },
    yank_diff = {
      normal = 'gy',
      register = '"', -- Default register to use for yanking
    },
    show_diff = {
      normal = 'gd',
      full_diff = false, -- Show full diff instead of unified diff when showing diff window
    },
    show_info = {
      normal = 'gi',
    },
    show_context = {
      normal = 'gc',
    },
    show_help = {
      normal = 'gh',
    },
  },
}

Customizing Buffers

Types of copilot buffers:

• copilot-chat - Main chat buffer
• copilot-diff - Diff overlay buffer
• copilot-overlay - Every other overlay buffer (e.g. help, info)

You can set local options for plugin buffers like this:

vim.api.nvim_create_autocmd('BufEnter', {
    pattern = 'copilot-*',
    callback = function()
        -- Set buffer-local options
    end
})

Customizing Highlights

Types of copilot highlights:

• CopilotChatHeader - Header highlight in chat buffer
• CopilotChatSeparator - Separator highlight in chat buffer
• CopilotChatStatus - Status and spinner in chat buffer
• CopilotChatHelp - Help messages in chat buffer (help, references)
• CopilotChatSelection - Selection highlight in source buffer
• CopilotChatKeyword - Keyword highlight in chat buffer (e.g. prompts, contexts)
• CopilotChatInput - Input highlight in chat buffer (for contexts)

API Reference

local chat = require("CopilotChat")

-- Window Management
chat.open()     -- Open chat window
chat.open({     -- Open with custom options
  window = {
    layout = 'float',
    title = 'Custom Chat',
  },
})
chat.close()    -- Close chat window
chat.toggle()   -- Toggle chat window
chat.reset()    -- Reset chat window

-- Chat Interaction
chat.ask("Explain this code.")  -- Basic question
chat.ask("Explain this code.", {
  selection = require("CopilotChat.select").buffer,
  context = { 'buffers', 'files' },
  callback = function(response)
    print("Response:", response)
  end,
})

-- Utilities
chat.prompts()   -- Get all available prompts
chat.response()  -- Get last response
chat.log_level("debug")  -- Set log level


-- Actions
local actions = require("CopilotChat.actions")
actions.pick(actions.prompt_actions({
    selection = require("CopilotChat.select").visual,
}))

-- Update config
chat.setup({
    model = 'gpt-4',
    window = {
        layout = 'float'
    }
})

Examples

For examples, see the examples wiki page.

Development

Setup

To set up the environment:

1. Clone the repository:

git clone https://github.com/CopilotC-Nvim/CopilotChat.nvim
cd CopilotChat.nvim

2. Install development dependencies:

# Install pre-commit hooks
make install-pre-commit

To run tests:

make test

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 for detailed guidelines.

Contributors

Thanks goes to these wonderful people (emoji key):

gptlang 💻 📖	Dung Duc Huynh (Kaka) 💻 📖	Ahmed Haracic 💻	Trí Thiện Nguyễn 💻	He Zhizhou 💻	Guruprakash Rajakkannu 💻	kristofka 💻
PostCyberPunk 📖	Katsuhiko Nishimra 💻	Erno Hopearuoho 💻	Shaun Garwood 💻	neutrinoA4 💻 📖	Jack Muratore 💻	Adriel Velazquez 💻 📖
Tomas Slusny 💻 📖	Nisal 📖	Tobias Gårdhus 📖	Petr Dlouhý 📖	Dylan Madisetti 💻	Aaron Weisberg 💻 📖	Jose Tlacuilo 💻 📖
Kevin Traver 💻 📖	dTry 💻	Arata Furukawa 💻	Ling 💻	Ivan Frolov 💻	Folke Lemaitre 💻 📖	GitMurf 💻
Dmitrii Lipin 💻	jinzhongjia 📖	guill 💻	Sjon-Paul Brown 💻	Renzo Mondragón 💻 📖	fjchen7 💻	Radosław Woźniak 💻
JakubPecenka 💻	thomastthai 📖	Tomáš Janoušek 💻	Toddneal Stallworth 📖	Sergey Alexandrov 💻	Léopold Mebazaa 💻	JunKi Jin 💻
abdennourzahaf 📖	Josiah 💻	Tony Fischer 💻 📖	Kohei Wada 💻	Sebastian Yaghoubi 📖	johncming 💻	Rokas Brazdžionis 💻
Sola 📖 💻

This project follows the all-contributors specification. Contributions of any kind are welcome!

Stargazers