Namu documentation
Configuration recipes
README · Full configuration guide
Each setup example shows only the settings it changes. Combine them
into one require("namu").setup(...) call, or into
lazy.nvim's opts table.
Resume the last picker
Use :Namu resume to reopen the last closed picker with
its search, options, selected row, scroll position, multiselections, and
insert/normal/jump-label mode.
vim.keymap.set("n", "<leader>nr", "<cmd>Namu resume<CR>", {
desc = "Namu: Resume last picker",
})Lua mappings can also call require("namu").resume(). The
snapshot lasts for the current Neovim session and requires the original
buffer and window to remain available. Cached asynchronous results
appear immediately; changing the search requests new results. A request
still pending when the picker closed is restarted on resume.
Sidebar and favorites
Open and manage:
:Namu sidebar: open current-file symbols in a persistent split, or restore the last list sent from a picker.:Namu sidebar symbols: replace a transferred list with live symbols.:Namu sidebar toggle/close: show/hide or close the sidebar.:Namu sidebar refresh: refresh live symbols manually.:Namu bookmarks: open favorites alongside the main sidebar.
From any picker:
<C-b>: save the current item or your Tab selections to favorites.<C-s>: send selected items to the sidebar, or all filtered items if nothing is selected. The sidebar opens on the focused item.
Search and preview:
- Live symbols follow the active code split and refresh on file
switches, saves, and LSP attachment. Current-buffer lists sent with
<C-s>also follow file switches; workspace and diagnostics lists keep saved locations. - Filter symbols, transferred lists, or favorites with
/fn,/mo, or/cl. Add text to search within a kind:/fnrender. - The sidebar shares picker formatting, tree guides, kind colors, search highlights, and symbol-body previews. Its input shows the filter count and symbol source when known.
- New symbol lists focus the symbol at the code cursor. Preview falls
back to saved ranges without a parser; set
preview.highlight_on_move = falseto disable it, orjump.enabled = falseto disable labels.
Try search, following, and favorites in the interactive demo.
Inside a sidebar:
j/k: move between items.h/l: collapse / expand nested groups./: edit the search; Enter or Escape returns to the list.- Enter in the list: jump to the item, keeping the sidebar open.
pin normal mode: toggle preview (preview.toggle_keycustomizes this key).<C-o>toggles preview in either mode, including while jump labels are active.- Search keeps the original list order and focuses the highest-scoring match, just like the floating picker.
<C-n>/<C-p>(or configured movement keys): move through results while remaining in the search input.f(normal mode) or<C-f>(either mode): toggle following the code cursor. While code has focus, the sidebar selects the most specific visible symbol containing its cursor line. Search and collapsed groups remain in effect; following never steals focus or moves code.;: toggle jump labels; pressing a label jumps to code and keeps the sidebar open.g?: open a floating shortcut reference with the configured keys and current toggle states. Escape,q, org?closes help.m: save the current item to favorites.ddin favorites: remove the current favorite.- Escape in the list: focus code;
q: close and save the sidebar.
Inline shortcut hints use the muted, theme-derived
NamuSidebarHint highlight. Customize that group to change
their color; generated defaults refresh with your colorscheme and
preserve your override. The letters used by preview, following, and the
g? help prefix are reserved while jump labels are
active.
Code following caches symbol ranges when the list changes, batches
cursor events, and skips unchanged lines and selections. It does not
request symbols, redraw the list, or write storage while scrolling.
Toggle it from Lua with
require("namu.sidebar").toggle_follow_cursor().
Favorites, search, selection, scroll position, and collapsed groups
are saved across restarts by default. Favorites store file paths and
locations, so they remain usable after buffer IDs change. The default
storage file is
stdpath("data") .. "/namu/sidebar.json".
require("namu").setup({
sidebar = {
position = "right", -- or "left"
width = 40,
follow_cursor = { enabled = true, toggle_key = "<C-f>", letter_key = "f" }, -- defaults; set enabled = false to start disabled
persist = false, -- optional: keep state only within this session
},
})
vim.keymap.set("n", "<leader>ns", "<cmd>Namu sidebar toggle<CR>")
vim.keymap.set("n", "<leader>nb", "<cmd>Namu bookmarks<CR>")Change picker shortcuts with
global.custom_keymaps.bookmark.keys and
global.custom_keymaps.sidebar.keys. Set either list to
{} to disable that shortcut.
:Namu bookmarks clear removes all favorites.
The earlier :Namu outline command,
namu_outline setup key, and
require("namu.namu_outline") API have been removed. Use the
sidebar commands above and put its settings under
sidebar.
Jump labels
Manual activation with ; is already enabled. Change the
trigger and label keys:
require("namu").setup({
global = {
jump = { toggle_key = ";", keys = "asdfghjkl" },
},
})To activate labels automatically for small vim.ui.select
dialogs, while leaving other pickers manual:
require("namu").setup({
ui_select = {
enable = true,
jump = {
auto_activate = 10,
skip_kinds = { codeaction = true },
},
},
})The threshold uses the item count when the picker opens.
skip_kinds only suppresses automatic activation for those
selection kinds; manual activation still works.
To disable jump labels everywhere:
require("namu").setup({
global = { jump = { enabled = false } },
})Display styles
Tree guides are the default. Use indentation everywhere, then restore tree guides for symbols:
require("namu").setup({
global = { display = { format = "indent" } },
namu_symbols = {
display = { format = "tree_guides", tree_guides = { style = "ascii" } },
},
})For a font without Nerd Font icons:
require("namu").setup({
namu_symbols = {
display = { mode = "raw" },
current_highlight = { prefix_icon = "> " },
},
})Window and preview
require("namu").setup({
namu_symbols = {
row_position = "center",
window = { max_width = 90, max_height = 25, border = "single" },
preview = { highlight_on_move = false },
},
})preview.highlight_on_move controls the preview
highlight. There is no supported preview.enable switch.
Symbol filters
Use :Namu symbols function or
:Namu symbols class for a one-off kind filter. For picker
query aliases, see :Namu help symbols.
To change the default Python kinds and exclude Python names beginning
with __:
require("namu").setup({
namu_symbols = {
AllowKinds = { python = { "Function", "Class", "Method" } },
BlockList = { python = { "^__" } },
},
})AllowKinds contains LSP kind names.
BlockList contains Lua patterns, not regular expressions.
Per-filetype lists take precedence over default lists.
To prefer Tree-sitter symbols:
require("namu").setup({
namu_symbols = { source_priority = "treesitter" },
})Install a parser for the file's language. You can also use
:Namu treesitter directly.
Keys and multiselect
require("namu").setup({
global = {
movement = { next = { "<C-j>", "<Down>" }, previous = { "<C-k>", "<Up>" } },
custom_keymaps = {
quickfix = { keys = { "<C-q>" }, desc = "Send to quickfix" },
},
},
namu_symbols = {
actions = { close_on_yank = true, close_on_quickfix = true },
},
})Use <Tab> to select multiple items, then invoke an
available action. CodeCompanion and Avante examples are in action_intergration.md.
Highlights and colorschemes
The default row background adapts to the colorscheme. You normally do not need an override. A transparent picker still gives its focused row a background; it does not add an underline as a visibility fallback.
To set your own row color and keep it across colorscheme changes:
local function set_namu_highlights()
vim.api.nvim_set_hl(0, "NamuCurrentItem", { bg = "#3b4b52", bold = true })
vim.api.nvim_set_hl(0, "NamuJumpLabel", { fg = "#ffd580", bold = true })
end
vim.api.nvim_create_autocmd("ColorScheme", {
group = vim.api.nvim_create_augroup("MyNamuHighlights", { clear = true }),
callback = set_namu_highlights,
})
set_namu_highlights()Choose a background that contrasts with your picker. Explicit highlight definitions take precedence over Namu's adaptive defaults.
To hide only the current-item prefix marker:
require("namu").setup({
global = { current_highlight = { enabled = false } },
})The row background remains visible.
Optional pickers
require("namu").setup({
namu_ctags = { enable = true }, -- Requires Universal Ctags.
colorscheme = { enable = true },
ui_select = { enable = true }, -- Replaces vim.ui.select.
})Then use :Namu ctags,
:Namu ctags watchtower, or :Namu colorscheme.
UI selection uses Namu when another plugin calls
vim.ui.select.
Test a local checkout
A local checkout can be loaded without changing your installed package. Use one source for Namu in each Neovim session to avoid mixing versions.
Built-in vim.pack
Temporarily replace the GitHub vim.pack.add entry for
Namu with:
local namu_path = vim.fn.expand("~/repos/namu.nvim")
vim.opt.runtimepath:prepend(namu_path)
vim.cmd.source(namu_path .. "/plugin/namu.lua")
require("namu").setup({})Start a fresh Neovim session. This loads the working checkout directly, including uncommitted edits. There is no install or update step for the local checkout. Restore the GitHub package entry when finished.
If your configuration wraps vim.pack with custom
lazy-loading hooks, put these operations in that wrapper's load
callback, keeping its command or key triggers. Those hooks belong to
your configuration rather than vim.pack itself.
lazy.nvim
Temporarily use a local directory in the plugin specification:
{
dir = vim.fn.expand("~/repos/namu.nvim"),
name = "namu.nvim",
main = "namu",
cmd = "Namu",
opts = {},
keys = {
{ "<leader>ss", "<cmd>Namu symbols<cr>", desc = "Namu symbols" },
},
}The command and key triggers still lazy-load the local checkout.
Check which copy is loaded
:lua vim.print(vim.api.nvim_get_runtime_file("lua/namu/init.lua", true))
:lua vim.print(debug.getinfo(require("namu").setup, "S").source)The first command lists matching runtime files; the second identifies the implementation actually loaded. Restart Neovim after switching sources, since Lua modules are cached for the session.