Namu.nvim

🌿 Jump to symbols in your code with live preview, built-in fuzzy finding, and more. Inspired by Zed, it preserves symbol order while guiding you through your codebase. Supports LSP, Treesitter, ctags, and works across buffers and workspaces.

[!WARNING] 🚧 Beta: This plugin is in beta. Breaking changes may occur.

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

🧩 Built-in Modules

| Module | Description | |----------------|--------------------------------------------------| | 🏷️ symbols | LSP symbols for current buffer | | 🌐 workspace | LSP workspace symbols, interactive, live preview | | 📂 watchtower | Symbols from all open buffers (LSP or Treesitter) | | 🩺 diagnostics | Diagnostics for buffer or full workspace, live filter | | 🔗 call_hierarchy | Call hierarchy (in/out/both) for symbol | | 🏷️ ctags | ctags-based symbols (buffer or watchtower) | | 🪟 ui_select | Wrapper for vim.ui.select with enhanced UI |

What Makes It Special

• 🔍 Live Preview: See exactly where you'll land before you jump
• 🌳 Order Preservation: Maintains symbol order as they appear in your code, even after filtering
• 🗂️ Hierarchy Preservation: Keeps the parent-child structure of your code symbols intact, so you always see context.
• 📐 Smart Auto-resize: Window adapts to your content in real-time as you type and filter, no need for a big window with only a couple of items
• 🚀 Zero Dependencies: Works with any LSP-supported language out of the box
• 🎯 Context Aware: Always shows your current location in the codebase
• ⚡ Powerful Filtering:
  • Live filtering through /xx such as /fn for fcuntions or /bf: for buffer names if watchtower module.
  • Built-in fuzzy finding that understands code structure
  • Filter by symbol types (functions, classes, methods)
  • Use regex patterns (e.g., ^__ to filter out Python's __init__ methods)
• 🎨 Quality of Life:
  • Auto-select when only one match remains
  • Remembers cursor position when you cancel
  • Customizable window style and behavior
• ✂️ Multi-Action Workflow: Perform multiple operations while Namu is open (or close it after, you choose!):
  • Delete, yank, and add to CodeCompanion chat (more plugins coming soon)
  • Works with both single and multiple selected symbols
• 🌑 Initially Hidden Mode: Start with an empty list and populate it dynamically as you type, just like the command palette in Zed and VS Code

Table of Contents

• Requirements
• Installation
• Features
• Keymaps
• Commands
• Make It Yours
• Tips
• Feature Demos
• Display Styles
• Highlights
• Contributing
• Credits & Acknowledgements
• Demo

⚡ Requirements

• LSP server for your language (Treesitter fallback for some modules)
• Treesitter (for live preview)
• ctags (for ctags module, optional)

Installation

Lazy.nvim

Using lazy.nvim:

{
    "bassamsdata/namu.nvim",
    opts = {
        global = { },
        namu_symbols = { -- Specific Module options
            options = {},
        },
    },
    -- === Suggested Keymaps: ===
    vim.keymap.set("n", "<leader>ss", ":Namu symbols<cr>", {
        desc = "Jump to LSP symbol",
        silent = true,
    }),
    vim.keymap.set("n", "<leader>sw", ":Namu workspace<cr>", {
        desc = "LSP Symbols - Workspace",
        silent = true,
    })
}

<details> <summary>📦 Paq.nvim</summary>

require "paq" {
  "bassamsdata/namu.nvim"
}

</details> <details> <summary>📦 Mini.deps</summary>

require("mini.deps").add("bassamsdata/namu.nvim")

</details>

Features

• Live kind filtering for all symbol modules (/fn, /me, etc.) and then start type like /fnmain to filter more see demo
• Filter by buffer name in watchtower: /bf:buffer_name see demo
• Combine filters: /bf:name:fn (buffer and function) see demo
• Diagnostics filtering: /er (errors), /wa (warnings), /hi (hints), /in (info) see demo
• Two display styles: tree_guides or indent [see pictures](## Display Styles)
• Configurable prefix icon for current item
• All operations are asynchronous (non-blocking)
• No dependencies except Neovim, LSP, and optional ctags
• Hierarchy Preservation: Keeps the parent-child structure of your code symbols intact, so you always see context.

Keymaps

<details> <summary>Show keymaps</summary>

| Key | Action | |-------------|----------------------------------------| | <CR> | Select item | | <Esc> | Close picker | | <C-n> | Next item | | <C-p> | Previous item | | <Tab> | Toggle multiselect | | <C-a> | Select all | | <C-l> | Clear all | | <C-y> | Yank symbol(s) | | <C-d> | Delete symbol(s) | | <C-v> | Open symbol in vertical split | | <C-h> | Open symbol in horizontal split | | <C-o> | Add symbol(s) to CodeCompanion chat |

</details>

Change Keymaps:

<details> <summary>change the default keymaps:</summary>

-- in namu_symbols.options
  movement = {
    next = { "<C-n>", "<DOWN>" }, -- Support multiple keys
    previous = { "<C-p>", "<UP>" }, -- Support multiple keys
    close = { "<ESC>" }, -- close mapping
    select = { "<CR>" }, -- select mapping
    delete_word = {}, -- delete word mapping
    clear_line = {}, -- clear line mapping
  },
  multiselect = {
    enabled = false,
    indicator = "●", -- or "✓"◉
    keymaps = {
      toggle = "<Tab>",
      select_all = "<C-a>",
      clear_all = "<C-l>",
      untoggle = "<S-Tab>",
    },
    max_items = nil, -- No limit by default
  },
  custom_keymaps = {
    yank = {
      keys = { "<C-y>" }, -- yank symbol text
    },
    delete = {
      keys = { "<C-d>" }, -- delete symbol text
    },
    vertical_split = {
      keys = { "<C-v>" }, -- open in vertical split
    },
    horizontal_split = {
      keys = { "<C-h>" }, -- open in horizontal split
    },
    codecompanion = {
      keys = "<C-o>", -- Add symbols to CodeCompanion
    },
    avante = {
      keys = "<C-t>", -- Add symbol to Avante
    },
  },

</details>

Commands

| Command | Arguments | Description | |------------------------|------------------|---------------------------------------------| | :Namu symbols | function, class, method… | Show buffer symbols, filter by kind | | :Namu workspace | | Search workspace symbols | | :Namu watchtower | | Symbols from all open buffers, it fallbacks to treesitter | | :Namu diagnostics | buffers, workspace | Diagnostics for buffer or workspace (not only open buffers) | | :Namu call in/out/both | in/out/both | Call hierarchy for symbol | | :Namu ctags [watchtower] | watchtower | ctags symbols (buffer or watchtower) | | :Namu help [topic] | symbols/analysis | Show help |

Make It Yours

You can check the configuration documentation for details on each option.

<details> <summary>Here's the full setup with defaults:</summary>

{ -- Those are the default options
  "bassamsdata/namu.nvim",
    opts = {
      -- Enable symbols navigator which is the default
      namu_symbols = {
        enable = true,
        ---@type NamuConfig
        options = {
          AllowKinds = {
            default = {
              "Function",
              "Method",
              "Class",
              "Module",
              "Property",
              "Variable",
              -- "Constant",
              -- "Enum",
              -- "Interface",
              -- "Field",
              -- "Struct",
            },
            go = {
              "Function",
              "Method",
              "Struct", -- For struct definitions
              "Field", -- For struct fields
              "Interface",
              "Constant",
              -- "Variable",
              "Property",
              -- "TypeParameter", -- For type parameters if using generics
            },
            lua = { "Function", "Method", "Table", "Module" },
            python = { "Function", "Class", "Method" },
            -- Filetype specific
            yaml = { "Object", "Array" },
            json = { "Module" },
            toml = { "Object" },
            markdown = { "String" },
          },
          BlockList = {
            default = {},
            -- Filetype-specific
            lua = {
              "^vim%.", -- anonymous functions passed to nvim api
              "%.%.%. :", -- vim.iter functions
              ":gsub", -- lua string.gsub
              "^callback$", -- nvim autocmds
              "^filter$",
              "^map$", -- nvim keymaps
            },
            -- another example:
            -- python = { "^__" }, -- ignore __init__ functions
          },
          display = {
            mode = "icon", -- "icon" or "raw"
            padding = 2,
          },
          -- This is a preset that let's set window without really get into the hassle of tuning window options
          -- top10 meaning top 10% of th