Awesome-hammerspoon, as advertised.

 Got rid of some stuff that I don't need.  Tim

Awesome-hammerspoon is my collection of lua scripts for Hammerspoon. It has highly modal-based, vim-styled key bindings, provides some functionality like desktop widgets, window management, application launcher, cheatsheets... etc.

Hammerspoon is a tool for powerful automation of OS X. You can write Lua code that interacts with OS X APIs for applications, windows, mouse pointers, filesystem objects, audio devices, batteries, screens, low-level keyboard/mouse events, clipboards, location services, wifi, and more.¹

Out of the box, Hammerspoon does nothing. You will need Lua scripts in ~/.hammerspoon/ to do your work. Here is this repository come to help.

Get started

Install Hammerspoon first.
git clone https://github.com/ashfinal/awesome-hammerspoon.git ~/.hammerspoon
Reload the configutation.

and you're set.

What's modal-based key bindings?

Well... simply to say, it allows you using S key to resize windows in resize mode, but in app mode, to launch Safari, in timer mode, to set a 10-mins timer... something like that. During all progress, you don't have to press extra keys.

And this means a lot.

It's scene-wise, you can use same key bindings to do different jobs in different scenes. You don't worry to run out of your hotkey bindings, and twist your fingers to press ⌘ + ⌃ + ⌥ + ⇧ + C in the end.
Less keystrokes, less memory pressure. You can press ⌥ + A to enter app mode, release, then press single key S to launch Safari, or C to lauch Chrome. Sounds good? You keep your pace, no rush.
Easy to extend, you can create your own modals if you like. For example, Finder mode, in which you press T to open Terminal here, press S to send files to predefined path, press C to upload images to cloud storage.

NOTICE: After your work you'd better quit current mode back to normal. Or, you carefully pick your key bindings to avoid conflict with other hotkeys.

How to use?

So, following above procedures, you have reloaded Hammerspoon's configutation. Let's see what we've got here.

Desktop widgets

As you may have noticed, there are two clean, nice-looking desktop widgets, analogclock and calendar. Usually we don't interact with them, but I do hope you like them.

Mode block

There is also a small gray block in the bottom right corner, maybe displaying current netspeed. Well, it's actually mode block. Want to know in which mode you are? Give it a glance. When Hammerspoon starts, or there's no work to do, it shows DOCK MODE in black background. But alway displaying the black block is a little boring, so we use it for netspeed monitor if there's no activity for 5 secs.

Mode block holds the entrance to other modes, you can use ⌥ + space to toggle its display. Then use ⌥ + R to enter resize mode, or use ⌥ + A to enter app mode... etc.

Key bindings available:

Key bindings	Movement
`⌥` + `A`	Enter app mode
`⌥` + `C`	Enter `clipboard` mode
`⌥` + `D`	Enter `download` mode
`⌥` + `I`	Enter `timer` mode
`⌥` + `R`	Enter `resize` mode
`⌥` + `S`	Enter `cheatsheet` mode
`⌥` + `T`	Show current time
`⌥` + `v`	Enter `view` mode
`⌥` + `Z`	Open Hammerspoon console
`⌥` + `⇥`	Show window hints

In most modes, you can use ⌥ + key, Q, or ⎋ to quit back to DOCK mode("key" is the same as you enter modes). And switch from one mode to another directly.

Window management(resize mode)

Use H, L, J, K to resize windows.

Use =, - to expand/shrink the window size.

Use ⌘ + H/J/K/L to cycle through active windows.

Use ⇧ + H/J/K/L to move windows around.

Use ⌃ + H/J/K/L to resize windows to 1/2 of screen.

Use ⌃ + Y/U/I/O to resize windows to 1/4 of screen.

Use F to put windows to fullscreen, use C to put windows to center of screen, use ⌃ + C to resize windows to predefined size and center them.

And of course, you can use system-wide ⌘ + ⇥ to switch between active applications.

App launcher(app mode)

Use F to launch Finder or focus the existing window; S for Safari; T for Terminal; V for Activity Monitor; Y for System Preferences... etc.

If you want to define your own hotkeys, please create ~/.hammerspoon/private/awesomeconfig.lua file, then add something like below:

applist = {
    {shortcut = 'i',appname = 'iTerm'},
    {shortcut = 'l',appname = 'Sublime Text'},
    {shortcut = 'm',appname = 'MacVim'},
    {shortcut = 'o',appname = 'LibreOffice'},
    {shortcut = 'r',appname = 'Firefox'},
}

Timer indicator(timer mode)

Have you noticed this issue on macos? There is 5 pixel tall blank at the bottom of the screen for non-native fullscreen window, which is sometimes disturbing. Let's make the blank more useful. When you set a timer, this will draw a colored line to fill that blank, meanwhile, show progress of the timer.

Press 0 to set a 5-mins timer, ↩︎ to set a 25-mins timer.

Press 1 to set a 10-mins timer;

Press 2 to set a 20-mins timer;

...

Press 9 to set a 90-mins timer.

Clipboard show(clipboard mode)

It shows the content of your clipboard. If text or image type then display it with proper size, if hyperlink type then use default browser to open it. Click the display block it will destory itself.

I usually use this to display QR image for cellphone's faster scanning, or display some text for better reading.

Below is what happened when I press ⌘ + C to copy Hammerspoon.app, then press ⌥ + C to activate clipboard mode.

Cheatsheet(cheatsheet mode)

It shows the cheatsheet of current application's hotkeys. Code comes from here.

Let the picture talk:

Other stuff

Tmux-styled Clock ⌥ + T

Works even when you're watching video in fullscreen.

Windows Hint ⌥ + ⇥

Focus to your windows easier.

View Mode ⌥ + V

Use H/J/K/L to scroll around.

Use ⌃/⇧ + H/J/K/L to move mouse around.

Use ,/. for mouse left/right click.

Lock Screen ⌘ + ⌃ + ⇧ + L

For whatever mode, you can always use:

⌘ + ⌥ + ⇠ to resize windows to left-half of screen

⌘ + ⌥ + ⇢ to resize windows to right-half of screen

⌘ + ⌥ + ⇡ to resize windows to fullscreen

⌘ + ⌥ + ⇣ to put windows to predefined size

⌘ + ⌥ + ↩︎ to put windows to center of screen

For those who care about system resource:

Customization

Modify the file ~/.hammerspoon/private/awesomeconfig.lua, you should create it before doing that.

Add application launching hotkey

See the section App launcher(app mode) above.

Add/Remove the plugin modules

default modules:

module_list = {
    "basicmode",
    "widgets/netspeed",
    "widgets/calendar",
    "widgets/analogclock",
    "modes/indicator",
    "modes/clipshow",
    "modes/aria2",
    "modes/cheatsheet",
}

For example, remove aria2 module(Download mode), add your own module mymodule:

module_list = {
    "basicmode",
    "widgets/netspeed",
    "widgets/calendar",
    "widgets/analogclock",
    "modes/indicator",
    "modes/clipshow",
    "modes/cheatsheet",
    "private/mymodule",
}

Create your own modal key bindings

See http://www.hammerspoon.org/docs/hs.hotkey.modal.html, also you can refer to my scripts.

Global options

These options should be in ~/.hammerspoon/private/awesomeconfig.lua file.

-- You may want to use your own aria2 webclient.
aria2URL = "http://www.myaria2.com/"
-- Local files also are supported, like this:
aria2URL = "file:///Users/ashfinal/Downloads/glutton/index.html"

-- Make mode block idle to netspeed or just hide.
idle_to_which = "never/netspeed/hide"

-- When enter `app` mode show or hide applauncher tips automatically.
show_applauncher_tips = true/false

-- Put analogclock to somewhere by defining center point.
aclockcenter = {x=200,y=200}

-- Put calendar to somewhere by defining topleft point.
caltopleft = {200,200}

UPDATE 2: Add new widget hcalendar. The design comes from here.

Add it to your config:

    module_list = {
        "basicmode",
        "widgets/netspeed",
        "widgets/calendar",
        "widgets/analogclock",
        "modes/indicator",
        "modes/clipshow",
        "modes/aria2",
        "modes/cheatsheet",
        **"widgets/hcalendar.lua",**
    }

Move it to somewhere else on your desktop:

Modify the numbers of the below line, then add it to the ~/.hammerspoon/private/awesomeconfig.lua file.

hcaltopleft = {40,658}

UPDATE 1: Now you can press ⇥ to show key bindings, available in resize, app, view, timer mode.

TODO

Code cleanup. Make modules can be easily pluged or unpluged.

Done. It should work now, also some global options can be set by using ~/.hammerspoon/private/awesomeconfig.lua file.
Put mode block into menubar? As I usually hide menubar, this will be a better idea? Or just provide an option?
Help system for modes. Press ? to show hotkeys, so I don't have to list them all in this file.

Done. use ⇥ for showing hotkeys, and key bindings can update themself dynamically.
Safari tabs/history search
Make opening URL works for ordinary string in clipboard mode

Should work now.