Awesome

kanata-tray

A simple wrapper for kanata to control it from tray icon. Works on Windows, Linux and macOS.

Note: there's now Windows-only native tray app support in kanata (https://github.com/jtroo/kanata/pull/990)

See #24 for comparison

Features

• Tray icon for kanata, with start/stop/pause buttons.
• Easy switching between multiple kanata configurations from tray icon.
• Allow to set custom tray icons for active kanata layers.
• Blink icon on successful kanata config reload.
• Hooks (custom scripts/programs that will run before/after kanata start/stop)
• Support for running multiple kanata instances with different configurations at the same time.
• Works out-of-the box with no configuration, but can be configured with toml file.

Configuration

Default config file will be autogenerated for you on the first run. You can access it from from: Click Tray Icon > Configure.

Config file name is kanata-tray.toml.

The config folder location:

• Linux ~/.config/kanata-tray.
• Windows C:\Users\<YourUsername>\AppData\Roaming\kanata-tray
• macOS $HOME/Library/Application\ Support/kanata-tray

Alternatively, you can place your config file in the same folder as kanata-tray executable, and it will be have higher priority than the global config in user folder.

Custom config directory location can be set with KANATA_TRAY_CONFIG_DIR environment variable.

Examples

An example of customized configuration file:

'$schema' = 'https://raw.githubusercontent.com/rszyma/kanata-tray/main/doc/config_schema.json'

[general]
allow_concurrent_presets = false

[defaults]
kanata_executable = '~/bin/kanata' # if empty or omitted, system $PATH will be searched.
kanata_config = '' # if empty or not omitted, kanata default config locations will be used.
tcp_port = 5829 # if not specified, defaults to 5829

[defaults.hooks]
# Hooks allow running custom commands on specific events (e.g. starting preset).
# Documentation: https://github.com/rszyma/kanata-tray/blob/main/doc/hooks.md

[defaults.layer_icons]
mouse = 'mouse.png'
qwerty = 'qwerty.ico'
'*' = 'other_layers.ico'

[presets.'main cfg']
kanata_config = '~/.config/kanata/test.kbd'
autorun = true
# kanata_executable = ''
# layer_icons = {  }
# tcp_port = 1234

[presets.'test cfg']
kanata_config = '~/.config/kanata/test.kbd'

Explanation

presets - a config item, that adds an entry to tray menu. Each preset can have different settings for running kanata with: kanata_config, kanata_executable, autorun, layer_icons, tcp_port.

preset.autorun - when set to true, preset will run at kanata-tray startup.

preset.layer_icons - maps kanata layer names to custom icons. Custom icons should be placed in icons folder in config directory, next to kanata-tray.toml. Accepted icon types on Linux are .ico, .png, .jpg; on Windows only .ico is supported. You can assign an icon to special identifier '*' to change icon for other layers not specified in [layer_icons].

defaults - a config item, that allows to overwrite default values for all presets. It accepts same configuration options that presets do.

general.allow_concurrent_presets - when enabled, allows running multiple presets at the same time. When disabled, switching presets will stop currently running preset (if any). Disabled by default.

Other notes:

• You can use ~ in kanata_config and kanata_executable to substitute to your "home" directory.
• On Windows: make sure to surround paths with single-quotes ' instead of double-quotes, otherwise paths will not work (because \ would be treated as escape character).

Hooks

Hooks allow running custom commands on specific events (e.g. starting preset). Hooks documentation.

Config completion in editors

In VSCode to get editor support for your kanata-tray config, install Even Better TOML extension and the following line at the top of your kanata-tray.toml file.

"$schema" = "https://raw.githubusercontent.com/rszyma/kanata-tray/main/doc/config_schema.json"

Supported Kanata Versions

Minimal supported version of kanata is v1.6.0.

More specifically, builds after commit 010338b (because it fixed an issue with TCP server)

Troubleshooting

Log file - By default kanata-tray will try to write a log file named kanata_tray_lastrun.log in the same directory as itself. If it causes problems e.g. because of the location is read-only, the log directory can be changed by setting new path in KANATA_TRAY_LOG_DIR environment variable.

Debug logs - more verbose kanata-tray output, debug logging can be enabled with --log-level=1 flag. You can use it to see loaded config struct or raw tcp messages from kanata.

Linux Dependencies

For Linux, make sure to install required packages first:

Arch:

pacman -S libayatana-appindicator

also if you want to build from source:

pacman -S base-devel gtk3 go just

Ubuntu:

sudo apt-get install libayatana-appindicator3-dev

also if you want to build from source:

sudo apt-get install gcc libgtk-3-dev golang just

OpenSUSE Tumbleweed:

sudo zypper in libayatana-appindicator3-devel

Installation

Prebuild binaries for Windows and Linux: releases page

To build from source see recipes in justfile.