Skip to content

Add customizable keymap for window_navigation and scrolling #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+81 −27
Open

Add customizable keymap for window_navigation and scrolling #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
90532ef
Allow customizable window_navigation and scrolling keymaps
TheoBrigitte Sep 30, 2025
b32bd39
address the rabbit reviews 🥕
TheoBrigitte Sep 30, 2025
b7d9971
fix typo
TheoBrigitte Sep 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
},
}
})
```
Expand Down
60 changes: 52 additions & 8 deletions lua/claude-code/config.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines +45 to +48
Copy link

@coderabbitai coderabbitai bot Sep 30, 2025

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Documentation is incomplete for window_navigation and scrolling fields.

The documentation only mentions the enabled field but omits the actual key binding fields. Users need to know about left, down, up, right for window_navigation and page_down, page_up for scrolling.

Apply this diff to complete the documentation:

 -- @field window_navigation table|nil Window navigation keymaps
 -- @field window_navigation.enabled boolean Enable window navigation keymaps
+-- @field window_navigation.left string Keymap to move to left window
+-- @field window_navigation.down string Keymap to move to down window
+-- @field window_navigation.up string Keymap to move to up window
+-- @field window_navigation.right string Keymap to move to right window
 -- @field scrolling table|nil Scrolling keymaps
 -- @field scrolling.enabled boolean Enable scrolling keymaps
+-- @field scrolling.page_down string Keymap to scroll down one page
+-- @field scrolling.page_up string Keymap to scroll up one page
🤖 Prompt for AI Agents 
In lua/claude-code/config.lua around lines 45 to 48, the docblock for
window_navigation and scrolling only documents the enabled boolean; update the
documentation to list the actual key binding fields: for window_navigation add
@field window_navigation.left string|nil, @field window_navigation.down
string|nil, @field window_navigation.up string|nil and @field
window_navigation.right string|nil; for scrolling add @field scrolling.page_down
string|nil and @field scrolling.page_up string|nil. Keep the existing enabled
fields and ensure the types and brief descriptions mirror the style of the
surrounding docs (e.g., indicate they are keymap strings and optional).


--- ClaudeCodeCommandVariants class for command variant configuration
-- @table ClaudeCodeCommandVariants
Expand Down Expand Up @@ -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
},
},
}

Expand Down Expand Up @@ -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 boolean'
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 table'
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
Expand Down
24 changes: 12 additions & 12 deletions lua/claude-code/keymaps.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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' }
)
Expand All @@ -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.scrolling.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.scrolling.page_up,
[[<C-\><C-n><C-b>i]],
{ noremap = true, silent = true, desc = 'Scroll full page up' }
)
Expand Down
10 changes: 5 additions & 5 deletions tests/spec/config_validation_spec.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down