connect.kak

Installation | Usage | Configuration | Documentation | FAQ

Leverage the client-server architecture of Kakoune to connect programs to clients.

The objective of connect.kak is to synchronize external applications with Kakoune clients easily. A typical use case is opening a file browser and having it open the files in the Kakoune client. Another very typical use case is connecting a terminal.

connect.kak provides basic commands to interact with the connected client interactively or to write your own scripts (check :batch, which is an integration crafted from the rest of the commands) as well as a set of officially supported modules (Kakoune commands to programs).

Dependencies

prelude.kak

Optional integrations

Installation

Run the following in your terminal:

make install

It will install kak-shell and kak-desktop to your ~/.local/bin directory and create a kakoune-connect.desktop desktop entry.

If you want to use Kakoune as your default editor, for example when opening files in Dolphin, open $XDG_CONFIG_HOME/mimeapps.list and add the following MIME type association:

~/.config/mimeapps.list

[Default Applications]
text/plain=kakoune-connect.desktop
text/xml=kakoune-connect.desktop

Add more entries to your liking.

Add connect.kak and its modules to your autoload or source them manually.

require-module connect

Usage

>, +, @, $ and & are Kakoune commands.

The : prefixes all connect.kak shell commands, and usually have an alias on a single key – :[e]dit and :[o]pen for example.

Example 1

Kakoune – Launch a new connected terminal:

Terminal – Open all .txt files in the connected client:

:e *.txt

Example 2

Terminal – Open all .txt files in a new client:

:o *.txt

Example 3

Kakoune – Launch a connected Dolphin instance:

$ dolphin

Example 4

Kakoune – Same, but with a dedicated dolphin command:

require-module connect-dolphin

dolphin

As you can notice by its content, the module is fairly simple and seamless. We just provide the nicety to have a dolphin command from Kakoune.

Example 5

Terminal – Render with Glow the current file or buffer content:

glow `:it`

:cat | glow -

The latter outputs the buffer content, which is useful when the file is not saved.

Example 6

Terminal – Run a shell connected to an arbitrary session from your terminal:

kak-shell

Illustration

$ kak-shell
Kakoune sessions:
1 kanto
2 johto
+ create new session
Kakoune session: 1█
@kanto $ :a█

Example 7

Kakoune – Detach from the client and generate a file to connect to the session:

In the terminal that spawned the client:

$ sh connect.sh
@kanto $ █

Learn more about the commands and aliases in the documentation.

Configuration

A typical workflow is mapping Control + q to quit and use the alias :a or a to reattach back and forth inside a kak-shell (or any connected terminal).

Example configuration

# Modules
require-module connect-fzf

# Windowing
hook global ModuleLoaded x11 %{
  alias global terminal alacritty-terminal
  alias global popup alacritty-terminal-popup

  # If your terminal does not have popups, fall back to x11-terminal.
  # alias global popup x11-terminal
}

# Explore files and buffers with fzf
alias global explore-files fzf-files
alias global explore-buffers fzf-buffers

# Terminal settings
map global normal -docstring 'Terminal' <c-w> ': enter-user-mode terminal<ret>'

# Create a new window
map global normal <c-t> ': connect-terminal<ret>'
map global normal <c-n> ': connect-shell alacritty<ret>'

# Quit
map global normal <c-q> ': quit<ret>'

# Yank ring
map global normal Y ': yank-ring<ret>'

Custom connect commands

You can also define your own connect commands and aliases and locate them in a path set in the connect_paths option. By default, it is set to your %val{config}/connect/commands and %val{config}/connect/aliases folders.

Take a look at the default modules. You can use them as a skeleton to your connect commands.

Custom environment

By setting the connect_environment option, you can specify shell commands to run before running your program. This might be useful, if you want to change or export environment variables.

set-option global connect_environment %{
  export SHELL=elvish
  export GIT_EDITOR=kak
}

Custom prompt

You can modify your shell prompt to notify you whenever you are connected to a session.

Example – for Bash:

PS1='$(test "$IN_KAKOUNE_CONNECT" && printf 🐈)$ '

Example – with Starship:

~/.config/starship.toml

[custom.kakoune]
symbol = '🐈'
command = 'printf "%s@%s" "$KAKOUNE_CLIENT" "$KAKOUNE_SESSION"'
when = '[ "$KAKOUNE_SESSION" ] && [ "$KAKOUNE_CLIENT" ]'
shell = ['sh']
description = 'The current Kakoune session and client'
style = 'green'
format = '[$symbol $output]($style)'

Available variables are:

IN_KAKOUNE_CONNECT (1 when true)
KAKOUNE_SESSION
KAKOUNE_CLIENT

Similar projects

kakoune-remote-control

kakounedotcom / connect.kak

readme