{"id":13761248,"url":"https://github.com/andweeb/Ki","last_synced_at":"2025-05-10T12:31:26.191Z","repository":{"id":85540681,"uuid":"132088601","full_name":"andweeb/Ki","owner":"andweeb","description":"⌘ Work in macOS like you work in vim \u003ccurrently under construction\u003e","archived":false,"fork":false,"pushed_at":"2021-01-24T00:13:08.000Z","size":947,"stargazers_count":127,"open_issues_count":7,"forks_count":13,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-08-03T13:06:18.368Z","etag":null,"topics":["automation","gotta-go-fast","hammerspoon","macos","vim"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andweeb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-05-04T04:50:24.000Z","updated_at":"2024-07-16T12:26:00.000Z","dependencies_parsed_at":"2024-01-15T03:59:03.055Z","dependency_job_id":"fe15a544-6f7e-42ca-8002-c59cc5bc6367","html_url":"https://github.com/andweeb/Ki","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andweeb%2FKi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andweeb%2FKi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andweeb%2FKi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andweeb%2FKi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andweeb","download_url":"https://codeload.github.com/andweeb/Ki/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224958119,"owners_count":17398495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","gotta-go-fast","hammerspoon","macos","vim"],"created_at":"2024-08-03T13:01:45.440Z","updated_at":"2024-11-16T18:32:28.304Z","avatar_url":"https://github.com/andweeb.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"# Ki\n\n[![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)\n\n\u003e 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.\n\n### What's that?\n\nKi 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.\n\nThe default state of macOS could be considered to be in `desktop` mode. Ki binds a `Command` `Escape` \u003ckbd\u003e⌘⎋\u003c/kbd\u003e hotkey that transitions to `normal` mode, in which an extensive set of command chains can be initiated.\n\nTo view all Ki shortcuts, a cheatsheet modal can be activated with \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘e\u003c/kbd\u003e\u003ckbd\u003e?\u003c/kbd\u003e. To see all shortcuts for actions that an entity implements, an entity-specific cheatsheet modal can be activated with \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘a\u003c/kbd\u003e\u003ckbd\u003e?\u003c/kbd\u003e\u003ckbd\u003e(entity hotkey)\u003c/kbd\u003e.\n\n\u003cdetails\u003e\n \u003csummary\u003eClick to view example workflows and their modal keybindings with accompanying descriptions.\u003c/summary\u003e\n\n\u003cbr\u003e\n\nWe can use `entity`, `action`, and `select` mode to achieve various common tasks from `desktop` mode:\n\nIntent | Keybindings | Translation\n:--- | :---: | :---\nLaunch or focus Safari | \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘e\u003c/kbd\u003e\u003ckbd\u003es\u003c/kbd\u003e | • \u003ckbd\u003e⌘⎋\u003c/kbd\u003e enter `normal` mode \u003cbr\u003e • \u003ckbd\u003e⌘e\u003c/kbd\u003e enter `entity` mode \u003cbr\u003e• \u003ckbd\u003es\u003c/kbd\u003e  target the **Safari** application\nToggle media in frontmost Safari window | \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘a\u003c/kbd\u003e\u003ckbd\u003eSpace\u003c/kbd\u003e\u003ckbd\u003es\u003c/kbd\u003e | • \u003ckbd\u003e⌘⎋\u003c/kbd\u003e enter `normal` mode \u003cbr\u003e • \u003ckbd\u003e⌘a\u003c/kbd\u003e enter `action` mode \u003cbr\u003e• \u003ckbd\u003eSpace\u003c/kbd\u003e **toggle** media \u003cbr\u003e• \u003ckbd\u003es\u003c/kbd\u003e target the **Safari** application\nFocus the third Safari tab | \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘s\u003c/kbd\u003e\u003ckbd\u003es\u003c/kbd\u003e\u003ckbd\u003e⌘3\u003c/kbd\u003e | • \u003ckbd\u003e⌘⎋\u003c/kbd\u003e enter `normal` mode \u003cbr\u003e • \u003ckbd\u003e⌘s\u003c/kbd\u003e enter `select` mode \u003cbr\u003e• \u003ckbd\u003es\u003c/kbd\u003e target the **Safari** application \u003cbr\u003e• \u003ckbd\u003e⌘3\u003c/kbd\u003e target the **third** tab\n\nWith those semantics in mind, we can intuit other \"sentences\" if we know other entities \u003ckbd\u003eg\u003c/kbd\u003e, \u003ckbd\u003e⇧s\u003c/kbd\u003e, and \u003ckbd\u003em\u003c/kbd\u003e:\n\nIntent | Keybindings | Translation\n:--- | :---: | :---\nLaunch or focus Google Chrome | \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘e\u003c/kbd\u003e\u003ckbd\u003eg\u003c/kbd\u003e | • \u003ckbd\u003e⌘⎋\u003c/kbd\u003e enter `normal` mode \u003cbr\u003e • \u003ckbd\u003e⌘e\u003c/kbd\u003e enter `entity` mode \u003cbr\u003e• \u003ckbd\u003eg\u003c/kbd\u003e  target the **Google Chrome** application\nToggle current song in Spotify | \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘a\u003c/kbd\u003e\u003ckbd\u003eSpace\u003c/kbd\u003e\u003ckbd\u003e⇧s\u003c/kbd\u003e | • \u003ckbd\u003e⌘⎋\u003c/kbd\u003e enter `normal` mode \u003cbr\u003e • \u003ckbd\u003e⌘a\u003c/kbd\u003e enter `action` mode \u003cbr\u003e• \u003ckbd\u003eSpace\u003c/kbd\u003e **toggle** current song \u003cbr\u003e• \u003ckbd\u003e⇧s\u003c/kbd\u003e target the **Spotify** application\nFocus the third Messages conversation | \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘s\u003c/kbd\u003e\u003ckbd\u003em\u003c/kbd\u003e\u003ckbd\u003e⌘3\u003c/kbd\u003e | • \u003ckbd\u003e⌘⎋\u003c/kbd\u003e enter `normal` mode \u003cbr\u003e • \u003ckbd\u003e⌘s\u003c/kbd\u003e enter `select` mode \u003cbr\u003e• \u003ckbd\u003em\u003c/kbd\u003e target the **Messages** application \u003cbr\u003e• \u003ckbd\u003e⌘3\u003c/kbd\u003e target the **third** conversation from the top\n\nCombinations of the different modes can lead to even more complex workflows!\n\nIntent | Keybindings | Translation\n:--- | :---: | :---\nToggle media in the fourth Chrome tab | \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘a\u003c/kbd\u003e\u003ckbd\u003eSpace\u003c/kbd\u003e\u003ckbd\u003e⌘s\u003c/kbd\u003e\u003ckbd\u003eg\u003c/kbd\u003e\u003ckbd\u003e⌘4\u003c/kbd\u003e | • \u003ckbd\u003e⌘⎋\u003c/kbd\u003e enter `normal` mode \u003cbr\u003e • \u003ckbd\u003e⌘a\u003c/kbd\u003e enter `action` mode \u003cbr\u003e• \u003ckbd\u003eSpace\u003c/kbd\u003e **toggle** media \u003cbr\u003e• \u003ckbd\u003e⌘s\u003c/kbd\u003e enter `select` mode \u003cbr\u003e• \u003ckbd\u003eg\u003c/kbd\u003e target **Google Chrome** \u003cbr\u003e• \u003ckbd\u003e⌘4\u003c/kbd\u003e target the **fourth** tab\nClose the second Safari tab | \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘a\u003c/kbd\u003e\u003ckbd\u003ew\u003c/kbd\u003e\u003ckbd\u003e⌘s\u003c/kbd\u003e\u003ckbd\u003es\u003c/kbd\u003e\u003ckbd\u003e⌘2\u003c/kbd\u003e | • \u003ckbd\u003e⌘⎋\u003c/kbd\u003e enter `normal` mode \u003cbr\u003e • \u003ckbd\u003e⌘a\u003c/kbd\u003e enter `action` mode \u003cbr\u003e• \u003ckbd\u003ew\u003c/kbd\u003e **close** tab \u003cbr\u003e• \u003ckbd\u003e⌘s\u003c/kbd\u003e enter `select` mode \u003cbr\u003e• \u003ckbd\u003es\u003c/kbd\u003e target the **Safari** application \u003cbr\u003e• \u003ckbd\u003e⌘2\u003c/kbd\u003e target the **second** tab\n\nKi 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: \u003ckbd\u003e⌘⎋\u003c/kbd\u003e\u003ckbd\u003e⌘e\u003c/kbd\u003e\u003ckbd\u003e?\u003c/kbd\u003e.\n\u003c/details\u003e\n\n## Installation\n\nInstall [Hammerspoon](http://www.hammerspoon.org) and extract [Ki.spoon.zip](https://github.com/andweeb/ki/releases/latest) to `~/.hammerspoon/Spoons`.\n\n## Usage and Configuration\n\nLoad, configure, and start the plugin in `~/.hammerspoon/init.lua`:\n\n```lua\nhs.loadSpoon('Ki')                 -- initialize the plugin\nspoon.Ki.workflowEvents = {...}    -- configure `spoon.Ki` here\nspoon.Ki:start()                   -- enable keyboard shortcuts\n```\n\nNearly 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).\n\n## Development\n\n```bash\n# Setup\n# Requires `luarocks` and `pip`\nmake deps      # install local luarocks dependencies necessary for Ki\nmake dev-deps  # install global luarocks dev dependencies and pip requirements for the docs generator\n\n# Development\n# The target names below can be prefixed with `watch-` to monitor for file changes using `fswatch`\nmake docs      # generate source documentation\nmake lint      # run linter on source and spec files\nmake test      # run busted unit tests and generate coverage files\nmake dev       # build and symlink the Ki spoon to the system spoons directory for quick development\nmake           # build and create a spoon zip file in the `dist` folder\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandweeb%2FKi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandweeb%2FKi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandweeb%2FKi/lists"}