surajt6 / ki

⌘ Work in macOS like you work in vim

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 shortcuts

Nearly 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