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

1. Installing

2. Install language servers for your desired languages

3. Configure Kakoune to enable LSP integration

4. Configure key mappings

5. Troubleshooting

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:

• 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.

• lsp user mode with the following default mappings:

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

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:

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.

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

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

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:

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

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.