Seamlessly integrate the opencode AI assistant with Neovim — convenient and editor-aware research, reviews, and requests.
demo.mp4
Uses
opencode's currently undocumented API — latest tested opencode version:v0.5.18
- Open
opencodein an embedded terminal, or auto-connect to one matching Neovim's CWD. - Input prompts with completions, highlights, and normal-mode support.
- Select from a built-in prompt library and define custom prompts.
- Inject relevant editor context (buffer, selection, cursor, diagnostics, etc.).
- Auto-reload buffers edited by
opencodein real-time. - Forward
opencode's Server-Sent-Events as Neovim autocmds for automation. - Sensible defaults with well-documented, granular configuration.
{
'NickvanDyke/opencode.nvim',
dependencies = {
-- Recommended for better prompt input, and required to use opencode.nvim's embedded terminal — otherwise optional
{ 'folke/snacks.nvim', opts = { input = { enabled = true } } },
},
---@type opencode.Opts
opts = {
-- Your configuration, if any — see lua/opencode/config.lua
},
keys = {
-- Recommended keymaps
{ '<leader>oA', function() require('opencode').ask() end, desc = 'Ask opencode', },
{ '<leader>oa', function() require('opencode').ask('@cursor: ') end, desc = 'Ask opencode about this', mode = 'n', },
{ '<leader>oa', function() require('opencode').ask('@selection: ') end, desc = 'Ask opencode about selection', mode = 'v', },
{ '<leader>ot', function() require('opencode').toggle() end, desc = 'Toggle embedded opencode', },
{ '<leader>on', function() require('opencode').command('session_new') end, desc = 'New session', },
{ '<leader>oy', function() require('opencode').command('messages_copy') end, desc = 'Copy last message', },
{ '<S-C-u>', function() require('opencode').command('messages_half_page_up') end, desc = 'Scroll messages up', },
{ '<S-C-d>', function() require('opencode').command('messages_half_page_down') end, desc = 'Scroll messages down', },
{ '<leader>op', function() require('opencode').select_prompt() end, desc = 'Select prompt', mode = { 'n', 'v', }, },
-- Example: keymap for custom prompt
{ '<leader>oe', function() require('opencode').prompt("Explain @cursor and its context") end, desc = "Explain code near cursor", },
},
}nixvim
programs.nixvim = { extraPlugins = [ pkgs.vimPlugins.opencode-nvim ]; keymaps = [ { key = "<leader>ot"; action = "<cmd>lua require('opencode').toggle()<CR>"; } { key = "<leader>oa"; action = "<cmd>lua require('opencode').ask()<CR>"; mode = "n"; } { key = "<leader>oa"; action = "<cmd>lua require('opencode').ask('@selection: ')<CR>"; mode = "v"; } { key = "<leader>oe"; action = "<cmd>lua require('opencode').select_prompt()<CR>"; mode = ["n" "v"]; } { key = "<leader>on"; action = "<cmd>lua require('opencode').command('session_new')<CR>"; } ]; };
opencode.nvim strives to provide a rich and reliable default experience, with a well-documented and flexible configuration and API for you to customize and compose according to your preferences.
When your prompt contains placeholders, opencode.nvim replaces them with context before sending:
| Placeholder | Context |
|---|---|
@buffer |
Current buffer |
@buffers |
Open buffers |
@cursor |
Cursor position |
@selection |
Selected text |
@visible |
Visible text |
@diagnostic |
Current line diagnostics |
@diagnostics |
Current buffer diagnostics |
@quickfix |
Quickfix list |
@diff |
Git diff |
@grapple |
grapple.nvim tags |
Add custom contexts to opts.contexts.
opencode.nvim forwards opencode's Server-Sent-Events as an OpencodeEvent autocmd:
-- Listen for opencode events vim.api.nvim_create_autocmd("User", { pattern = "OpencodeEvent", callback = function(args) -- See the available event types and their properties vim.notify(vim.inspect(args.data), vim.log.levels.DEBUG) -- Do something interesting, like show a notification when opencode finishes responding if args.data.type == "session.idle" then vim.notify("opencode finished responding", vim.log.levels.INFO) end end, })
- Inspired by (and partially based on) nvim-aider and later neopencode.nvim.
opencode.nvimuses opencode's TUI for simplicity — see sudo-tee/opencode.nvim for a Neovim frontend.- mcp-neovim-server may better suit you, but it lacks customization and tool calls are slow and unreliable.