namu.nvim

<!-- panvimdoc-include-comment
# Namu.nvim
-->
<h1 align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="site/assets/logo-dark.svg">
    <img src="site/assets/logo-light.svg" alt="Namu.nvim" width="240" height="55">
  </picture>
</h1>

**Namu.nvim** brings symbols, diagnostics, and call hierarchies into a fuzzy picker with live preview, inspired by [Zed](https://zed.dev).

[Documentation & interactive demos](https://namu.bassamai.com)

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](https://ctags.io/) is needed for the ctags picker.

## Installation

### Built-in vim.pack

Add this to your `init.lua`:

```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](https://neovim.io/doc/user/pack/) for installation and updates.

### lazy.nvim

Add this plugin specification:

```lua
{
  "bassamsdata/namu.nvim",
  cmd = "Namu",
  main = "namu",
  opts = {},
  keys = {
    { "<leader>ss",