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).
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
>, +, @, $ 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.
Kakoune – Launch a new connected terminal:
>
Terminal – Open all .txt
files in the connected client:
:e *.txt
Terminal – Open all .txt
files in a new client:
:o *.txt
Kakoune – Launch a connected Dolphin instance:
$ dolphin
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.
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.
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█
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.
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).
# 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>'
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.
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
}
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