andweeb / Ki

⌘ Work in macOS like you work in vim <currently under construction>

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Ki

Build Status codecov

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

About

⌘ Work in macOS like you work in vim <currently under construction>

License:MIT License


Languages

Language:Lua 91.8%Language:AppleScript 4.8%Language:Shell 1.7%Language:Makefile 0.7%Language:CSS 0.5%Language:HTML 0.4%