Kakoune Language Server Protocol Client

This is a Language Server Protocol client for the Kakoune editor (version v2021.11.08 or higher).

Quick Start

1. Installing

2. Install language servers for your desired languages

3. Configure Kakoune to enable LSP integration

4. Configure key mappings

5. Troubleshooting

Installing

Pre-built binaries

Package managers

• Alpine Linux (edge): apk add kakoune-lsp

• Arch Linux: pacman -S kakoune-lsp or AUR/kakoune-lsp-git

• FreeBSD pkg add kakoune-lsp

• Fedora Copr: sudo dnf copr enable atim/kakoune -y && sudo dnf install kakoune-lsp

• MacOS: brew install kakoune-lsp/kakoune-lsp/kakoune-lsp

• openSUSE

• Void Linux: xbps-install -S kak-lsp

Manual

[ $(uname -sm) = 'Darwin arm64' ] &&
    curl -OL https://github.com/kakoune-lsp/kakoune-lsp/releases/download/v18.0.3/kakoune-lsp-v18.0.3-aarch64-apple-darwin.tar.gz
[ $(uname -sm) = 'Darwin x86_64' ] &&
    curl -OL https://github.com/kakoune-lsp/kakoune-lsp/releases/download/v18.0.3/kakoune-lsp-v18.0.3-x86_64-apple-darwin.tar.gz
[ $(uname) = Linux ] &&
    curl -OL https://github.com/kakoune-lsp/kakoune-lsp/releases/download/v18.0.3/kakoune-lsp-v18.0.3-x86_64-unknown-linux-musl.tar.gz
tar xzvf kakoune-lsp-v18.0.3-*.tar.gz
# replace `~/.local/bin/` with something on your `$PATH`
mv kak-lsp ~/.local/bin/

From source

Generally, you need the latest stable version of Rust to build kakoune-lsp.

git clone https://github.com/kakoune-lsp/kakoune-lsp
cd kakoune-lsp
# this installs the kak-lsp binary to ~/.cargo/bin, which must be in your `$PATH`
cargo install --locked --force --path .

Install language servers for your desired languages

kakoune-lsp doesn’t manage installation of language servers, please install them by yourself for the languages you plan to use kakoune-lsp with. Please consult the How to install servers wiki page for quick installation of language servers supported by kakoune-lsp out of the box.

Configure Kakoune to enable LSP integration

To enable LSP support for configured languages (see Configuration) add the following commands to your kakrc:

eval %sh{kak-lsp}
lsp-enable

Alternatively, enable LSP only for specific filetypes you need via lsp-enable-window, e.g.:

eval %sh{kak-lsp}
hook global WinSetOption filetype=(rust|python|go|javascript|typescript|c|cpp) %{
    lsp-enable-window
}

Configure key mappings

There are three default mappings in goto-mode: gd (lsp-definition), gy (lsp-type-definition) and gr (lsp-references). You can override them in your kakrc after this plugin is loaded.

Here are additional recommended mappings. See below for the meaning of each command.

map global user l ':enter-user-mode lsp<ret>' -docstring 'LSP mode'

map global insert <tab> '<a-;>:try lsp-snippets-select-next-placeholders catch %{ execute-keys -with-hooks <lt>tab> }<ret>' -docstring 'Select next snippet placeholder'

map global object a '<a-semicolon>lsp-object<ret>' -docstring 'LSP any symbol'
map global object <a-a> '<a-semicolon>lsp-object<ret>' -docstring 'LSP any symbol'
map global object f '<a-semicolon>lsp-object Function Method<ret>' -docstring 'LSP function or method'
map global object t '<a-semicolon>lsp-object Class Interface Struct<ret>' -docstring 'LSP class interface or struct'
map global object d '<a-semicolon>lsp-diagnostic-object --include-warnings<ret>' -docstring 'LSP errors and warnings'
map global object D '<a-semicolon>lsp-diagnostic-object<ret>' -docstring 'LSP errors'

Usage

Note

Contents below corresponds to the master branch HEAD and could be slightly out-of-sync with the version installed from pre-built binaries. The most common case is new commands being in a pre-release testing stage. Please refer to the README.asciidoc revision tagged with the version you use or the README.asciidoc from the release archive.

If you have followed above steps you get

• completions

• lsp-definition command to jump to the definition of the symbol under the main cursor (mapped to gd by default)

• lsp-references command to find references to the symbol under the main cursor, mapped to gr by default

• lsp-declaration command to jump to the declaration of the symbol under the main cursor

• lsp-type-definition command to jump to the definition of the type of the symbol under the main cursor, mapped to gy by default

• lsp-implementation command to find implementations for the symbol under the main cursor

  • for the previous five commands, the *goto* buffer has filetype lsp-goto, so you can press <ret> on a line or use the jump command

• lsp-hover command to show hover info (including relevant diagnostics when available) in the info box.

  • lsp-hover-buffer command to show the same in a scratch buffer.

  • to automatically show hover when you move around, use lsp-auto-hover-enable or lsp-auto-hover-buffer-enable.

  • to show hover anchored to hovered position, use set global lsp_hover_anchor true

  • to exclude diagnostics, use set-option global lsp_show_hover_format 'printf %s "${lsp_info}"'

• lsp-find-error command to jump to the next or previous error in the current file

• lsp-selection-range command to quickly select interesting ranges around selections.

  • lsp-selection-range-select to navigate ranges fetched by lsp-selection-range.

    • A polyfill of Kakoune’s jump-* commands to jump to the next or previous location listed in a buffer with the lsp-goto filetype. These also work for buffers *grep*, *lint* and *make*

• lsp-highlight-references command to select (unless run in a hook context) all references to the symbol under the main cursor in the current buffer and highlight them with the Reference face (which is equal to the MatchingChar face by default)

• lsp-document-symbol command to list the current buffer’s symbols in a buffer of type lsp-document-symbol

• lsp-goto-document-symbol command to jump to one of the current buffer’s symbols

• lsp-workspace-symbol command to list project-wide symbols matching the query

• lsp-workspace-symbol-incr command to incrementally list project-wide symbols matching the query

  • *symbols* buffer has filetype lsp-goto so you can press <ret> on a line or use the jump command

• lsp-diagnostics command to list project-wide diagnostics (current buffer determines project and language to collect diagnostics for)

  • *diagnostics* buffer has filetype lsp-diagnostics so you can press <ret> on a line or use the jump command

• lsp-incoming-calls and lsp-outgoing-calls commands to list callers and callees of the function at the cursor.

  • *callers* and *callees* buffers have filetype lsp-goto so you can press <ret> on a line or use the jump command

• lsp-signature-help command to show signature information of the function under the main cursor

  • To automatically show signature information in insert mode, use lsp-auto-signature-help-enable.

• inline diagnostics highlighting using the DiagnosticError, DiagnosticHint, DiagnosticInfo, DiagnosticWarning, DiagnosticTagDeprecated and DiagnosticTagUnnecessary faces; can be disabled with lsp-inline-diagnostics-disable command

• flags in the left margin on lines with errors or other diagnostics; can be disabled with lsp-diagnostic-lines-disable command

• for lines with code lenses, a > flag which can be customized via the lsp_code_lens_sign option

  • lsp-code-lens command to execute a code lens from the current selection

  • commands lsp-inlay-code-lenses-enable and lsp-inlay-code-lenses-disable to toggle rendering of code lenses.

  • You can change the code lenses' face with set-face global InlayCodeLens <face>.

• lsp-formatting command to format current buffer, according to the tabstop and lsp_insert_spaces options

• lsp-formatting-sync command to format current buffer synchronously, suitable for use in a BufWritePre hook:

hook global BufSetOption filetype=rust %{
    hook buffer BufWritePre .* lsp-formatting-sync
}

• lsp-object command to select adjacent or surrounding syntax tree nodes in object mode

  • lsp-diagnostic-object does something similar but for inline diagnostics.

• lsp-next-symbol and lsp-previous-symbol command to go to the buffer’s next and current/previous symbol.

• lsp-hover-next-symbol and lsp-hover-previous-symbol to show hover of the buffer’s next and current/previous symbol.

• lsp-rename <new_name> and lsp-rename-prompt commands to rename the symbol under the main cursor.

• Breadcrumbs in the modeline indicating the symbol around the main cursor, like (somemodule > someclass > somefunction).

  • To implement this, kakoune-lsp adds %opt{lsp_modeline} to the front of your global modelinefmt at load time.

• An hourglass character (⌛) in the modeline whenever the language server indicates it’s busy.

  • To customize this behavior, override lsp-handle-progress.

• If lsp_auto_show_code_actions is true, a lightbulb (💡) in the modeline whenever code actions are available at the main cursor position

  • To customize the lightbulb, you can override lsp-show-code-actions and lsp-hide-code-actions

• lsp-code-actions to open a menu to choose a code action to run

  • To customize the menu, you can override lsp-perform-code-action

• lsp-code-action to run the code action matching the given pattern.

• lsp-code-action-sync to synchronously run that code action, suitable for use in a BufWritePre hook.

• lsp_diagnostic_error_count, lsp_diagnostic_hint_count, lsp_diagnostic_info_count and lsp_diagnostic_warning_count options which contain the number of diagnostics of the respective level for the current buffer. For example, you can put it into your modeline to see at a glance if there are errors in the current file

• lsp-execute-command command to execute server-specific commands (listed by lsp-capabilities).

• Commands starting with either of ccls-, clangd-, ejdtls-, rust-analyzer- or texlab-, that provide server specific features.

Note

By default, kak-lsp exits when it doesn’t receive any request from Kakoune for 5 hours, even if the Kakoune session is still up and running. Change the lsp_timeout option before starting kak-lsp (or use lsp-restart) to change this duration, or set it to 0 to disable this behavior. In any scenario, a new request would spin up a fresh server if it is down.

• lsp user mode with the following default mappings:

Binding	Command
a	lsp-code-actions
c	lsp-capabilities
d	lsp-definition
e	lsp-diagnostics
f	lsp-formatting
h	lsp-hover
i	lsp-implementation
j	lsp-outgoing-calls
k	lsp-incoming-calls
l	lsp-code-lens
r	lsp-references
R	lsp-rename-prompt
s	lsp-goto-document-symbol
S	lsp-document-symbol
o	lsp-workspace-symbol-incr
n	lsp-find-error
p	lsp-find-error --previous
v	lsp-selection-range
y	lsp-type-definition
9	lsp-hover-previous-function
0	lsp-hover-next-function
&	lsp-highlight-references
(	lsp-previous-function
)	lsp-next-function
[	lsp-hover-previous-symbol
]	lsp-hover-next-symbol
{	lsp-previous-symbol
}	lsp-next-symbol

To know which subset of LSP commands is backed by the current buffer’s language server use the lsp-capabilities command.

Configuration

kakoune-lsp uses Kakoune options to customize its behavior.

The lsp_servers option is a TOML table that specifies the list of servers to use for the current buffer. By default, this option is populated by hooks such as:

hook -group lsp-filetype-clangd global BufSetOption filetype=(?:c|cpp) %{
    set-option buffer lsp_servers %{
        [clangd]
        args = ["--log=error"]
        root_globs = ["compile_commands.json", ".clangd", ".git", ".hg"]
    }
}

See rc/servers.kak for the default set of servers and some commented-out alternatives.

To use different servers, add the appropriate hooks to your kakrc after the eval %sh{kak-lsp} line, To remove all default servers, use remove-hooks global lsp-filetype-.*.

Please let us know if you have any ideas about how to make the default config more sensible.

Server-specific configuration

Many servers accept configuration options that are not part of the LSP spec. The TOML table [<server_name>.settings] holds those configuration options. It has the same structure as the corresponding fragments from VSCode’s settings.json. For example:

hook global BufSetOption filetype=go %{
    set-option buffer lsp_servers %{
        [gopls]
        root_globs = ["Gopkg.toml", "go.mod", ".git", ".hg"]
        settings_section = "gopls"
        [gopls.settings.gopls]
        "formatting.gofumpt" = true
    }
}

kakoune-lsp sends the section specified by settings_section, in this case {"formatting.gofumpt":true} as part of initializationOptions and workspace/didChangeConfiguration. Additionally, kakoune-lsp will send any sections requested by the server in workspace/configuration.

Language ID ("languageId")

The current buffer’s lsp_language_id option value is sent to the language server as languageId. It should usually be the same as Kakoune’s filetype option but depending on the language server it may need to be different. See rc/servers.kak for the default set of exceptions.

Multiple language servers

It is possible to map more than one language server to a filetype. For example, if you want to set up TSServer and TailwindCSS to use in React projects:

hook global BufSetOption filetype=(?:javascript|typescript) %{
    set-option buffer lsp_servers %{
        [typescript-language-server]
        root_globs = ["tailwind.config.ts", "tailwind.config.js"]
        args = ["--stdio"]
        [tailwindcss-language-server]
        root_globs = ["package.json", "tsconfig.json", "jsconfig.json", ".git", ".hg"]
        args = ["--stdio"]
        [tailwindcss-language-server.settings.tailwindcss]
        editor = {}
    }
}

Snippets

Snippets are completions that come with placeholders ("tabstops") in the places you likely want to insert text (for example as arguments in a function call). The placeholders are highlighted with the two faces SnippetsNextPlaceholders and SnippetsOtherPlaceholders.

The lsp-snippets-select-next-placeholders command allows to jump to the next tabstop (like function call arguments). The suggested mapping uses <tab> (see Configure key mappings). Here’s a way to bind it to <c-n> instead (might need to hide the completion menu with Kakoune’s <c-o> command):

map global insert <c-n> '<a-;>:lsp-snippets-select-next-placeholders<ret>' -docstring 'Select next snippet placeholder'
hook global InsertCompletionShow .* %{
  unmap global insert <c-n> '<a-;>:lsp-snippets-select-next-placeholders<ret>'
}
hook global InsertCompletionHide .* %{
  map global insert <c-n> '<a-;>:lsp-snippets-select-next-placeholders<ret>' -docstring 'Select next snippet placeholder'
}

Snippet support can be disabled via set-option global lsp_snippet_support false before starting kak-lsp.

Other configuration options

kakoune-lsp declares the following Kakoune options:

• lsp_completion_trigger (str): This option is set to a Kakoune command, which is executed every time the user pauses in insert mode. If the command succeeds, kakoune-lsp will send a completion request to the language server.

• lsp_diagnostic_line_error_sign, lsp_diagnostic_line_hint_sign, lsp_diagnostic_line_info_sign, and lsp_diagnostic_line_warning_sign (str): When using lsp-diagnostic-lines-enable and the language server detects an error or another diagnostic, kakoune-lsp will add a flag to the left-most column of the window, using this string and one of the corresponding faces LineFlagError, LineFlagHint, LineFlagInfo or LineFlagWarning.

• lsp_hover_anchor (bool): When using lsp-hover or lsp-auto-hover-enable, if this option is true then the hover information will be displayed next to the active selection. Otherwise, the information will be displayed in a box in the lower-right corner.

• lsp_hover_max_info_lines (int): If greater than 0 then limit information in the hover box to the given number of lines. Default is 20.

• lsp_hover_max_diagnostic_lines (int): If greater than 0 then limit diagnostics in the hover box to the given number of lines. Default is 20.

• lsp_hover_insert_mode_trigger (str): This option is set to a Kakoune command. When using lsp-auto-hover-insert-mode-enable, this command is executed every time the user pauses in insert mode. If the command succeeds, kakoune-lsp will send a hover-information request for the text selected by the command.

• lsp_insert_spaces (bool): When using lsp-formatting, if this option is true, kakoune-lsp will ask the language server to indent with spaces rather than tabs.

• lsp_auto_highlight_references (bool): If this option is true then lsp-highlight-references is executed every time the user pauses in normal mode.

• lsp_auto_show_code_actions (bool): If this option is true then lsp-code-actions is executed every time the user pauses in normal mode.

• lsp_snippet_support (bool): toggles snippet support (completions with placeholders), see Snippets

• lsp_file_watch_support (bool): toggles file watch support, see Limitations

Inlay hints

Inlay hints are used to show inferred types, parameter names in function calls, and the types of chained calls inline in the code. To enable support for it, add the following to your kakrc:

lsp-inlay-hints-enable global

You can change the hints' face with set-face global InlayHint <face>.

Semantic Tokens

kakoune-lsp supports the semanticTokens feature for semantic highlighting. If the language server supports it, you can enable it with:

hook global WinSetOption filetype=<language> %{
  hook window -group semantic-tokens BufReload .* lsp-semantic-tokens
  hook window -group semantic-tokens NormalIdle .* lsp-semantic-tokens
  hook window -group semantic-tokens InsertIdle .* lsp-semantic-tokens
  hook -once -always window WinSetOption filetype=.* %{
    remove-hooks window semantic-tokens
  }
}

The faces used for semantic tokens and modifiers are defined via the lsp_semantic_tokens option, for example:

hook global BufSetOption filetype=<language> %{
    [
        {face="const_variable_declaration", token="variable", modifiers=["constant", "declaration"]},
    ]
}

where face is the face that will be applied in Kakoune (you’ll want to define these in your theme/config), token is the token’s name as reported by the language server (see lsp-capabilities) and modifiers is an array of modifier names (also reported by the language server). modifiers may be omitted, but token and face are required.

You may create any arbitrary number of definitions with permutations between the token names and modifiers reported by the server. For an entry to match a token, all the entry’s modifiers must exist on the token. However, the token may have additional modifiers not assigned in the config entry.
kakoune-lsp will find the most specific matching configuration to apply, where specificity is defined as the number of matching modifiers. If multiple matching entries have the same number of modifiers, the one that was defined last in the configuration wins.

Example:

Assuming the following configuration,

set-option global lsp_semantic_tokens %{
    [
        {face="const_variable_declaration", token="variable", modifiers=["constant","declaration"]},
        {face="const_variable", token="variable", modifiers=["constant"]},
        {face="variable", token="variable"},
    ]
}

kakoune-lsp will perform these mappings:

Token	Modifiers	Face	Comment
variable	constant, declaration	const_variable_declaration	First entry matches with 2 modifiers.
variable	constant	const_variable	First and second entry match with 1 modifier, second wins.
variable	declaration	variable	Only third entry matches. First entry doesn’t match, because constant is missing.
variable		variable	Third entry matches.
function			No entries match and no face is applied.

Inlay Diagnostics

kakoune-lsp supports showing diagnostics inline after their respective line, but this behavior can be somewhat buggy and must be enabled explicitly:

lsp-inlay-diagnostics-enable global

Markdown rendering in info box

kakoune-lsp shows some additional information provided by the language server in an info box. This information includes documentation for the token under the cursor (lsp-hover) and documentation for completion candidates. In both cases, the Language Server Protocol allows for both plain text and Markdown, and most servers do implement Markdown.

To make use of Markdown, kakoune-lsp transpiles it into Kakoune’s markup language, utilizing various faces for styling. These faces all default to the Information face, to ensure that the text in the info box works with any color scheme.

To enable Markdown highlighting, define some of the following faces in your theme or kakrc:

Face	Usage
InfoDefault	The default text color. You’ll likely want to leave this at the default Information.
InfoBlock	The face used for code blocks. Language specific syntax highlighting for code blocks is not supported.
InfoBlockQuote	The face used for block quotes. The > Markdown syntax is still rendered.
InfoBullet	The face used to highlight the list symbol for both ordered and unordered lists. For list items' text, InfoDefault is used.
InfoHeader	The face used for headings. There is currently no distinction between different heading levels.
InfoLink	The face used to highlight link titles. Maybe some classic blue+u for this one?
InfoLinkMono	This face is assigned to inline code spans within link titles, such as in the following Markdown snippet. Here, the word format will receive the InfoLinkMono face. [the `format` function](https://example.com)
InfoMono	The face used for inline code spans (backtick strings).
InfoRule	The face used for horizontal lines (rules).
InfoDiagnosticError	Used for error messages in the diagnostics inside hover info. This defaults to Kakoune’s built-in Error face.
InfoDiagnosticHint	Used for hints in the diagnostics inside hover info.
InfoDiagnosticInformation	Used for informational messages in the diagnostics inside hover info.
InfoDiagnosticWarning	Used for warnings in the diagnostics inside hover info.

For convenience, here is a snippet to paste into your theme/config:

face global InfoDefault               Information
face global InfoBlock                 Information
face global InfoBlockQuote            Information
face global InfoBullet                Information
face global InfoHeader                Information
face global InfoLink                  Information
face global InfoLinkMono              Information
face global InfoMono                  Information
face global InfoRule                  Information
face global InfoDiagnosticError       Information
face global InfoDiagnosticHint        Information
face global InfoDiagnosticInformation Information
face global InfoDiagnosticWarning     Information

Current limitations of this feature are:

• Language specific syntax highlighting for code blocks is not supported.

• For hyperlinks, only their title (the pretty name) is shown.

• The original syntax for headings is retained to visualize their level.

Limitations

workspace/didChangeWatchedFiles is disabled by default; use set-option global lsp_file_watch_support true before starting kak-lsp to enable it.

Encoding

kakoune-lsp works best with UTF-8 documents.

Position.character interpretation

The LSP spec says that column offsets (Position.character) are to be interpreted as UTF-16 code units. Many servers violate the spec. Please refer to microsoft/language-server-protocol#376 for some background.

kakoune-lsp adheres to the spec but will prefer UTF-8 offsets if the server advertises support for UTF-8 offsets via client capabilities general.positionEncodings or clangd protocol extension.

Troubleshooting

If kakoune-lsp fails, check the log in the *debug* buffer. To get more verbose logs, run:

set global lsp_debug true

If this does not give enough insight to fix the problem, don’t hesitate to raise an issue.

Please also try to reproduce your issue with a minimal configuration. Sometimes a problem occurs only with specific lsp* settings in your ~/.config/kak/{kakrc,autoload}. To start both Kakoune and kakoune-lsp without user-specific configuration, use this command:

env -u XDG_CONFIG_HOME HOME=$(mktemp -d) kak -e '
    eval %sh{kak-lsp}
    set global lsp_debug true
    lsp-enable'
# Now reproduce the issue and check the *debug* buffer for logs.

If this works and your configuration doesn’t, remove lines from your configuration until you find the one that causes the problem.

Versioning

kakoune-lsp follows SemVer with one notable difference from common practice: we don’t use 0 major version to indicate that product is not yet reached stability. Even for non-stable and not feature-complete product user should be clearly informed about breaking change. Therefore we start with major version 1 and increment it each time when upgrade requires user’s attention.