NickvanDyke/opencode.nvimPublic

generated fromellisonleao/nvim-plugin-template

NotificationsYou must be signed in to change notification settings
Fork35
Star1.2k

Integrate the opencode AI assistant with Neovim — streamline editor-aware research, reviews, and requests.

License

MIT license

1.2k stars 35 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 597 Commits
.github		.github
lua		lua
plugin		plugin
.gitignore		.gitignore
.luarc.ci.json		.luarc.ci.json
.stylua.toml		.stylua.toml
LICENSE		LICENSE
README.md		README.md

Repository files navigation

opencode.nvim

Integrate theopencode AI assistant with Neovim — streamline editor-aware research, reviews, and requests.

demo.mp4

✨ Features

Auto-connects toanyopencode running inside Neovim's CWD, or provides an integrated instance.
Input prompts with completions, highlights, and normal-mode support.
Select prompts from a library and define your own.
Inject editor context (buffer, cursor, selection, diagnostics, etc.).
Controlopencode with commands.
Respond toopencode permission requests.
Reloads buffers edited byopencode in real-time.
Monitoropencode's state via statusline component.
Forwardsopencode's Server-Sent-Events as autocmds for automation.
Sensible defaults with well-documented, flexible configuration and API to fit your workflow.
Vim-y — supports ranges and dot-repeat.

📦 Setup

Tip

Run:checkhealth opencode after setup.

lazy.nvim

{"NickvanDyke/opencode.nvim",dependencies= {-- Recommended for `ask()` and `select()`.-- Required for `snacks` provider.---@module'snacks'<- Loads`snacks.nvim`types for configuration intellisense.    {"folke/snacks.nvim",opts= {input= {},picker= {},terminal= {} } },  },config=function()---@typeopencode.Optsvim.g.opencode_opts= {-- Your configuration, if any — see `lua/opencode/config.lua`, or "goto definition".    }-- Required for `opts.events.reload`.vim.o.autoread=true-- Recommended/example keymaps.vim.keymap.set({"n","x"},"<C-a>",function()require("opencode").ask("@this:", {submit=true })end, {desc="Ask opencode"})vim.keymap.set({"n","x"},"<C-x>",function()require("opencode").select()end,                          {desc="Execute opencode action…"})vim.keymap.set({"n","t"},"<C-.>",function()require("opencode").toggle()end,                          {desc="Toggle opencode"})vim.keymap.set({"n","x"},"go",function()returnrequire("opencode").operator("@this")end,        {expr=true,desc="Add range to opencode"})vim.keymap.set("n","goo",function()returnrequire("opencode").operator("@this").."_"end, {expr=true,desc="Add line to opencode"})vim.keymap.set("n","<S-C-u>",function()require("opencode").command("session.half.page.up")end,   {desc="opencode half page up"})vim.keymap.set("n","<S-C-d>",function()require("opencode").command("session.half.page.down")end, {desc="opencode half page down"})-- You may want these if you stick with the opinionated "<C-a>" and "<C-x>" above — otherwise consider "<leader>o".vim.keymap.set("n","+","<C-a>", {desc="Increment",noremap=true })vim.keymap.set("n","-","<C-x>", {desc="Decrement",noremap=true })end,}

nixvim

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

⚙️ Configuration

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

Contexts

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

Placeholder	Context
`@this`	Operator range or visual selection if any, else cursor position
`@buffer`	Current buffer
`@buffers`	Open buffers
`@visible`	Visible text
`@diagnostics`	Current buffer diagnostics
`@quickfix`	Quickfix list
`@diff`	Git diff
`@grapple`	grapple.nvim tags

Prompts

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

Name	Prompt
`diagnostics`	Explain`@diagnostics`
`diff`	Review the following git diff for correctness and readability:`@diff`
`document`	Add comments documenting`@this`
`explain`	Explain`@this` and its context
`fix`	Fix`@diagnostics`
`implement`	Implement`@this`
`optimize`	Optimize`@this` for performance and readability
`review`	Review`@this` for correctness and readability
`test`	Add tests for`@this`

Provider

You can manually runopencode inside Neovim's CWD however you like andopencode.nvim will find it!

Ifopencode.nvim can't find an existingopencode, it uses the configured provider (defaulting based on availability) to manage one for you.

Neovim terminal

vim.g.opencode_opts= {provider= {enabled="terminal",terminal= {-- ...    }  }}

snacks.terminal

vim.g.opencode_opts= {provider= {enabled="snacks",snacks= {-- ...    }  }}

kitty

vim.g.opencode_opts= {provider= {enabled="kitty",kitty= {-- ...    }  }}

The kitty provider requiresremote control via a socket to be enabled.

You can do this either by running Kitty with the following command:

# For Linux only:kitty -o allow_remote_control=yes --single-instance --listen-on unix:@mykitty# Other UNIX systems:kitty -o allow_remote_control=yes --single-instance --listen-on unix:/tmp/mykitty

OR, by adding the following to yourkitty.conf:

# For Linux only:allow_remote_control yeslisten_on unix:@mykitty# Other UNIX systems:allow_remote_control yeslisten_on unix:/tmp/kitty

wezterm

vim.g.opencode_opts= {provider= {enabled="wezterm",wezterm= {-- ...    }  }}

tmux

vim.g.opencode_opts= {provider= {enabled="tmux",tmux= {-- ...    }  }}

custom

Integrate your custom method for convenience!

vim.g.opencode_opts= {provider= {toggle=function(self)-- ...end,start=function(self)-- ...end,stop=function(self)-- ...end,  }}

Please submit PRs adding new providers! 🙂

🚀 Usage

✍️ Ask —`require("opencode").ask()`

Input a prompt foropencode.

Press<Up> to browse recent asks.
Highlights and completes contexts andopencode subagents.
- Press<Tab> to trigger built-in completion.
- Registersopts.ask.blink_cmp_sources when usingsnacks.input andblink.cmp.

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

Select from allopencode.nvim functionality.

Fetches custom commands fromopencode.
Highlights and previews items when usingsnacks.picker.

🗣️ Prompt —`require("opencode").prompt()`

Promptopencode.

Resolves named references to configured prompts.
Injects configured contexts.
opencode will interpret@ references to files or subagents.

🧑‍🔬 Operator —`require("opencode").operator()`

Wrapsprompt as an operator, supporting ranges and dot-repeat.

🧑‍🏫 Command —`require("opencode").command()`

Commandopencode:

Command	Description
`session.list`	List sessions
`session.new`	Start a new session
`session.share`	Share the current session
`session.interrupt`	Interrupt the current session
`session.compact`	Compact the current session (reduce context size)
`session.page.up`	Scroll messages up by one page
`session.page.down`	Scroll messages down by one page
`session.half.page.up`	Scroll messages up by half a page
`session.half.page.down`	Scroll messages down by half a page
`session.first`	Jump to the first message in the session
`session.last`	Jump to the last message in the session
`session.undo`	Undo the last action in the current session
`session.redo`	Redo the last undone action in the current session
`prompt.submit`	Submit the TUI input
`prompt.clear`	Clear the TUI input
`agent.cycle`	Cycle the selected agent

👀 Events

opencode.nvim forwardsopencode's Server-Sent-Events as anOpencodeEvent autocmd:

-- Handle `opencode` eventsvim.api.nvim_create_autocmd("User", {pattern="OpencodeEvent:*",-- Optionally filter event typescallback=function(args)---@typeopencode.cli.client.Eventlocalevent=args.data.event---@typenumberlocalport=args.data.port-- See the available event types and their propertiesvim.notify(vim.inspect(event))-- Do something usefulifevent.type=="session.idle"thenvim.notify("`opencode` finished responding")endend,})

Edits

Whenopencode edits a file,opencode.nvim automatically reloads the corresponding buffer.

Permissions

Whenopencode requests a permission,opencode.nvim waits for idle to ask you to approve or deny it.

Statusline

lualine

require("lualine").setup({sections= {lualine_z= {      {require("opencode").statusline,      },    }  }})

🙏 Acknowledgments

Inspired bynvim-aider,neopencode.nvim, andsidekick.nvim.
Usesopencode's TUI for simplicity — seesudo-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.