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