feat: Normal buffer keymaps

Author: dmtrKovalenko

README.md

@@ -48,6 +48,7 @@ Integrate the [opencode](https://github.com/sst/opencode) AI assistant with Neov
     vim.keymap.set({ "n", "x" }, "go",  function() return require("opencode").operator("@this ") end,        { desc = "Add range to opencode", expr = true })
     vim.keymap.set("n",          "goo", function() return require("opencode").operator("@this ") .. "_" end, { desc = "Add line to opencode", expr = true })
 
+    -- The default <C-u>/<C-d> keymaps will work in the normal mode but it is possible to scroll opencode from any buffer:
     vim.keymap.set("n", "<S-C-u>", function() require("opencode").command("session.half.page.up") end,   { desc = "Scroll opencode up" })
     vim.keymap.set("n", "<S-C-d>", function() require("opencode").command("session.half.page.down") end, { desc = "Scroll opencode down" })
 
@@ -79,17 +80,17 @@ programs.nixvim = {
 
 `opencode.nvim` replaces placeholders in prompts with the corresponding context:
 
-| Placeholder    | Context                                                       |
-| -------------- | ------------------------------------------------------------- |
-| `@this`          | Operator range or visual selection if any, else cursor position |
-| `@buffer`        | Current buffer                                              |
-| `@buffers`       | Open buffers                                                |
-| `@visible`       | Visible text                                                |
-| `@diagnostics`   | Current buffer diagnostics                                  |
-| `@quickfix`      | Quickfix list                                               |
-| `@diff`          | Git diff                                                    |
-| `@marks`         | Global marks                                                |
-| `@grapple`       | [grapple.nvim](https://github.com/cbochs/grapple.nvim) tags |
+| Placeholder    | Context                                                         |
+| -------------- | --------------------------------------------------------------- |
+| `@this`        | Operator range or visual selection if any, else cursor position |
+| `@buffer`      | Current buffer                                                  |
+| `@buffers`     | Open buffers                                                    |
+| `@visible`     | Visible text                                                    |
+| `@diagnostics` | Current buffer diagnostics                                      |
+| `@quickfix`    | Quickfix list                                                   |
+| `@diff`        | Git diff                                                        |
+| `@marks`       | Global marks                                                    |
+| `@grapple`     | [grapple.nvim](https://github.com/cbochs/grapple.nvim) tags     |
 
 ### Prompts
 
@@ -107,6 +108,37 @@ Select or reference prompts to review, explain, and improve your code:
 | `review`      | Review `@this` for correctness and readability                         |
 | `test`        | Add tests for `@this`                                                  |
 
+### Keymaps
+
+`opencode.nvim` sets these buffer-local keymaps in opencode terminal buffers by default:
+
+| Keymap  | Command                  | Description                  |
+| ------- | ------------------------ | ---------------------------- |
+| `<C-u>` | `session.half.page.up`   | Scroll up half page          |
+| `<C-d>` | `session.half.page.down` | Scroll down half page        |
+| `<Esc>` | `session.interrupt`      | Interrup (same as esc press) |
+| `gg`    | `session.first`          | Go to first message          |
+| `G`     | `session.last`           | Go to last message           |
+
+You can customize or disable these keymaps:
+
+```lua
+vim.g.opencode_opts = {
+  -- Customize keymaps
+  keymaps = {
+    n = {
+      ["<C-u>"] = { "session.half.page.up", desc = "Scroll up" },
+      ["<C-d>"] = { "session.half.page.down", desc = "Scroll down" },
+      ["gg"] = false, -- Disable this keymap
+      -- Add custom keymaps
+      ["<C-n>"] = { "session.new", desc = "New session" },
+    },
+  },
+  -- Or disable all default keymaps
+  -- keymaps = false,
+}
+```
+
 ### Provider
 
 You can manually run `opencode` inside Neovim's CWD however you like and `opencode.nvim` will find it!

lua/opencode/config.lua

@@ -37,11 +37,23 @@ vim.g.opencode_opts = vim.g.opencode_opts
 ---
 ---Provide an integrated `opencode` when one is not found.
 ---@field provider? opencode.Provider|opencode.provider.Opts
+---
+---Buffer-local keymaps for opencode terminal buffers.
+---Set to `false` to disable all default keymaps.
+---@field keymaps? opencode.keymaps.Opts|false
 
 ---@class opencode.Prompt : opencode.api.prompt.Opts
 ---@field prompt string The prompt to send to `opencode`.
 ---@field ask? boolean Call `ask(prompt)` instead of `prompt(prompt)`. Useful for prompts that expect additional user input.
 
+---Buffer-local keymaps for opencode terminal buffers.
+---@class opencode.keymaps.Opts
+---@field n? table<string, opencode.keymap.Def|false> Normal mode keymaps. Set to `false` to disable a default keymap.
+
+---@class opencode.keymap.Def
+---@field [1] string|fun() The command string or callback function.
+---@field desc? string Description for the keymap.
+
 ---@type opencode.Opts
 local defaults = {
   port = nil,
@@ -116,6 +128,15 @@ local defaults = {
       idle_delay_ms = 1000,
     },
   },
+  keymaps = {
+    n = {
+      ["<C-u>"] = { "session.half.page.up", desc = "Scroll up half page" },
+      ["<C-d>"] = { "session.half.page.down", desc = "Scroll down half page" },
+      ["gg"] = { "session.first", desc = "Go to first message" },
+      ["G"] = { "session.last", desc = "Go to last message" },
+      ["<Esc>"] = { "session.interrupt", desc = "Interrupt current session (esc)" },
+    },
+  },
   provider = {
     cmd = "opencode --port",
     enabled = vim.tbl_filter(

lua/opencode/keymaps.lua

@@ -0,0 +1,36 @@
+local M = {}
+
+---Apply buffer-local keymaps to the given buffer.
+---@param bufnr integer The buffer number to apply keymaps to.
+function M.apply(bufnr)
+  local opts = require("opencode.config").opts.keymaps
+  if opts == false then
+    return
+  end
+
+  local command = require("opencode.api.command").command
+
+  if opts and opts.n then
+    for lhs, def in pairs(opts.n) do
+      if def ~= false then
+        local rhs = def[1]
+        local callback
+        if type(rhs) == "string" then
+          callback = function()
+            command(rhs)
+          end
+        else
+          -- It's a function
+          callback = rhs
+        end
+
+        vim.keymap.set("n", lhs, callback, {
+          buffer = bufnr,
+          desc = def.desc,
+        })
+      end
+    end
+  end
+end
+
+return M

lua/opencode/provider/terminal.lua

@@ -49,6 +49,8 @@ function Terminal:start()
     self.bufnr = vim.api.nvim_create_buf(true, false)
     self.winid = vim.api.nvim_open_win(self.bufnr, true, self.opts)
 
+    require("opencode.keymaps").apply(self.bufnr)
+
     -- Redraw terminal buffer on initial render.
     -- Fixes empty columns on the right side.
     local auid

plugin/keymaps.lua

@@ -0,0 +1,8 @@
+-- Apply buffer-local keymaps to opencode terminal buffers.
+-- This handles the snacks provider (and any other provider using `opencode_terminal` filetype).
+vim.api.nvim_create_autocmd("FileType", {
+  pattern = "opencode_terminal",
+  callback = function(ev)
+    require("opencode.keymaps").apply(ev.buf)
+  end,
+})