Skip to content

feat: Normal buffer keymaps#151

Open
dmtrKovalenko wants to merge 7 commits intonickjvandyke:mainfrom
dmtrKovalenko:main
Open

feat: Normal buffer keymaps#151
dmtrKovalenko wants to merge 7 commits intonickjvandyke:mainfrom
dmtrKovalenko:main

Conversation

@dmtrKovalenko
Copy link

@dmtrKovalenko dmtrKovalenko commented Jan 28, 2026

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 AI review requested due to automatic review settings January 28, 2026 19:00
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines 133 to 134
["<C-u>"] = { "session.half.page.up", desc = "Scroll up half page" },
["<C-d>"] = { "session.half.page.down", desc = "Scroll down half page" },
Copy link

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copilot uses AI. Check for mistakes.
README.md Outdated
| Keymap | Command | Description |
| ------- | ------------------------ | -------------------- |
| `<C-u>` | `session.half.page.up` | Scroll up half page |
| `<C-d>` | `session.half.page.down` | Scroll down half page|
Copy link

Copilot AI Jan 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 |

Copilot uses AI. Check for mistakes.
@dmtrKovalenko dmtrKovalenko force-pushed the main branch 4 times, most recently from 6b34967 to e8ae2b9 Compare January 28, 2026 19:20
@nickjvandyke
Copy link
Owner

nickjvandyke commented Jan 28, 2026

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
Copy link
Author

dmtrKovalenko commented Jan 28, 2026

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
Copy link
Owner

nickjvandyke commented Jan 28, 2026

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
Copy link
Author

dmtrKovalenko commented Jan 28, 2026

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
Copy link
Author

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
Copy link
Owner

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?

@dmtrKovalenko
Copy link
Author

you broke the original behavior

@nickjvandyke
Copy link
Owner

Sorry could you clarify? It's working for me as discussed above. But I could be misaligned on that. None of my changes were meant to change functionality.

@nickjvandyke
Copy link
Owner

nickjvandyke commented Feb 5, 2026

Ah you're right, looks like setting the filetype on the built-in terminal doesn't trigger the autocmd. My bad! I must have forgot to test that one. Will look into it.

@dmtrKovalenko
Copy link
Author

dmtrKovalenko commented Feb 5, 2026

Now you broke all of my keymaps making <C-u> in every buffer to scroll opencode. Please if you want to push into my branch test your changes

shh my changes originally have been at least working

@nickjvandyke
Copy link
Owner

nickjvandyke commented Feb 5, 2026

Sorry about that, I was a bit rushed irl! Should have done it on a different branch. Thanks for fixing 🙏

It's working for me now in both terminal and snacks.terminal. Let me know if I missed anything. Otherwise I think this is good to go!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants