Running commands at startup

Generally, any configuration changes you make to Kakoune (setting options, changing colour schemes, etc.) only take effect for the current session, and will not be present the next time you start Kakoune. To make a change permanent, you need to make Kakoune execute those commands every time it starts up.

The easiest way to do that is to put them into your kakrc file.

The kakrc file

Every time Kakoune starts up, it sets the %val{config} value to $XDG_CONFIG_HOME/kak, or if that environment variable isn't set, $HOME/.config/kak. If %val{config}/kakrc exists and is an ordinary file, Kakoune will :source it, executing all the commands inside it.

If you want to add default highlighters (like line-numbering), set options, or a default colour scheme, this is a great place to do it.

The autoload directory

Every time Kakoune starts up, if %val{config}/autoload exists and is a directory, Kakoune will recursively search it for .kak files, including following symlinks, and :source all of them.

If your kakrc gets to be too large and you want to split it up, you can put all the pieces in the autoload directory and have the same effect.

Note: If you create %val{config}/autoload, Kakoune will stop loading the standard library plugins from %val{runtime}/autoload. This allows you to control which plugins you want by selectively symlinking them into your personal autoload directory. If you want a personal autoload directory and to load all the standard plugins, you can run the following command in Kakoune:

nop %sh{
    mkdir -p "$kak_config/autoload"
    ln -s "$kak_runtime/autoload" "$kak_config/autoload/standard-library"
}

Load order

Kakoune does not guarantee anything about the load-order of plugins in the autoload directory, but guarantees that kakrc will always be loaded last. If your plugin needs to do something if some other plugin is loaded, you may be able to use the require-module command or the ModuleLoaded hook.