A proof of concept to apply the "Zen" of vi to desktop automation.

Ki introduces a novel approach to automating macOS. Inspired by the vi text editor, Ki enables composable commands to execute desktop tasks to see whether it can be effective in automating the desktop environment.

From the default resting desktop state, enter normal mode with the default hotkey ⌘⎋ (Command and Escape), where an extensive set of command chains become available to achieve various workflows:

• ⌘⎋⌘es - enter entity mode ⌘e and open or focus the Safari s application
• ⌘⎋⌘aSpaces - enter action mode ⌘a and toggle media Space in the frontmost Safari s window
• ⌘⎋⌘ss⌘3 - enter select mode ⌘s and focus a specific Safari s tab, the third one ⌘3 from the left

With those semantics in mind, we can intuit other "sentences" if we know other entities g, m, and ⇧s:

• ⌘⎋⌘eg - enter entity mode ⌘e and open or focus the Google Chrome g application
• ⌘⎋⌘aSpace⇧s - enter action mode ⌘a and toggle the current song Space in the Spotify ⇧s application
• ⌘⎋⌘sm⌘3 - enter select mode ⌘s and focus a specific Messages m conversation, the third one ⌘3 from the top

For certain applications, shortcuts can be chained even further to compose more complex workflows:

• ⌘⎋⌘aSpace⌘sg⌘4 - enter action mode ⌘a to toggle media Space, and enter select mode ⌘s to target the specific Google Chrome g tab, the fourth one ⌘4 from the left
• ⌘⎋⌘aw⌘ss⌘2 - enter action mode ⌘a to close a tab w, and enter select mode ⌘s to target the specific Safari s tab, the second one ⌘2 from the left

To see Ki shortcuts, you can activate the Cheatsheet with ⌘⎋⌘e?. To see all shortcuts for actions that an entity implements, you can show its Cheatsheet with ⌘⎋⌘a?(entity).

Install Hammerspoon and extract Ki.spoon.zip to ~/.hammerspoon/Spoons.

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 shortcuts

Nearly everything in Ki is customizable! API documentation can be found here and usage examples here.

# Setup
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
# Prefix the target names below 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