neovimcraft github

plugins configs about

bassamsdata/namu.nvim

website github github
fuzzy-finder
stars 433
issues 7
subscribers 2
forks 18
CREATED

UPDATED

Namu.nvim brings symbols, diagnostics, and call hierarchies into a fuzzy picker with live preview, inspired by Zed.

Documentation & interactive demos

https://github.com/user-attachments/assets/a97ff3b1-8b25-4da1-b276-f623e37d0368

Features

  • Symbols with context: search the current buffer, open buffers, or your workspace. Tree guides show how symbols fit together.
  • Jump labels: press ; in a picker, then a displayed label to jump directly to that item. Enabled by default, with configurable keys and optional automatic activation.
  • Live preview: see a symbol's location as you move through the results.
  • Persistent sidebar: keep symbols beside your code with search, preview, and optional cursor following. Send picker results into the same sidebar.
  • Favorites: save file-backed locations from any picker or sidebar and reopen them across Neovim sessions.
  • Diagnostics and calls: browse diagnostics or follow incoming and outgoing calls when your language server supports them.
  • Actions and multiselect: select several items, send them to quickfix, yank or delete symbol text, or open a split. CodeCompanion and Avante integrations are available when installed.
  • Theme-aware selection: the focused row gets a contrasting background, including with transparent colorschemes. Custom highlights take precedence.
  • Optional pickers: Tree-sitter and ctags symbols, a colorscheme picker, and a vim.ui.select replacement.

Requirements

Namu requires Neovim 0.11+. The built-in vim.pack installation below requires Neovim 0.12+.

Use a configured language server for LSP symbols, workspace search, and call hierarchies; available features depend on the server's capabilities. Tree-sitter symbol extraction requires a parser for the buffer's language. A Nerd Font is optional for icons, and Universal Ctags is needed for the ctags picker.

Installation

Built-in vim.pack

Add this to your init.lua:

vim.pack.add({
  { src = "https://github.com/bassamsdata/namu.nvim" },
})

require("namu").setup({})

vim.keymap.set("n", "<leader>ss", "<cmd>Namu symbols<cr>", { desc = "Namu symbols" })
vim.keymap.set("n", "<leader>sw", "<cmd>Namu workspace<cr>", { desc = "Namu workspace symbols" })

This follows the default branch. To follow v0.7 releases, add version = vim.version.range("0.7") to the package specification. See Neovim's package documentation for installation and updates.

lazy.nvim

Add this plugin specification:

{
  "bassamsdata/namu.nvim",
  cmd = "Namu",
  main = "namu",
  opts = {},
  keys = {
    { "<leader>ss", "<cmd>Namu symbols<cr>", desc = "Namu symbols" },
    { "<leader>sw", "<cmd>Namu workspace<cr>", desc = "Namu workspace symbols" },
  },
}

The command and keys load Namu on demand. Put configuration in opts; see lazy.nvim's loading documentation for other triggers.

Getting started

Open a file with an attached language server, then run :Namu symbols. Type to filter, move through the results to preview the code, and press <CR> to jump. Press ; to show labels and select a result directly.

Tree guides and manual jump labels are the defaults. No configuration is needed to enable them.

Commands

Command What it shows
:Namu symbols Symbols in the current buffer
:Namu symbols function Only functions; other kinds such as class, method, and variable are supported
:Namu treesitter Current-buffer symbols from Tree-sitter
:Namu sidebar Current-file symbols, or the last list sent from a picker
:Namu sidebar symbols Replace the sidebar list with live current-file symbols
:Namu sidebar toggle Show or hide the sidebar
:Namu sidebar close / :Namu sidebar refresh Close the sidebar / refresh its live symbols
:Namu bookmarks Saved favorites
:Namu bookmarks clear Remove all favorites
:Namu workspace Workspace symbols from your language server
:Namu workspace query Workspace symbols with an initial query
:Namu watchtower Symbols across open buffers
:Namu diagnostics Current-buffer diagnostics
:Namu diagnostics buffers Diagnostics across open buffers
:Namu diagnostics workspace Available workspace diagnostics
:Namu call in Incoming calls
:Namu call out Outgoing calls
:Namu call both Both directions
:Namu ctags Current-buffer ctags symbols; enable namu_ctags first
:Namu ctags watchtower Ctags symbols across open buffers
:Namu colorscheme Colorscheme picker; enable colorscheme first
:Namu help Command help
:Namu help symbols Symbol filtering help
:Namu help analysis Symbol information for the current buffer

Picker keys

Key Action
<C-n> / <Down> Next item
<C-p> / <Up> Previous item
<CR> Select item
<Esc> Close picker; in jump mode, return to filtering first
; Toggle jump labels
<Tab> / <S-Tab> Select / unselect an item
<C-a> / <C-l> Select all / clear selection
<C-y> Yank symbol text
<C-d> Delete symbol text
<C-v> / <C-h> Open a vertical / horizontal split
<C-q> Send items to quickfix
<C-s> Send selected items, or all filtered items, to the sidebar
<C-b> Save the current item or multiselection to favorites
<C-o> / <C-t> Add to CodeCompanion / Avante

Actions depend on the picker and its items. Integrations require the corresponding plugin.

Sidebar and favorites

Run :Namu sidebar to keep symbols beside your code. Live symbol lists follow the active code buffer and refresh on file changes, saves, or LSP attachment. Lists transferred from workspace, diagnostics, or other pickers keep their saved locations. Use :Namu sidebar symbols to return to current-file symbols.

Inside the sidebar, press / to search (including /fn, /cl, and /mo filters), Enter to jump without closing, and Escape to focus code. Use p to toggle preview, f to toggle cursor following, ; for jump labels, and g? for the full shortcut reference. m saves the current item; dd removes an item from the favorites sidebar. Close with q.

Favorites, searches, selection, collapsed groups, and scroll position persist across restarts. Favorites store file paths and locations rather than buffer IDs. Set sidebar.persist = false for session-only state. Bookmarks is the command name for favorites.

Try the interactive sidebar demo, or see the sidebar recipe for configuration and mappings.

Configuration

Use global for shared picker options and a module key for its overrides:

require("namu").setup({
  global = {
    display = { format = "tree_guides" },
    jump = { enabled = true, toggle_key = ";", auto_activate = false },
  },
  namu_symbols = {
    row_position = "top10",
    window = { max_width = 100 },
  },
  sidebar = { position = "right", width = 40, persist = true },
  ui_select = { enable = false },
})

See the full configuration guide for module names, option reference, defaults, and precedence. The configuration recipes cover jump labels, display styles, filters, highlights, optional pickers, and testing a local checkout with vim.pack or lazy.nvim.

You can also read :help namu inside Neovim.

Demos

Feature Recording
Current-buffer symbols Watch
Sidebar and favorites Try the interactive demo
Workspace symbols Watch
Watchtower Watch
Diagnostics Watch
Call hierarchy Watch
Ctags Watch

Tree guides (default):

Tree guides

Indentation (display.format = "indent"):

Indentation

Contributing

Bug reports, suggestions, and pull requests are welcome. Include your Neovim version, configuration, and a small reproduction when reporting a problem. Run make format, make docs, and relevant tests for changes.

For website edits, recordings, and domain setup, see the website guide.

“Namu” means “tree” in Korean, reflecting the structure of your code.

Credits

License

MIT