Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/andweeb/Ki

⌘ Work in macOS like you work in vim <currently under construction>
https://github.com/andweeb/Ki

automation gotta-go-fast hammerspoon macos vim

Last synced: about 1 month ago
JSON representation

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

Host: GitHub
URL: https://github.com/andweeb/Ki
Owner: andweeb
License: mit
Created: 2018-05-04T04:50:24.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2021-01-24T00:13:08.000Z (almost 4 years ago)
Last Synced: 2024-08-03T13:06:18.368Z (5 months ago)
Topics: automation, gotta-go-fast, hammerspoon, macos, vim
Language: Lua
Homepage:
Size: 925 KB
Stars: 127
Watchers: 6
Forks: 13
Open Issues: 7
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Ki

[![Build Status](https://travis-ci.com/andweeb/ki.svg?branch=master)](https://travis-ci.com/andweeb/ki) [![codecov](https://codecov.io/gh/andweeb/ki/branch/master/graph/badge.svg)](https://codecov.io/gh/andweeb/ki)

> A proof of concept to apply the ["Zen" of vi](https://stackoverflow.com/questions/1218390/what-is-your-most-productive-shortcut-with-vim/1220118#1220118) to desktop automation.

### What's that?

Ki introduces a novel approach to automating macOS. Inspired by the [vi text editor](https://en.wikipedia.org/wiki/Vi#Interface), 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](http://www.hammerspoon.org) and extract [Ki.spoon.zip](https://github.com/andweeb/ki/releases/latest) to `~/.hammerspoon/Spoons`.

## Usage and Configuration

Load, configure, and start the plugin in `~/.hammerspoon/init.lua`:

```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](https://andweeb.github.io/ki/html/Ki.html) and usage examples [here](docs/usage-examples).

## Development

```bash
# 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
```