🦅 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 API level 12 (tested on a version as old as 0.10.2.
• A configured LSP server to provide the LSP information. This is only a requirement if you need the feature. If you don't, make sure you set show_lsp_info=false so you save some cpu cycles (see more in Configuration).

Installation

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,
    },
}

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

Configuration

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

Default Options

{
    show_headers=true,
    order=1,
    concealcursor="nv",
    conceallevel=1,
    improved_markdown=true,
    mouse_mode=true,
    keyboard_mode=false,
    logging=false,
    close_on_cmd=true,
    show_lsp_info=true,
    scrollbar_offset=0,
    max_width_factor=2,
    max_height_factor=2.5,
    render_delay=500,
    detect_idle_timer=50,
    window_row=1,
    window_col=5,
    border="single",
    title="",
    title_pos="center",
    title_color="#8AAAE5",
    border_color="#8AAAE5",
    diagnostic_header_color="",
    lsp_info_header_color="",
    diagnostic_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