connect.kak

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

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

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

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 🐈)$ '

Documentation

> ⇒ Open a new terminal
$ ⇒ Execute commands in a shell
& ⇒ Write an attachable program to connect.sh and detach the client

listentolist / connect.kak