Allow customizable window_navigation and scrolling keymaps

Author: TheoBrigitte

README.md

@@ -146,8 +146,18 @@ require("claude-code").setup({
         verbose = "<leader>cV",  -- Normal mode keymap for Claude Code with verbose flag
       },
     },
-    window_navigation = true, -- Enable window navigation keymaps (<C-h/j/k/l>)
-    scrolling = true,         -- Enable scrolling keymaps (<C-f/b>) for page up/down
+    window_navigation = {
+      enabled = true,  -- Enable window navigation keymaps
+      left = '<C-h>',  -- Move to left window
+      down = '<C-j>',  -- Move to down window
+      up = '<C-k>',    -- Move to up window
+      right = '<C-l>', -- Move to right window
+    },
+    scrolling = {
+      enabled = true, -- Enable scrolling keymaps
+      page_down = '<C-f>', -- Scroll down one page
+      page_up = '<C-b>',   -- Scroll up one page
+    },
   }
 })
 ```

lua/claude-code/config.lua

@@ -42,8 +42,10 @@ local M = {}
 --- ClaudeCodeKeymaps class for keymap configuration
 -- @table ClaudeCodeKeymaps
 -- @field toggle ClaudeCodeKeymapsToggle Keymaps for toggling Claude Code
--- @field window_navigation boolean Enable window navigation keymaps
--- @field scrolling boolean Enable scrolling keymaps
+-- @field window_navigation table|nil Window navigation keymaps
+-- @field window_navigation.enabled boolean Enable window navigation keymaps
+-- @field scrolling table|nil Scrolling keymaps
+-- @field scrolling.enabled boolean Enable scrolling keymaps
 
 --- ClaudeCodeCommandVariants class for command variant configuration
 -- @table ClaudeCodeCommandVariants
@@ -131,8 +133,18 @@ M.default_config = {
         verbose = '<leader>cV', -- Normal mode keymap for Claude Code with verbose flag
       },
     },
-    window_navigation = true, -- Enable window navigation keymaps (<C-h/j/k/l>)
-    scrolling = true, -- Enable scrolling keymaps (<C-f/b>) for page up/down
+    window_navigation = {
+      enabled = true,  -- Enable window navigation keymaps
+      left = '<C-h>',  -- Move to left window
+      down = '<C-j>',  -- Move to down window
+      up = '<C-k>',    -- Move to up window
+      right = '<C-l>', -- Move to right window
+    },
+    scrolling = {
+      enabled = true, -- Enable scrolling keymaps
+      page_down = '<C-f>', -- Scroll down one page
+      page_up = '<C-b>',   -- Scroll up one page
+    },
   },
 }
 
@@ -351,12 +363,44 @@ local function validate_keymaps_config(keymaps)
     end
   end
 
-  if type(keymaps.window_navigation) ~= 'boolean' then
-    return false, 'keymaps.window_navigation must be a boolean'
+  if type(keymaps.window_navigation) ~= 'table' then
+    return false, 'keymaps.window_navigation must be a table'
+  end
+
+  if type(keymaps.window_navigation.enabled) ~= 'boolean' then
+    return false, 'keymaps.window_navigation.enabled must be a table'
+  end
+
+  if type(keymaps.window_navigation.left) ~= 'string' then
+    return false, 'keymaps.window_navigation.left must be a string'
+  end
+
+  if type(keymaps.window_navigation.down) ~= 'string' then
+    return false, 'keymaps.window_navigation.down must be a string'
+  end
+
+  if type(keymaps.window_navigation.up) ~= 'string' then
+    return false, 'keymaps.window_navigation.up must be a string'
+  end
+
+  if type(keymaps.window_navigation.right) ~= 'string' then
+    return false, 'keymaps.window_navigation.right must be a string'
+  end
+
+  if type(keymaps.scrolling) ~= 'table' then
+    return false, 'keymaps.scrolling must be a btable'
+  end
+
+  if type(keymaps.scrolling.enabled) ~= 'boolean' then
+    return false, 'keymaps.scrolling.enabled must be a boolean'
+  end
+
+  if type(keymaps.scrolling.page_down) ~= 'string' then
+    return false, 'keymaps.scrolling.page_down must be a string'
   end
 
-  if type(keymaps.scrolling) ~= 'boolean' then
-    return false, 'keymaps.scrolling must be a boolean'
+  if type(keymaps.scrolling.page_up) ~= 'string' then
+    return false, 'keymaps.scrolling.page_up must be a string'
   end
 
   return true, nil

lua/claude-code/keymaps.lua

@@ -109,33 +109,33 @@ function M.setup_terminal_navigation(claude_code, config)
     )
 
     -- Window navigation keymaps
-    if config.keymaps.window_navigation then
+    if config.keymaps.window_navigation.enabled then
       -- Window navigation keymaps with special handling to force insert mode in the target window
       vim.api.nvim_buf_set_keymap(
         buf,
         't',
-        '<C-h>',
+        config.keymaps.window_navigation.left,
         [[<C-\><C-n><C-w>h:lua require("claude-code").force_insert_mode()<CR>]],
         { noremap = true, silent = true, desc = 'Window: move left' }
       )
       vim.api.nvim_buf_set_keymap(
         buf,
         't',
-        '<C-j>',
+        config.keymaps.window_navigation.down,
         [[<C-\><C-n><C-w>j:lua require("claude-code").force_insert_mode()<CR>]],
         { noremap = true, silent = true, desc = 'Window: move down' }
       )
       vim.api.nvim_buf_set_keymap(
         buf,
         't',
-        '<C-k>',
+        config.keymaps.window_navigation.up,
         [[<C-\><C-n><C-w>k:lua require("claude-code").force_insert_mode()<CR>]],
         { noremap = true, silent = true, desc = 'Window: move up' }
       )
       vim.api.nvim_buf_set_keymap(
         buf,
         't',
-        '<C-l>',
+        config.keymaps.window_navigation.right,
         [[<C-\><C-n><C-w>l:lua require("claude-code").force_insert_mode()<CR>]],
         { noremap = true, silent = true, desc = 'Window: move right' }
       )
@@ -144,46 +144,46 @@ function M.setup_terminal_navigation(claude_code, config)
       vim.api.nvim_buf_set_keymap(
         buf,
         'n',
-        '<C-h>',
+        config.keymaps.window_navigation.left,
         [[<C-w>h:lua require("claude-code").force_insert_mode()<CR>]],
         { noremap = true, silent = true, desc = 'Window: move left' }
       )
       vim.api.nvim_buf_set_keymap(
         buf,
         'n',
-        '<C-j>',
+        config.keymaps.window_navigation.down,
         [[<C-w>j:lua require("claude-code").force_insert_mode()<CR>]],
         { noremap = true, silent = true, desc = 'Window: move down' }
       )
       vim.api.nvim_buf_set_keymap(
         buf,
         'n',
-        '<C-k>',
+        config.keymaps.window_navigation.up,
         [[<C-w>k:lua require("claude-code").force_insert_mode()<CR>]],
         { noremap = true, silent = true, desc = 'Window: move up' }
       )
       vim.api.nvim_buf_set_keymap(
         buf,
         'n',
-        '<C-l>',
+       config.keymaps.window_navigation.right,
         [[<C-w>l:lua require("claude-code").force_insert_mode()<CR>]],
         { noremap = true, silent = true, desc = 'Window: move right' }
       )
     end
 
     -- Add scrolling keymaps
-    if config.keymaps.scrolling then
+    if config.keymaps.scrolling.enabled then
       vim.api.nvim_buf_set_keymap(
         buf,
         't',
-        '<C-f>',
+        config.keymaps.window_navigation.page_down,
         [[<C-\><C-n><C-f>i]],
         { noremap = true, silent = true, desc = 'Scroll full page down' }
       )
       vim.api.nvim_buf_set_keymap(
         buf,
         't',
-        '<C-b>',
+        config.keymaps.window_navigation.page_up,
         [[<C-\><C-n><C-b>i]],
         { noremap = true, silent = true, desc = 'Scroll full page up' }
       )

tests/spec/config_validation_spec.lua

@@ -83,7 +83,7 @@ describe('config validation', function()
 
       local result = config.parse_config(invalid_config, true) -- silent mode
       assert.are.equal(config.default_config.window.position, result.window.position)
-      -- Ensure invalid border doesn't bleed through  
+      -- Ensure invalid border doesn't bleed through
       assert.are.not_equal('invalid', result.window.float.border)
       assert.are.equal(config.default_config.window.float.border, result.window.float.border)
     end)
@@ -147,17 +147,17 @@ describe('config validation', function()
       assert.are.equal(config.default_config.keymaps.toggle.normal, result3.keymaps.toggle.normal)
     end)
 
-    it('should validate keymaps.window_navigation must be a boolean', function()
+    it('should validate keymaps.window_navigation.enabled must be a boolean', function()
       -- Simplify this test to match others
       local invalid_config = vim.deepcopy(config.default_config)
-      invalid_config.keymaps.window_navigation = 'enabled' -- String instead of boolean
+      invalid_config.keymaps.window_navigation.enabled = 'enabled' -- String instead of boolean
 
       -- Use silent mode to avoid pollution
       local result = config.parse_config(invalid_config, true)
 
       assert.are.equal(
-        config.default_config.keymaps.window_navigation,
-        result.keymaps.window_navigation
+        config.default_config.keymaps.window_navigation.enabled,
+        result.keymaps.window_navigation.enabled
       )
     end)
   end)