feat: Normal buffer keymaps

[dmtrKovalenko]

Description

The problem I faced with this plugin is very simple: the keymaps are not working.

Readme is suggesting to create global keymaps but this is not how I use neovim, I expect the plugin to correctly behave with buffer-specific keymaps when I am in the normal mode. So when I focus the opencode view I expect the basic keymaps like gg gG and to just work. Which is not how it works rn

This PR adds an ability to provide default keymaps and provides default keymaps in normal mode to match the deafult neovim behavior I am 100% sure every neovim user expects this by default

Screenshots/Videos

This is the behavior now without the configuration at all you can actually scroll opencode without using mouse

Screen.Recording.2026-01-28.at.10.58.36.mov

[Copilot]

Pull request overview

This PR adds default buffer-local keymaps for opencode terminal buffers to enable standard Neovim navigation commands (gg, G, , ) in normal mode. Previously, users had to manually configure global keymaps, but this update provides sensible defaults while maintaining customization options.

Changes:

• Added configurable buffer-local keymap system with default normal mode navigation keymaps
• Updated README to document default keymaps and customization options
• Removed previously suggested global keymap examples from README that are now handled by default

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
lua/opencode/keymaps.lua	New module that applies buffer-local keymaps with support for command strings or callback functions
lua/opencode/config.lua	Added keymap configuration schema and default keymaps for normal mode navigation
lua/opencode/provider/terminal.lua	Integrated keymap application when terminal buffer is created
plugin/keymaps.lua	Added FileType autocmd to apply keymaps for opencode_terminal buffers
README.md	Updated documentation to show default keymaps and removed outdated global keymap examples

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Corrected spelling of 'deafult' to 'default' in the PR description.

[Copilot]

Missing space before the closing pipe character in the table for consistency with other rows.

Suggested change

	| `<C-d>` | `session.half.page.down` | Scroll down half page|
	| `<C-d>` | `session.half.page.down` | Scroll down half page |

[nickjvandyke]

This is a neat idea! 😀

But I'd like to avoid a keymap DSL. And generalize it to work with snacks.terminal (or any other terminal plugins).

Naively, what about a couple more recommended keymaps, but with autocmd and buffer-local? Like:

vim.api.nvim_create_autocmd("FileType", {
  pattern = "opencode_terminal" -- already set on snacks.terminal - would have to set in Terminal provider too
  callback = function()
    vim.keymap.set({ 'n', }, '<C-u>', function() require('opencode').command 'session.half.page.up' end, { desc = 'opencode half page up', buffer = true })
    -- ...
  end
)

I'll admit it's a bit lengthy. Idk if Neovim's API provides a more concise way to set filetype-specific keymaps? We could use ftplugin but that'd require a way to config it unfortunately.

Is it possible to find what the user has already bound to Neovim's scroll functions?? Then we could bind the opencode_terminal versions to those ourselves, with no effort from the user, and guaranteed to match their expected keys.

[dmtrKovalenko]

I disagree I strongly believe that dsl is a way better to set keymaps than callbacks especially given that you already have all the commands as strings. Plugins with a lot of keymaps like https://github.com/dmtrKovalenko/fff.nvim should exclusively use this approach

I'll admit it's a bit lengthy. Idk if Neovim's API provides a more concise way to set filetype-specific keymaps? We could use ftplugin but that'd require a way to config it unfortunately.

The behavior I provided by default I am 100% should be coming by default

Is it possible to find what the user has already bound to Neovim's scroll functions?

Nothing what I know about

[nickjvandyke]

Plugins with a lot of keymaps like dmtrKovalenko/fff.nvim should exclusively use this approach

I guess I'm trying to avoid the level of complexity that warrants a DSL. I want this plugin to be a simple bridge between Neovim and the native opencode TUI first and foremost. I'm wary to make it hyper Neovim-y when e.g. https://github.com/sudo-tee/opencode.nvim or https://github.com/olimorris/codecompanion.nvim do that well already.

Let me think on this some more. I like the functionality you've added. Just considering how it best fits into the rest of the plugin 🙂

I wonder how many Neovim users already customize their opencode keybinds to be Neovim-like 🤔 I think the way their config-ing works, it'd be possible to inject configuration when launched by the plugin. (Similar outcome, but the keymaps would work in terminal mode, not normal mode. And still require a configuration DSL. Just thinking aloud.)

If we did introduce a keymap DSL for this feature, do you think the existing recommended keymaps (and maybe more) should also move to it, for consistency? This is my main reference for avoiding DSLs and default keymaps. But to your credit, it does say "An example for uncontroversial keymaps are buffer-local mappings for specific file types ".

[dmtrKovalenko]

I think it might make sense to not even expose those at the config level because most neovim users would expect this behavior by default, because if they have remapped the for example they will anyway map it like :map <smth> <C-u> which will keep working for this specific usecase unless nnoremap is set

[dmtrKovalenko]

If we did introduce a keymap DSL for this feature, do you think the existing recommended keymaps (and maybe more) should also move to it, for consistency

No because the DSL usually make sense only at a buffer level, for all the global keymaps I would still expect the global keymap. At least this is what I do in fff.nvim https://github.com/dmtrKovalenko/fff.nvim

[nickjvandyke]

I think it might make sense to not even expose those at the config level because most neovim users would expect this behavior by default, because if they have remapped the for example they will anyway map it like :map which will keep working for this specific usecase unless nnoremap is set

Oo that is a great point about the recursive maps working in our favor!

Removing the configuration aspect makes this a much easier merge for me. That's really the only bit I'm concerned with because it adds user-facing complexity.

Does that work for you?

[nickjvandyke]

Could you instead set the opencode_terminal filetype on the buffer? To share logic with snacks.terminal. Unless I'm missing a reason to avoid that.

Maybe also inline opencode/keymaps.lua's content in plugin/keymaps.lua after that too.