blink_cmp_kitty

blink.cmp completions source that extracts content from Kitty terminal windows and makes it available as completions. This is an updated and streamlined version of the cmp_kitty nvim-cmp completion source, targeting blink.com.

Motivation / use case

When working on a project one often has several Kitty tabs and windows open containing different types of information from different sources. For example, one tab might contain windows containing Neovim, test output, and a command line, while another tab might contain other project-related content.

This extension pulls content from each of the tabs and windows and makes it available in Neovim via completions, which provides a bit of integration between the different tools.

Example use cases:

1. While developing a Flask application, one often needs to reference view endpoints. While one could create a custom completion source containing endpoints for each project, this can be achieved automatically with blink_cmp_kitty; Simply create a new Kitty window, run flask routes, which lists all project endpoints in that window. After jumping back to Neovim all project endpoints appear as completion candidates.

2. While working on front-end development one often has both HTML and javascript files open, with a javascript file referencing ids, classes, etc in the HTML. blink_cmp_kitty automatically parses this content from the HTML window and makes it available in the javascript window (and vice versa), allowing auto-completion that automatically updates as the project develops.

Requirements

• Neovim
• blink.cmp
• Kitty

Kitty configuration

This extension requires configuring Kitty to enable remote control. Refer to the Kitty documentation for detailed information about how to do this.

In short, set the allow_remote_control line of your kitty.conf file to one of:

allow_remote_control socket-only
allow_remote_control socket

Be sure to review the Kitty docs to understand the available settings and their security implications.

Next, follow the instructions for setting the socket that Kitty uses for communication.

Once configured you can test the Kitty configuration from the command line by opening a separate terminal and executing a command such as:

kitty @ ls

which returns a JSON response when Kitty has been configured correctly.

After configuring Kitty, then install this extension.

Installation and Configuration

Setup with lazy.nvim is something like this:

require("lazy").setup({
    {
        "Saghen/blink.cmp",
        opts = {
            sources = {
                default = {"blink_cmp_kitty", ...}
                    ...
                    providers = {
                        blink_cmp_kitty = {
                            name = "kitty",
                            module="blink_cmp_kitty",
                            opts = {
                                -- Optional config can go here
                            },
                        },
                    },
            },
        },
    },
    {
        "garyhurtz/blink_cmp_kitty",
        dependencies = {
            { "Saghen/blink.cmp" },
        },
        opts = {
            -- Optional config can go here
        }
    },
})

Configuration options can be set in either the blink.cmp or the lazy.nvim setup. The following configuration options are supported (shown with the default values):

opts = {

    enabled = true,

    trigger_characters = {},

    -- windows & tabs
    include_os_window = function(ctx)
        return true
    end,

    include_tab = function(ctx)
        return true
    end,

    include_window = function(ctx)
        return not ctx.is_self
    end,

    -- Timing configuration
    completion_min_update_period = 5, -- in seconds
    completion_item_lifetime = 60, -- in seconds
}

Window matching configuration

By default, all windows except for the window running this instance of Neovim contribute completion candidates (completions for the current window are already provided by the built-in buffer completion source). You can control which OS Windows, Tabs, and Windows contribute candidates by overriding one or more of the include_os_window, include_tab, and include_window functions in your configuration. When called, each of these functions is passed its associated context information, which the function should evaluate then return true to include it or false to exclude it and all of its children.

The context information is extracted from the output of kitty @ ls, which can be executed from within blink_cmp_kitty using the :CmpKittyLs user command. Kitty provides a wide range of information that can be used to identify which Tabs and Windows should contribute, allowing fine-tuned control based upon the title, the current working directory, environment variables, and even which foreground processes are running in a Window. Be sure to examine output of the :CmpKittyLs command to gain a better understanding of the inputs that these functions receive.

Timing configuration

blink_cmp_kitty maintains a cache of completions candidates, and makes them available to blink.cmp when requested. blink_cmp_kitty periodically evaluates each OS-Window, Tab, and Window to identify completion candidates and add them to the cache. This process begins any time the WinEnter event fires, or when completion candidates are requested and it has been more than completion_min_update_period since the previous update. Completion candidates if they are in the cache and have not been updated for completion_item_lifetime.

Testing your setup

To check your installation you can test communication between blink_cmp_kitty and Kitty itself with the command:

:CmpKittyLs

This opens a new buffer and inserts the contents of Kitty's JSON response, as it did from the command line.