🦅 eagle.nvim

A Neovim plugin that provides a floating window for diagnostics and LSP information.

Table of Contents

• Features
• Why eagle.nvim?
• Requirements
• Installation
• Configuration
• Usage
• Troubleshooting
• Contributing
• Support
• Acknowledgments

Features

• Smart Mouse Tracking — Detects when the mouse hovers over underlined code. Once idle (configurable delay), a floating window appears, mirroring the behavior of conventional GUI editors like VS Code.

• Comprehensive Diagnostics — Displays all diagnostics (Errors, Warnings, Hints) under the current position. Multiple diagnostics at the same location are shown in a numbered list.

• LSP Integration — Shows LSP hover information (same content as vim.lsp.buf.hover()).

• Intelligent Re-rendering — The window only re-renders when the mouse encounters a "special" character (like {}.?:), staying open while hovering over the same variable/function/operator name.

• Keyboard Mode — Opt-in keyboard control that can work alongside or independently of mouse control (eg. using the <Tab> key).

• Highly Customizable — Extensive configuration options for appearance, timing, and behavior.

Why eagle.nvim?

Feature	Built-in vim.diagnostic.open_float()	Built-in vim.lsp.buf.hover()	eagle.nvim
Mouse tracking	❌	❌	✅
Combined diagnostics + LSP	❌	❌	✅
Smart rendering	❌	❌	✅
Keyboard + Mouse cooperation	❌	❌	✅

Requirements

• Neovim >= 0.10.2 (API level 12)
• A configured LSP server to provide the LSP information

Installation

lazy.nvim is a modern plugin manager for Neovim.

Basic setup:

{
    "soulis-1256/eagle.nvim",
    opts = {},
    config = function(_, opts)
        require("eagle").setup(opts)
        vim.o.mousemoveevent = true -- Required for mouse mode
    end,
},

With keyboard mode enabled:

{
    "soulis-1256/eagle.nvim",
    opts = {
        keyboard_mode = true,
    },
    config = function(_, opts)
        require("eagle").setup(opts)
        vim.o.mousemoveevent = true
        vim.keymap.set('n', '<Tab>', ':EagleWin<CR>', { noremap = true, silent = true })
    end,
},

Alternative setup (if you encounter issues with opts):

{ "soulis-1256/eagle.nvim" },

Then in your config:

require("eagle").setup({
    -- your options here
})
vim.o.mousemoveevent = true

LazyVim is a Neovim setup powered by lazy.nvim.

Create a file under lua/plugins/eagle.lua:

return {
    {
        "soulis-1256/eagle.nvim",
        config = function()
            require("eagle").setup({
                keyboard_mode = true,
            })
            vim.o.mousemoveevent = true
            vim.keymap.set('n', '<Tab>', ':EagleWin<CR>', { noremap = true, silent = true })
        end,
    },
}

Configuration

All options can be passed to the setup() function. See config.lua for extensive documentation.

Default Options

require("eagle").setup({
    -- Behavior
    mouse_mode = true,           -- Enable mouse hover detection
    keyboard_mode = false,       -- Enable keyboard-triggered window
    close_on_cmd = true,         -- Close window when entering command mode
    show_lsp_info = true,        -- Show LSP hover information
    logging = false,             -- Enable debug logging

    -- Content
    show_headers = true,         -- Show section headers in the window
    order = 1,                   -- Order of content (1: diagnostics first, 2: LSP first)
    improved_markdown = true,    -- Enhanced markdown rendering

    -- Timing
    render_delay = 500,          -- Delay (ms) before rendering the window
    detect_idle_timer = 50,      -- Interval (ms) for idle detection

    -- Window Positioning
    window_row = 1,              -- Vertical offset from cursor
    window_col = 5,              -- Horizontal offset from cursor
    scrollbar_offset = 0,        -- Offset for scrollbar

    -- Window Size
    max_width_factor = 2,        -- Max width as factor of window width
    max_height_factor = 2.5,     -- Max height as factor of window height

    -- Window Appearance
    border = "single",           -- Border style: "single", "double", "rounded", "solid", "shadow", "none"
    title = "",                  -- Window title
    title_pos = "center",        -- Title position: "left", "center", "right"

    -- Colors (leave empty to use defaults)
    title_color = "#8AAAE5",           -- Title text color
    border_color = "#8AAAE5",          -- Border color
    diagnostic_header_color = "",      -- Diagnostic header color
    lsp_info_header_color = "",        -- LSP info header color
    diagnostic_content_color = "",     -- Diagnostic content color
    lsp_info_content_color = "",       -- LSP info content color
})

Usage

Mouse Mode

1. Hover your mouse over any code with diagnostics or LSP information
2. Keep the mouse idle for the configured delay
3. The floating window will appear automatically
4. Move to a different symbol to update the window, move away to close it, or move inside it to be able to scroll through and copy its contents

Keyboard Mode (assuming <Tab> is your custom keybind)

1. Position your cursor on any code with diagnostics or LSP information
2. Press <Tab> and the floating window will appear at your cursor position
3. Either move away to immediately close the window (eg. pressing <h>,<j>,<k>,<l>), or press <Tab> again to enter it
4. Press <Tab> one last time to close it (once inside)

Commands

Command	Description
:EagleWin	Toggle the eagle window at the current cursor position

Troubleshooting

Make sure mousemoveevent is enabled:

vim.o.mousemoveevent = true

This must be set for mouse tracking to work.

1. Ensure keyboard_mode = true in your setup
2. Make sure you've set a keymap for :EagleWin:

vim.keymap.set('n', '<Tab>', ':EagleWin<CR>', { noremap = true, silent = true })

1. Ensure show_lsp_info = true (default)
2. Verify your LSP server is attached: :LspInfo
3. Check if the LSP supports hover: try :lua vim.lsp.buf.hover()

If you're using other plugins that provide hover functionality (like noice.nvim or custom LSP handlers), you may need to disable their hover features or configure them to not conflict with eagle.nvim.

To diagnose issues, enable logging:

require("eagle").setup({
    logging = true,
})

Contributing

Contributions are welcome! Here's how you can help:

1. Report bugs — Open an issue with reproduction steps
2. Suggest features — Open an issue describing the feature
3. Submit PRs — Fork the repo, make your changes, and submit a pull request

Support

If you find this plugin useful, consider supporting its development:

• Star this repository — It helps others discover the plugin
• Provide feedback — Your input helps improve the plugin
• Donate — PayPal
• Contact — Discord

Acknowledgments

• Inspired by the hover behavior of modern IDEs like VS Code
• Built on Neovim's powerful Diagnostic API and LSP API
• Thanks to all contributors and users who provide valuable feedback