Keymaps

The rule: common operations get memorable mappings; uncommon operations get commands and pickers. Every Blak-registered keymap has a description. :BlakKeys shows effective mappings in the current buffer, including described global Neovim/plugin defaults and buffer-local shortcuts. A buffer-local override takes precedence; shadowed mappings are omitted. Inspect global mappings without descriptions with :BlakPick keymaps or :map.

The leader is <Space>. Local leader is \.

All core keymaps are defined in lua/blak/core/keymaps.lua. Extras and user.lua can add more — they show up in :BlakKeys too.

Custom keymaps

Add or override mappings from lua/blak/user.lua with the keymaps list:

return {
  keymaps = {
    { key = "<leader>sg", action = "<cmd>BlakPick grep<cr>", description = "Grep" },
    {
      mode = { "n", "x" },
      key = "<leader>y",
      action = '"+y',
      description = "Yank to clipboard",
    },
    {
      key = "<leader>rn",
      action = function()
        vim.lsp.buf.rename()
      end,
      description = "Rename symbol",
    },
    { key = "<leader>/", disable = true },
  },
}

Active entries require description so they stay discoverable through :BlakKeys. Use mode for one mode or a list of modes, and use a command string or Lua function for action. Use disable = true to disable a Blak mapping. To move a default action, disable the old key and add the new one.

Modes use Neovim’s short names: "n" for Normal, "i" for Insert, and "x" for Visual, for example. "v" covers both Visual and Select mode, so Blak registers it as "x" plus "s"; prefer "x" unless you also want the mapping while typing over a snippet placeholder. Names such as "normal" fail config validation before the current session’s keymaps are refreshed.

Edit & navigation

Mode	Mapping	Action
n	<Esc>	Clear search highlight
n,x	<C-s>	Save
n,i,x,s	<D-s>	Save (where the UI forwards Command-s)
n	<leader>qq	Quit all (:qa)

<C-s> and <D-s> are bound only if your config, a plugin, or Neovim hasn’t already claimed them. In insert and select mode <C-s> stays Neovim’s native LSP signature help, so <C-s> saves only from normal and visual mode. See map_if_available in the source.

Find (pickers)

Mapping	Action
<leader><space>	Find files
<leader>/	Grep
<leader>ff	Find files
<leader>fg	Grep
<leader>fb	Buffers
<leader>fr	Recent files
<leader>fc	Commands
<leader>fk	Keymaps
<leader>fh	Help

All dispatch through the picker provider — see Pickers.

Buffers

Mapping	Action
<leader>`	Toggle last file (native alternate file)
<leader>bd	Delete buffer (via Snacks bufdelete if available)
<leader>bn	Next buffer
<leader>bp	Previous buffer

Windows

Mapping	Action
<leader>ws	Split window below
<leader>wv	Split window right

These use Neovim’s native :rightbelow split and :rightbelow vsplit. Blak only binds them when those keys are still free, so an existing user or plugin mapping wins.

Explorer

Mapping	Action
<leader>e	Configured explorer (Oil by default; Snacks when editor.snacks-explorer is enabled)

Blak leaves Neovim’s native - motion alone.

Terminal

Mapping	Action
<leader>tt	Toggle the configured terminal provider

Change this mapping with terminal.toggle_key in lua/blak/user.lua. Set it to false to leave terminal toggling command-only.

In terminal input mode, press <C-\><C-n> to return to Normal mode, then <leader>tt to hide the terminal. Reopening reuses a running shell; after it exits, reopening starts a fresh shell and keeps the old output buffer.

Git (gitsigns)

Mode	Mapping	Action
n	]h	Next hunk (or ]c inside a diff)
n	[h	Previous hunk (or [c inside a diff)
n	<leader>gs	Stage hunk
x	<leader>gs	Stage selection range
n	<leader>gr	Reset hunk
x	<leader>gr	Reset selection range
n	<leader>gS	Stage buffer
n	<leader>gR	Reset buffer
n	<leader>gp	Preview hunk
n	<leader>gb	Blame line (full)
n	<leader>gd	Diff this

LSP (bound on LspAttach)

These map only when an LSP server attaches to the current buffer.

Mapping	Action
gd	Go to definition
gD	Go to declaration
<leader>ca	Code action
<leader>cr	Rename
<leader>cs	Document symbols (picker)
<leader>cS	Workspace symbols (picker)

Blak does not map K, gr, or gI. Neovim’s own LSP defaults cover them:

Mode	Mapping	Action
n	K	Hover
n	grr	References
n	gri	Go to implementation
n	grn	Rename
n,x	gra	Code action
n	grt	Go to type definition
n	grx	Run code lens
n	gO	Document symbols (location list)
i,s	<C-s>	Signature help

To keep a bare gr for references, add it back in user.lua. It shadows the native gr* prefix, so every gr waits for timeoutlen before it runs:

return {
  keymaps = {
    { key = "gr", action = vim.lsp.buf.references, description = "References" },
  },
}

See the LSP guide.

Formatting

<leader>cf runs :BlakFormat in any buffer, with or without an LSP. To format selected lines, use :'<,'>BlakFormat. Disable the mapping through keymaps = { { key = "<leader>cf", disable = true } } in user.lua.

Native shortcuts

Neovim’s described defaults, such as the LSP maps above, ]d/[d, and the Treesitter selections an/in in visual mode, appear in :BlakKeys alongside Blak’s keys when active. They remain native mappings. See Native Neovim tools for other built-in capabilities that need no extra plugin.

Diagnostics

Mapping	Action
]d / [d	Next / previous diagnostic (native, takes a count)
]D / [D	Last / first diagnostic in the buffer (native)
<leader>xx	Diagnostics picker
<leader>xd	Line diagnostic float

The jumps are Neovim’s own mappings. Blak sets vim.diagnostic.config({ jump = { on_jump = ... } }) so every jump also opens the diagnostic float at the cursor.

Blak & Lazy

Mapping	Action
<leader>ll	:Lazy
<leader>lo	:Blak
<leader>lc	:BlakConfig
<leader>lu	:BlakUpdate
<leader>lU	:BlakUpgrade
<leader>lr	:BlakRollback
<leader>ld	:BlakDoctor
<leader>le	:BlakExtras
<leader>lk	:BlakKeys
<leader>ln	:BlakNews
<leader>ls	:BlakSplash
<leader>lt	:BlakToolsInstall
<leader>lT	:BlakTreesitterInstall
<leader>?	:BlakKeys

Toggles

Mapping	Action
<leader>uf	Toggle format-on-save (buffer)

:BlakFormatToggle! toggles it globally. See Formatting.

Keymaps added or changed by extras

Extra	Mapping	Action
editor.window-navigation	<C-h> / <C-j> / <C-k> / <C-l>	Move between windows
ui.comfy-line-numbers	label + j / k	Comfy vertical motions
ui.comfy-line-numbers	label + <Down> / <Up>	Comfy vertical motions
ui.zen	<leader>uz	Zen mode
ui.indent	<leader>ug	Toggle indent guides
git.lazygit	<leader>gg	LazyGit float
git.diffview	<leader>gD	DiffviewOpen
git.diffview	<leader>gH	File history
git.gitbrowse	<leader>gB	Open file/line on the Git remote
git.neogit	<leader>gn	Open Neogit
ai.claudecode	<leader>ac	Toggle Claude Code
ai.claudecode	<leader>aF	Focus Claude Code
ai.claudecode	<leader>ar	Resume Claude Code
ai.claudecode	<leader>aC	Continue Claude Code
ai.claudecode	<leader>am	Select Claude model
ai.claudecode	<leader>ab	Add current buffer
ai.claudecode	<leader>as	Send visual selection
ai.claudecode	<leader>aA	Accept Claude Code diff
ai.claudecode	<leader>aD	Deny Claude Code diff
ai.sidekick	<C-.>	Focus Sidekick CLI
ai.sidekick	<leader>aa	Toggle Sidekick CLI
ai.sidekick	<leader>as	Select Sidekick CLI
ai.sidekick	<leader>ad	Detach Sidekick CLI session
ai.sidekick	<leader>af	Send file to Sidekick
ai.sidekick	<leader>at	Send current context to Sidekick
ai.sidekick	<leader>av	Send visual selection to Sidekick
ai.sidekick	<leader>ap	Pick Sidekick prompt
ai.sidekick	<leader>an	Jump to or apply the next edit suggestion
ai.copilot	<M-l>	Accept the inline suggestion (insert)
ai.copilot	<M-]> / <M-[>	Next / previous inline suggestion (insert)
debug.dap	<leader>db	Toggle breakpoint
debug.dap	<leader>dc	Continue debugging
debug.dap	<leader>di / <leader>do / <leader>dO	Step into / over / out
debug.dap	<leader>dr	Toggle DAP REPL
debug.dap	<leader>dt	Terminate debug session
debug.dap	<leader>du	Toggle dap-ui
lang.python-pro	<leader>cv	Select Python virtualenv
test.neotest	<leader>Tn	Run nearest test
test.neotest	<leader>Tf	Run current file tests
test.neotest	<leader>Td	Debug nearest test
test.neotest	<leader>Ts	Toggle test summary
test.neotest	<leader>To	Open test output
test.neotest	<leader>TO	Toggle test output panel
editor.aerial	<leader>co	Toggle code outline
editor.flash	s / S	Flash jump / Treesitter select
editor.flash	r / R	Flash remote / Treesitter search
editor.flash	<C-s>	Toggle Flash while searching (command-line)
editor.grug-far	<leader>sr	Search and replace (project-wide)
editor.scratch	<leader>.	Toggle scratch buffer
editor.scratch	<leader>S	Select scratch buffer
editor.overseer	<leader>oo	Toggle tasks
editor.overseer	<leader>or	Run task
editor.overseer	<leader>oq	Task action (pick a task, then an action)
editor.refactoring	<leader>re	Extract function
editor.refactoring	<leader>rf	Extract function to file
editor.refactoring	<leader>rv	Extract variable
editor.refactoring	<leader>ri	Inline variable
editor.refactoring	<leader>rI	Inline function
editor.refactoring	<leader>rp	Print debug variable
editor.refactoring	<leader>rc	Cleanup debug prints
editor.render-markdown	<leader>um	Toggle Markdown rendering
editor.todo-comments	]t / [t	Next / previous TODO comment
editor.todo-comments	<leader>xT	TODO quickfix
editor.trouble	<leader>xX	Trouble diagnostics
editor.trouble	<leader>xQ	Trouble quickfix
editor.trouble	<leader>xL	Trouble loclist
editor.trouble	<leader>cO	Trouble symbols
editor.trouble	<leader>cR	Trouble references
editor.harpoon	<leader>ha	Add current file to Harpoon
editor.harpoon	<leader>hh	Toggle Harpoon quick menu
editor.harpoon	<leader>hp / <leader>hn	Previous / next Harpoon file
editor.harpoon	<leader>h1-<leader>h4	Jump to Harpoon file
editor.neotree	<leader>E	Toggle Neo-tree
editor.snacks-explorer	<leader>e	Snacks explorer
editor.snacks-terminal	terminal.toggle_key	Snacks terminal

Design notes

• No hidden chords. If a Blak mapping isn’t in this page or in :BlakKeys, it doesn’t exist in core, enabled extras, or user.lua.
• Mnemonic grouping. <leader>f* find, <leader>b* buffers, <leader>g* git, <leader>c* code, <leader>x* diagnostics, <leader>l* Lazy/Blak, <leader>t* terminal, <leader>u* UI toggles, <leader>w* windows, <leader>q* quit. Extras use <leader>a* AI, <leader>d* debug, <leader>h* Harpoon, <leader>o* tasks, <leader>r* refactor, <leader>s* search, and <leader>T* test; which-key labels these groups once an enabled extra maps a key under them.
• map_if_available. Keys like <C-s> and <D-s> are only set when not already mapped — they yield to native bindings or another plugin’s claim.
• Extras and user config add to or retarget this list. Run :BlakKeys to see what your enabled extras and user.lua have registered.