A proof of concept to apply the "Zen" of vi to desktop automation.
Ki introduces a modal paradigm to automating macOS: as you would edit text objects with operators in vi, you would automate entities with actions in Ki.
The default state of macOS could be considered to be in desktop mode. Ki binds the Command Escape ⌘⎋ hotkey to enter normal mode, in which an extensive set of keyboard shortcuts are available when using the default config.
To view all shortcuts, a cheatsheet can be activated with ⌘⎋⌘e?.
- ⌘⎋ to enter
normalmode - ⌘e to enter
entitymode - ? to activate the
cheatsheetentity
To see all shortcuts for actions that an entity implements, a cheatsheet can be activated with ⌘⎋⌘a?(entity hotkey).
- ⌘⎋ to enter
normalmode - ⌘a to enter
actionmode - ? to use the
open cheatsheetaction - (entity hotkey) to apply the action to some target entity
Click to view more example workflows and their modal keyboard shortcuts with accompanying descriptions.
We can use entity, action, and select mode to achieve various repetitive tasks starting 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?.
Install Hammerspoon and extract Ki.spoon.zip to ~/.hammerspoon/Spoons.
Load, configure, and start the plugin in ~/.hammerspoon/init.lua:
hs.loadSpoon('Ki') -- load the plugin
spoon.Ki:useDefaultConfig() -- use the default config (optional)
spoon.Ki:start() -- enable keyboard shortcutsBy default, Ki ships with predefined shortcuts for almost all native macOS applications, common directory files, and popular websites with preconfigured modes using a default config.
Nearly everything in Ki is configurable! Everyone uses their computer differently, so Ki provides an API to use the default config with particular options, register custom entities and their shortcuts, and even create custom modes and their modal shortcuts:
hs.loadSpoon('Ki') -- load the plugin
spoon.Ki:useDefaultConfig({ -- use the default config with options as a base
include = { -- include only the following default entities
"google-chrome",
"spotify",
...
},
})
spoon.Ki:registerModes(transitions, shortcuts) -- register custom modes
spoon.Ki:registerShortcuts(shortcuts) -- register custom shortcuts
spoon.Ki:start() -- enable keyboard shortcutsAPI documentation can be found here and usage examples here.
# 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