Ki
A proof of concept to apply the "Zen" of vi to desktop automation.
What's that?
Ki introduces a novel approach to automating macOS. Inspired by the vi text editor, Ki enables modal hotkeys to execute desktop tasks to determine whether it can be effective in a desktop environment.
The default state of macOS could be considered to be in desktop mode. Ki binds a Command Escape ⌘⎋ hotkey that transitions to normal mode, in which an extensive set of command chains can be initiated.
To view all Ki shortcuts, a cheatsheet modal can be activated with ⌘⎋⌘e?. To see all shortcuts for actions that an entity implements, an entity-specific cheatsheet modal can be activated with ⌘⎋⌘a?(entity hotkey).
Click to view example workflows and their modal keybindings with accompanying descriptions.
We can use entity, action, and select mode to achieve various common tasks from desktop mode:
| Intent | Keybindings | Translation |
|---|---|---|
| Launch or focus Safari | ⌘⎋⌘es | • ⌘⎋ enter normal mode • ⌘e enter entity mode • s target the Safari application |
| Toggle media in frontmost Safari window | ⌘⎋⌘aSpaces | • ⌘⎋ enter normal mode • ⌘a enter action mode • Space toggle media • s target the Safari application |
| Focus the third Safari tab | ⌘⎋⌘ss⌘3 | • ⌘⎋ enter normal mode • ⌘s enter select mode • s target the Safari application • ⌘3 target the third tab |
With those semantics in mind, we can intuit other "sentences" if we know other entities g, ⇧s, and m:
| Intent | Keybindings | Translation |
|---|---|---|
| Launch or focus Google Chrome | ⌘⎋⌘eg | • ⌘⎋ enter normal mode • ⌘e enter entity mode • g target the Google Chrome application |
| Toggle current song in Spotify | ⌘⎋⌘aSpace⇧s | • ⌘⎋ enter normal mode • ⌘a enter action mode • Space toggle current song • ⇧s target the Spotify application |
| Focus the third Messages conversation | ⌘⎋⌘sm⌘3 | • ⌘⎋ enter normal mode • ⌘s enter select mode • m target the Messages application • ⌘3 target the third conversation from the top |
Combinations of the different modes can lead to even more complex workflows!
| Intent | Keybindings | Translation |
|---|---|---|
| Toggle media in the fourth Chrome tab | ⌘⎋⌘aSpace⌘sg⌘4 | • ⌘⎋ enter normal mode • ⌘a enter action mode • Space toggle media • ⌘s enter select mode • g target Google Chrome • ⌘4 target the fourth tab |
| Close the second Safari tab | ⌘⎋⌘aw⌘ss⌘2 | • ⌘⎋ enter normal mode • ⌘a enter action mode • w close tab • ⌘s enter select mode • s target the Safari application • ⌘2 target the second tab |
Ki has an ambitious goal of full automative coverage and already comes shipped with default hotkeys and actions for all native macOS applications. A number of other modes (file, url, etc.) are available for automating other aspects of macOS, and can be found in the Ki cheatsheet: ⌘⎋⌘e?.
Installation
Install Hammerspoon and extract Ki.spoon.zip to ~/.hammerspoon/Spoons.
Usage and Configuration
Load, configure, and start the plugin in ~/.hammerspoon/init.lua:
hs.loadSpoon('Ki') -- initialize the plugin
spoon.Ki.workflowEvents = {...} -- configure `spoon.Ki` here
spoon.Ki:start() -- enable keyboard shortcutsNearly everything in Ki is customizable! API documentation can be found here and usage examples here.
Development
# Setup
# Requires `luarocks` and `pip`
make deps # install local luarocks dependencies necessary for Ki
make dev-deps # install global luarocks dev dependencies and pip requirements for the docs generator
# Development
# The target names below can be prefixed with `watch-` to monitor for file changes using `fswatch`
make docs # generate source documentation
make lint # run linter on source and spec files
make test # run busted unit tests and generate coverage files
make dev # build and symlink the Ki spoon to the system spoons directory for quick development
make # build and create a spoon zip file in the `dist` folder