opencode.nvim

# 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**: reads OpenCode's background service registration (`service.json`) from its state directory (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

```bash
# 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 .
```

## CI

- **`.github/workflows/lua-ls.yml`**: type-check on push/PR to main
- **`.github/workflows/stylua.yml`**: format check on push/PR to main
- **`.github/workflows/release-please.yml`**: automated releases via release-please (non-fork, main branch only)

## Testing

- No test framework — no tests directory, no test runner config
- Manual verification: `:checkhealth opencode`

## Formatting (StyLua)

- `column_width = 120`, `indent_width = 2`, spaces, double quotes, no call parentheses
- File: `.stylua.toml`

## Type-checking (LuaLS)

- Config: `.luarc.ci.json`
- Runtime: `LuaJIT`
- Library paths: `/opt/nvim/share/nvim/runtime/lua`, cloned `snacks.nvim` and `blink.cmp`

## Architecture notes

- **Async**: custom Promise implementation in `lua/opencode/promise/init.lua` (fork of `promise.nvim`)
- **Server discovery flow** (`lua/opencode/server/discovery/init.lua`): connected server → configured URL → OpenCode background service registration (`service.json`, URL + password) → auto-start + poll (5s timeout)
- **OpenCode v2 API** (`lua/opencode/server/init.lua`): the HTTP API lives under `/api/*` and requires HTTP basic auth. The password comes from the service registration or `opts.server.password`. Requests carry `x-opencode-directory: <nvim cwd>`; the daemon is shared across projects, so `/api/session` is scoped with a `directory` query. Prompts and commands target the most recently updated root session for Neovim's directory (`Server:resolve_session()`), resolved per call and never cached. OpenCode v2 has no TUI-driving or prompt-append API.
- **Discovery vs connection**: server.connect (default true) controls whether the discovered server is automatically subscribed to via SSE. When false, the server is found but not connected.
- **Context system** (`lua/opencode/context/init.lua`): captures buffer/win/cursor/selection before UI opens, renders placeholders (`@this`, `@buffer`, etc.) in prompts
- **Events**: SSE subscribed on `connect()` (`/api/event`), dispatched as `OpencodeEvent:<type>` User autocmds. OpenCode v2 events are shaped `{ id, type, data }`.
- **Edit review**: opens diff in new tab via `:diffpatch`, keymaps `da`/`dr` to accept/reject, `dp`/`do` for per-hunk
- **Ask completion**: in-process LSP server (`lua/opencode/ui/ask/cmp.lua`) providing context placeholder + agent completions
- **Integration policy**: code that bridges another tool _to_ opencode.nvim (e.g. picker send, terminal toggle) belongs in README examples. Code that enhances opencode.nvim's own UI (ask/select with snacks input/picker) stays in the plugin.
- **Operator**: `operator()` sets `operatorfunc`, uses `g@` for range + dot-repeat support

## Project vision

See [CONTRIBUTING.md](./CONTRIBUTING.md) for project guidelines, priorities, and maintenance philosophy. When in doubt, follow the patterns already in the codebase.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• nickjvandyke/opencode.nvim3.9k