opencode.nvim AGENTS.md

opencode.nvim — agent guide

What it is

A Neovim Lua plugin that bridges Neovim and the opencode CLI (external binary). It discovers or starts an opencode server, communicates via REST + SSE, and provides UI for prompting, context injection, session management, and edit review.

Entrypoints

• Public API: lua/opencode.lua — exports ask(), select(), prompt(), command(), operator(), format(), statusline
• Config: vim.g.opencode_opts global (not a setup() call); merged with defaults from lua/opencode/config.lua
• Plugin files: plugin/highlights.lua sets highlight groups; plugin/events/ registers four autocmd groups (OpencodeReload, OpencodeStatus, OpencodePermissions, OpencodeEdits) that listen for OpencodeEvent:* User events to reload edited buffers, update statusline, display permission requests, and diff edit proposals

Config quirks

• Config is passed via vim.g.opencode_opts for simpler UX and faster startup (see lua/opencode/config.lua:6)
• snacks.nvim nested opts go under ask.snacks / select.snacks, then get merged into the passed options at usage time (lua/opencode/ui/ask/init.lua, lua/opencode/ui/select.lua)
• vim.o.autoread is automatically set to true when events.reload.enabled = true (the default) unless the user has explicitly configured it
• Neovim doesn't support mixed integer/string keys in vim.g, which affects some snacks.input options; workaround: modify require("opencode.config").opts directly

Dependencies

• Required: opencode CLI, curl
• Auto-discovery: pgrep + lsof (Unix, unless server.url is set)
• Optional: snacks.nvim (enhances ask() with snacks.input, select() with snacks.picker), blink.cmp (completion plugin with LSP source)
• No hard Lua dependencies beyond Neovim itself

Verification commands

# Type-check (requires neovim + lua-language-server + cloned snacks/blink)
lua-language-server --configpath .luarc.ci.json --check=.

# Format check
stylua --check .

# Format in place
stylua .