Plugin ideas for OpenCode v2

[nickjvandyke]

Spun out of #322.

Good paraphrased summary by @nikfp of OpenCode v2 and how it affects opencode.nvim:

From V2 onward, the Opencode TUI isn't the target. The server and sessions are what should be targeted. That would effectively mean writing a client that is Neovim native. Which is definitely a lot to build out, test, and maintain. On the other hand, it would allow much tighter integration into Neovim itself.

We already have https://github.com/sudo-tee/opencode.nvim as a Neovim-native client, and it looks to be under active development still. So I'd like to focus on maximizing this plugin's "bridge" philosophy within OpenCode v2's constraints. It minimizes maintenance burden/feature creep and the barrier to entry.

Rather than introduce yet another interaction model, opencode.nvim leverages OpenCode's existing TUI and API via standard Neovim interfaces. You keep your environment, your config, your flow.

My high-level ideas:

1. Develop and include an OpenCode plugin that re-instates the TUI endpoints. Recreate the v1 experience as much as possible, targeting the TUI. Plus maybe new things now that we'd have some OpenCode-influence. Depends on the plugin API. Imo the best solution, if possible.
2. Discover the TUI process, its parent, and then use its parent's send-keys to imitate the /tui/* endpoints. Similar issues as the OG Providers: finnicky, super high-maintenance, doesn't support every workflow. Although this text-only solution would have less surface area than Providers, which managed opencode's entire lifecycle. Restores functionality and reliable targeting.
3. Or, target the server and its sessions directly. Already done on main. See this commit for functionality consequences. Then improve the opencode.nvim prompting experience rather than rely on the TUI. Multi-line input, append to an in-memory prompt, agent selection, filesystem completions, (custom command completions to replace the commands section in select()?), etc. Restores functionality, just in a different way. And maybe even a better way, because I'm sure Neovim users would prefer to write their prompts in Neovim. However this leaves correct-session targeting. Some ideas there are to create new sessions ourselves so we know the ID to then send to. And a session picker that controls which session we send to (as opposed to selecting a session in the TUI like it used to). Display selected session in statusline component for visibility. Probably some other stuff I'm missing.

Open to feedback and other ideas!

Related issues:

• feature: OpenCode v2 support #322
• feature: send prompt in a new session #335

[nikfp]

And maybe even a better way, because I'm sure Neovim users would prefer to write their prompts in Neovim.

To be honest, this is probably my biggest gripe with the Opencode TUI right now. I really miss the VIM motions and operators if I need to edit a prompt midway through writing it.

Develop and include an OpenCode plugin that re-instates the TUI endpoints. Recreate the v1 experience as much as possible, targeting the TUI. Plus maybe new things now that we'd have some OpenCode-influence. Depends on the plugin API. Imo the best solution, if possible.

This appears to be the rub from what I've been gathering. Much of the TUI behavior support was changed or dropped at v2, which creates a lot of friction. To be clear though, at least for my usage pattern, I would still prefer this as I frequently run a Herdr pane with Opencode on one side, and another terminal on the other in which I may or may not be in Neovim. I would rather not be required to be in neovim to get the functionality I want.

My opinion is that idea 2 is going to be more trouble than it's worth, and it looks like you already agree. However I also can't help but wonder if using an Opencode TUI from within a shell in Neovim would help capture the TUI client in an easier way, and similarly if the Neovim shell might help standardize the target in any way and make option 2 more realistic.

[nickjvandyke]

Thanks for your thoughts!

However I also can't help but wonder if using an Opencode TUI from within a shell in Neovim would help capture the TUI client in an easier way, and similarly if the Neovim shell might help standardize the target in any way and make option 2 more realistic

This is actually how opencode.nvim started before I knew about OpenCode's API lol. It's not so bad using just Neovim's terminal buffer (or snacks.terminal, which was my very first go). Buuut

I would rather not be required to be in neovim to get the functionality I want.

This was my issue too. Both personally (I prefer ghostty tabs) and for the community. We tinkerers love our workflows, so I want to integrate, not force. Providers attempted to do both, but exploded in maintenance burden as mentioned.

So seems we agree that 2 (or some variation on "control the tty directly") is a last resort.

Between 1 and 3, hmmm. Both have their own UX upsides. And similar effort levels? Maybe we explore if 1 is even possible. If so, we'd weigh the tradeoffs and collect community sentiment.

Right now I'm leaning towards 3... Robust in-Neovim prompting does sound nice. And I like that we stay fully Neovim/Lua and don't expand our complexity and dependencies into OpenCode's plugin API and JS/TS.

The way I use Neovim and OpenCode has changed since opencode.nvim started too. As AI improves, I find myself prompting more and driving Neovim less (unfortunately, but gotta hit those metrics!). I think 3 benefits that workflow most? And I bet I'm not the only one.

[nikfp]

As AI improves, I find myself prompting more and driving Neovim less (unfortunately, but gotta hit those metrics!).

I've found the workflow changing, and that seems to be common. Not necessarily less neovim, but the way I'm using neovim has changed. I'm finding myself using neogit a lot more and then jumping directly into files for larger diffs, and the Opencode.nvim v1 experience lets me use my treesitter highlights, gitsigns information, lsp jumps, etc. to jump around and see what the LLM gave me, and then quickly inject lines and ranges back into opencode to request edits, get clarifications, etc.

I think 3 benefits that workflow most? And I bet I'm not the only one.

This is true, assuming the "heart" of what you originally provided is preserved. Personally, I don't want just a code window and then an LLM window and they don't talk to each other very well. I want to pass context from one to the other and I would really like familiar vim motions as I write prompts. Option 3 has the potential to provide the best of all of that

I took a good look at the other opencode.nvim, just to be thorough on what's out there. And to be honest it's such a wall of text on the readme that I just hit the back button. There's a difference between "AI helped me write it" and "AI Wrote it" and it appears very much the latter, and I don't think I should need an LLM just to grok the config and options.

So for me, and understanding that I'm one opinion of many, I would like something closer to the opencode tui with your contexts and prompts philosophy. Simple, straightforward, as minimal a config as possible, and somewhat opinionated in the way it operates.

[nickjvandyke]

That review workflow makes sense, and I often do something similar with lazygit. Generally I have wondered how to enhance the increasingly-common agent-first workflow, such as that.

That reminds me: a while ago I tinkered with adding OpenCode-edited files (from edit events) to Neovim's qflist for quick navigation and review. See the quickfix-events branch. But events had only the file, w/o line numbers, so it was kinda useless. We should check if v2 changed that. Similar case for read events iirc.

Thanks for peeking at the other opencode.nvim. Admittedly I have not tried it either, for similar reasons. Tools change quickly these days and reading yet another verbose readme for yet another tool with it's own unique workflow turns me off. Hence my less-is-more, integration-focused philosophy for opencode.nvim.

Glad to hear that it resonates with you! Thank you for sharing your well-written thoughts. Hopefully others chime in too 😁

[nickjvandyke]

Option 1 research (custom OpenCode plugin to re-instate TUI endpoints)

How it'd work

1. Server plugin registers RPC (Rpc.define) with methods such as selectSession and executeCommand. It emits an RPC event for each call.
2. CLI plugin (runs inside the TUI) subscribes to those RPC events. It calls ui.router.navigate or keymap.dispatch.
3. opencode.nvim sends POST /api/rpc/<id>/<method> over HTTP.

So we'd need two plugins - one for the server, one for the CLI/TUI.

What it could do

Likely restore most TUI endpoints, but not prompt append.

Cost

• Two TypeScript packages plus opencode.nvim changes
• A required install step for every user (possibly automatable, but eh)
• New dependency on a relatively immature plugin API

---

Sooo seems like a bad option. Lots of work and maintenance, and still can't give us everything we want. I'll brainstorm on Option 3 next.

[paweldrozd]

Not a solution for the session-targeting problem, but a data point in case it inspires something.

I dropped the plugin for v2 and made Neovim act as the editor the TUI connects to, using the TUI's built-in editor integration (the Claude Code IDE protocol). It is a small Lua module with no dependencies: a loopback WebSocket server on vim.uv (SHA-1 for the handshake via LuaJIT bit), a lock file in ~/.claude/ide/<port>.lock with workspaceFolders and an authToken, and one notification, at_mentioned { filePath, lineStart, lineEnd }, sent from a visual-mode keymap.

What it gives:

• The TUI inserts @path#10-15 at the prompt cursor as a real file attachment, without submitting.
• No session targeting at all. The TUI picks the lock whose workspaceFolders best contains its own directory, so the mention goes to the TUI that is connected, not to "the most recent session".
• It works from a plain Neovim, with no multiplexer or provider logic.

#318 already implements the same protocol (lock file, WebSocket, selection_changed, at_mentioned) with live selection tracking. I did not find anything of it on main.

#10-15 vs :L10-L15

These are not two spellings of the same thing.

• path:L10-L15 is what opencode.nvim v1 (Context.format) and the bridge I used before produce: a plain-text reference. On 2.0.32 a message containing only @btop/btop.conf:L32-L33 was stored with no attachment at all (checked in session_message). The TUI's parseFileLineRange (packages/tui/src/prompt/parse.ts) only recognises #N-M. So the model gets a string and has to open the file and find the lines itself.
• path#10-15 is the TUI's own range syntax. insertFileMention puts the range into the attachment URI (file:///...?start=10&end=15), and the server's readFileAttachment reads start and end and slices the file (.slice(start - 1, end)) before attaching it. The model gets exactly those lines, not the file.

I checked what was actually stored for mentions sent through at_mentioned (decoded attachment data, counted lines):

Mention	URI	Lines attached	File size
btop/btop.conf#3-5	...?start=3&end=5	3	286 lines
btop/btop.conf#28-30	...?start=28&end=30	3	286 lines
btop/btop.conf#46-61	...?start=46&end=61	16	286 lines
ci-netns/ci-netns-setup.sh#11-17	...?start=11&end=17	7	59 lines

The range only comes through at_mentioned. Typed by hand, @file#N-M gave me no range in any of my attempts: either no attachment, or the whole file with #N-M left as plain text after the mention.

Limitations I hit on 2.0.32

1. at_mentioned always produces an @ attachment (the prefix is hardcoded in insertPart), so it cannot append plain text. tui.prompt.append is still handled by the TUI, but nothing can publish it.
2. A one-line range (lineStart == lineEnd) attaches from that line to the end of the file: tui: single-line file mention (lineStart == lineEnd, or "#N") attaches from that line to the end of the file anomalyco/opencode#58033. I send N..N+1 as a workaround.
3. The 20 MB attachment limit is checked on the whole file before the range is applied, so a range does not help with large files.
4. Several TUIs in the same directory all match the same lock. I did not test it, but OPENCODE_EDITOR_SSE_PORT should pin one.

[nickjvandyke]

Thanks for calling attention to this @paweldrozd ! I'll take a closer look soon when I can. Initially I glossed over #318 because it was quite a departure from the plugin's ethos. But now with v2 differences, and shifts in how I (and others) use Neovim in agentic workflows, it could be the right move!

Do you know how much of this is harness agnostic? Wondering how we should set opencode.nvim apart if claudecode.nvim's method already supports (?) OpenCode.