opencode.nvim

Bridge Neovim and OpenCode AI to stay in your flow.

https://github.com/user-attachments/assets/e85e021c-fa8f-466e-830c-c667b28f611e

Like what you see? Check out my config.

✨ Features

• Connect to any OpenCode server, or start an integrated instance
• Inject editor context (cursor, selection, buffer, ...)
• Input prompts with completions, highlights, and normal mode
• Select and define re-usable prompts
• Execute commands
• Monitor and respond to events
• Accept/reject and reload edits
• Vim-y — operator and dot-repeat
• Simple and sensible defaults to get you started quickly

📦 Setup

vim.pack (recommended)

vim.pack.add({
  {
    src = "https://github.com/nickjvandyke/opencode.nvim",
    version = vim.version.range("*"), -- Latest stable release
  },
})

---@type opencode.Opts
vim.g.opencode_opts = {
  -- Your configuration, if any; goto definition on the type for details
}

vim.o.autoread = true -- Required for `vim.g.opencode_opts.events.reload`

-- Recommended/example keymaps
vim.keymap.set({ "n", "x" }, "<leader>oa", function() require("opencode").ask("@this: ") end, { desc = "Ask opencode…" })
vim.keymap.set({ "n", "x" }, "<leader>os", function() require("opencode").select() end,       { desc = "Select opencode…" })

vim.keymap.set({ "n", "x" }, "go",  function() return require("opencode").operator("@this ") end,        { desc = "Add range to opencode", expr = true })
vim.keymap.set("n",          "goo", function() return require("opencode").operator("@this ") .. "_" end, { desc = "Add line to opencode", expr = true })

vim.keymap.set("n", "<S-C-u>", function() require("opencode").command("session.half.page.up") end,   { desc = "Scroll opencode up" })
vim.keymap.set("n", "<S-C-d>", function() require("opencode").command("session.half.page.down") end, { desc = "Scroll opencode down" })

{
  "nickjvandyke/opencode.nvim",
  version = "*", -- Latest stable release
  config = function()
    ---@type opencode.Opts
    vim.g.opencode_opts = {
      -- Your configuration, if any; goto definition on the type or field for details
    }

    vim.o.autoread = true -- Required for `vim.g.opencode_opts.events.reload`

    -- Recommended/example keymaps
    vim.keymap.set({ "n", "x" }, "<leader>oa", function() require("opencode").ask("@this: ") end, { desc = "Ask opencode…" })
    vim.keymap.set({ "n", "x" }, "<leader>os", function() require("opencode").select() end,       { desc = "Select opencode…" })

    vim.keymap.set({ "n", "x" }, "go",  function() return require("opencode").operator("@this ") end,        { desc = "Add range to opencode", expr = true })
    vim.keymap.set("n",          "goo", function() return require("opencode").operator("@this ") .. "_" end, { desc = "Add line to opencode", expr = true })

    vim.keymap.set("n", "<S-C-u>", function() require("opencode").command("session.half.page.up") end,   { desc = "Scroll opencode up" })
    vim.keymap.set("n", "<S-C-d>", function() require("opencode").command("session.half.page.down") end, { desc = "Scroll opencode down" })
  end,
}

programs.nixvim = {
  extraPlugins = [
    pkgs.vimPlugins.opencode-nvim
  ];
};

[!TIP] Run :checkhealth opencode after setup.

Integrations

require("snacks").setup({
  input = {
    enabled = true, -- Enhances `ask()`
  },
  picker = {
    enabled = true, -- Enhances `select()`
    actions = {
      ---@param picker snacks.Picker
      opencode_send = function(picker)
        local items = vim.tbl_map(function(item) ---@param item snacks.picker.Item
          return item.file
            and require("opencode").format({ path = item.file, from = item.pos, to = item.end_pos })
            or item.text
        end, picker:selected({ fallback = true }))

        require("opencode").prompt(table.concat(items, ", ") .. " ")
      end,
    },
    win = {
      input = {
        keys = {
          ["<a-a>"] = { "opencode_send", mode = { "n", "i" } },
        },
      },
    },
  },
})

require("lualine").setup({
  sections = {
    lualine_z = {
      {
        -- Shows the currently connected server and its status
        require("opencode").statusline,
      },
    }
  }
})

⚙️ Configuration

opencode.nvim provides a rich and reliable default experience — see all available options and their defaults here.

Contexts

opencode.nvim replaces placeholders in prompts with the corresponding context:

[!TIP] opencode reads referenced files from disk — save your changes!

Prompts

Select prompts to review, explain, and improve your code:

Server

Run local opencodes however you like and opencode.nvim will find them! Or point vim.g.opencode_opts.server.url to a specific server, including remotes.

[!IMPORTANT] You must run opencode with the --port flag to expose its server.

If opencode.nvim can't find an existing opencode, it starts one for you via vim.g.opencode_opts.server.start, defaulting to term://opencode --port.

local opencode_cmd = 'opencode --port'
---@type snacks.terminal.Opts
local snacks_terminal_opts = {
  win = {
    position = 'right',
    enter = false,
  },
}

---@type opencode.Opts
vim.g.opencode_opts = {
  server = {
    start = function()
      require('snacks.terminal').open(opencode_cmd, snacks_terminal_opts)
    end,
  },
}

-- Can also leverage toggle functionality.
-- Avoid <leader> here — Neovim watches for keymaps in terminal mode, so your leader key will have input delay.
vim.keymap.set({ 'n', 't' }, '<C-.>', function()
  require('snacks.terminal').toggle(opencode_cmd, snacks_terminal_opts)
end, { desc = 'Toggle opencode' })

-- Optionally show upon submitting prompt
vim.api.nvim_create_autocmd('User', {
  pattern = { 'OpencodeEvent:tui.command.execute' },
  callback = function(args)
    ---@type opencode.server.Event
    local event = args.data.event
    if event.properties.command == 'prompt.submit' then
      local win = require('snacks.terminal').get(opencode_cmd, { create = false })
      if win then
        win:show()
      end
    end
  end,
})

🚀 Usage

Ask — require("opencode").ask()

Input a prompt for opencode.

• End the prompt with a space to append instead of submit.
• Press <Up> to browse recent asks.
• Highlights and completes contexts and opencode subagents.
  • Press <Tab> to trigger built-in completion.
  • Provided by in-process LSP when using snacks.input.

Select — require("opencode").select()

Select from all opencode.nvim functionality.

• Prompts
• Commands
• Servers

Highlights and previews items when using snacks.picker.

Prompt — require("opencode").prompt()

Prompt opencode.

• End the prompt with a space to append instead of submit.
• Injects configured contexts.
• opencode will interpret references to files or subagents.

Operator — require("opencode").operator()

Wraps prompt as an operator, supporting ranges and dot-repeat.

Command — require("opencode").command()

Command opencode: