Awesome-hammerspoon, as advertised.

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, Alfred-like search, aria2 GUI, dictionary translation, cheatsheets, take notes ... etc.

Get started

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

and you're set.

Keep update

See awesome-hammerspoon whiteboard for changlog and roadmap.

To update, run cd ~/.hammerspoon && git pull.

What's modal-based key bindings?

More details

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.

How to use?

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

1. Desktop Widgets

More details

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

There are also other widgets calendar, time elapsed, maybe more …

2. More Widgets and Modes

More details

There is actually more besides these. Now you can press ⌥ + R to enter resize mode, or press ⌥ + A to enter app mode …and start to explore.

In order to make one single keystroke work in two scenes, you may want to know in which scene you are now. If you enter certain scene (and forget to exit, and wonder why your regular typing doesn't work as expected), see if there is a small circle in the bottom right corner, which indicates different scenes with different color. If that's the fact, then you realize you need to press ⎋, exit current scene, dismiss the circle, and get back to your work.

Key bindings available:

Key bindings	Movement
`⌥` + `A`	Enter `app` mode
`⌥` + `C`	Enter `clipboard` mode
`⌥` + `D`	Launch aria2 GUI .
`⌥` + `G`	Launch hammer search
`⌥` + `I`	Enter `timer` mode
`⌥` + `R`	Enter `resize` mode
`⌥` + `S`	Enter `cheatsheet` mode
`⌥` + `T`	Show current time
`⌥` + `v`	Enter `view` mode
`⌥` + `Z`	Toggle Hammerspoon console
`⌥` + `⇥`	Show window hints

In most modes, you can use Q, or ⎋ to quit back. And switch from one mode to another directly.

3. Window Management(resize mode) `⌥` + `R`

More details

Use [/] to cycle through active windows.

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 ⇧ + H/J/K/L to move windows around.

Use ␣ or ⇡⇣⇠⇢⇠ to move windows to other screens.

Use ⇧ + Y/U/I/O to resize windows.

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

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.

4. App Launcher(app mode) `⌥` + `A`

More details

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'},
}

UPDATE: Now you can press ⇥ to toggle key bindings, also available in resize, view, timer mode.

5. Hammer Search `⌥` + `G`

More details

Now you can do lots of things with Hammerspoon search: search Safari tabs, dictionary translation, kill active application, English thesaurus, get latest posts from v2ex, emoji search, take notes … etc. And feel free to add your own source!

NOTICE: If you heavily rely on instant translation(youdao dict), please consider applying for your own API key at here:

http://fanyi.youdao.com/openapi?path=data-mode

Then add them to ~/.hammerspoon/private/awesomeconfig.lua:

youdaokeyfrom = 'hsearch'  -- keyfrom
youdaoapikey = '1199732752'  -- API key

6. Aria2 GUI `⌥` + `D`

More details

This is a "native" frontend for aria2.

You need to run aria2 with RPC enabled before using this. Config aria2 host and token in ~/.hammerspoon/private/awesomeconfig.lua, then you're ready to go.

aria2_host = "http://localhost:6800/jsonrpc" -- default host
aria2_token = "token" -- YOUR OWN TOKEN

Add new task (regular URL or BTfile or Metafile) from aria2 "toolbar", click certain task item to pause/resume the download, or open completed files. While holding down ⌘ key, you click certain item, that will stop the download, or remove the completed/error task. It will notify you if there is any completed download or any error, even aria2 window is closed. And you can batch add tasks from your pasteboard, one URL per line.

7. Timer Indicator(timer mode) `⌥` + `I`

More details

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.

8. Cheatsheet(cheatsheet mode) `⌥` + `S`

More details

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

Let the picture talk:

9. Clipboard Show `⌥` + `C`

More details

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. And I never need to do this below: focus the default browser, click the address bar, paste the URL and press Enter to go.

10. Other Stuff

Tmux-styled Clock ⌥ + T

Works even when you're watching video in fullscreen.

Windows Hint ⌥ + ⇥

Focus to your windows easier.

Netspeed Monitor

Watch your netspeed sitting on the menubar. Support macos's darkmode.

Bing Wallpaper

Automatically use Bing daily picture for your wallpaper.

Lock Screen ⌘ + ⌃ + ⇧ + L

No description.

And More...

For whatever mode, you can always use:

fn + H/J/K/L to navigate, fn + Y/U/I/O to scroll, + , to leftClick, + . to rightClick.

⌘ + ⌥ + ⇠ 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

Customization

More details

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

Add application launching hotkey

See the section App launcher(app mode) above.

Add/Remove the plugin modules

default modules:

 module_list = {
     "widgets/netspeed",
     "widgets/calendar",
     "widgets/hcalendar",
     "widgets/analogclock",
     "widgets/timelapsed",
     "widgets/aria2",
     "modes/basicmode",
     "modes/indicator",
     "modes/clipshow",
     "modes/cheatsheet",
     "modes/hsearch",
     "misc/bingdaily",
 }

For example, remove bingdaily module, add your own module mymodule:

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

Modify/Remove the default key bindings

Available key binding variables:

Action	Variable	Default value
Reload Configuration	hsreload_keys	{{"cmd", "shift", "ctrl"}, "R"}
Toggle Modal Supervisor	modalmgr_keys	{{"cmd", "shift", "ctrl"}, "Q"}
Toggle Hammerspoon Console	toggleconsole_keys	{{"alt"}, "Z"}
Lock Screen	lockscreen_keys	{{"cmd", "shift", "ctrl"}, "L"}
Enter Application Mode	appM_keys	{{"alt"}, "A"}
Enter Clipboard Mode	clipboardM_keys	{"alt"}, "C"}
Launch Aria2 GUI .	aria2_keys .	{"alt"}, "D"}
Launch Hammer Search	hsearch_keys	{{"alt"}, "G"}
Enter Timer Mode	timerM_keys	{{"alt"}, "T"}
Enter Resize Mode	resizeM_keys	{{"alt"}, "R"}
Enter Cheatsheet Mode	cheatsheetM_keys	{{"alt"}, "S"}
Show Digital Clock	showtime_keys	{{"alt"}, "T"}
Show Window hints	winhints_keys	{{"alt"}, "tab"}
Lefthalf of Screen	resizeextra_lefthalf_keys	{{"cmd", "alt"}, "left"}
Righthalf of Screen	resizeextra_righthalf_keys	{{"cmd", "alt"}, "right"}
Fullscreen	resizeextra_fullscreen_keys	{{"cmd", "alt"}, "up"}
Resize & Center	resizeextra_fcenter_keys	{{"cmd", "alt"}, "down"}
Center Window	resizeextra_center_keys	{{"cmd", "alt"}, "return"}

For example, to modify Toggle Modal Supervisor key binding:

 modalmgr_keys = {{"alt"}, "F"}

To completely remove Lock Screen key binding:

 lockscreen_keys = {{}, ""}

Global options

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

aria2_host = "http://localhost:6800/jsonrpc" -- default host
aria2_token = "token" -- YOUR OWN TOKEN
aria2_refresh_interval = 1 -- How often the frontend should request data from the host
aria2_show_items_max = 5 -- How many items the frontend should show

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

hotkey_tips_bg = "light"/"dark" -- Make the hotkey tips' background light or dark

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

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

-- Put timelapsed to somewhere by defining topleft point.
timelapsetopleft = {200,1800}

FAQ

How can I integrate my little script into this configutation?

Use private folder and ~/.hammerspoon/private/awesomeconfig.lua file.

If your script is just a few lines, then put it into ~/.hammerspoon/private/awesomeconfig.lua file. If it is long enough, create a file in private folder, e.g. mymodule.lua (Wow, you just create a "module" without extra code), then include this module in ~/.hammerspoon/private/awesomeconfig.lua file.

    module_list = {
        ...
        "private/mymodule",
    }

Thanks to

More details

http://www.hammerspoon.org/

https://github.com/zzamboni/oh-my-hammerspoon

https://github.com/scottcs/dot_hammerspoon

https://github.com/dharmapoudel/hammerspoon-config

http://tracesof.net/uebersicht/

Welcome to

Share your scripts and thoughts.

: )

WhiteWorld / awesome-hammerspoon

Awesome-hammerspoon, as advertised.

Get started

Keep update

What's modal-based key bindings?

How to use?

1. Desktop Widgets

2. More Widgets and Modes

3. Window Management(resize mode) `⌥` + `R`

4. App Launcher(app mode) `⌥` + `A`

5. Hammer Search `⌥` + `G`

6. Aria2 GUI `⌥` + `D`

7. Timer Indicator(timer mode) `⌥` + `I`

8. Cheatsheet(cheatsheet mode) `⌥` + `S`

9. Clipboard Show `⌥` + `C`

10. Other Stuff

Customization

FAQ

Thanks to

Welcome to

About

Languages

Awesome-hammerspoon, as advertised.

Get started

Keep update

What's modal-based key bindings?

How to use?

1. Desktop Widgets

2. More Widgets and Modes

3. Window Management(resize mode) ⌥ + R

4. App Launcher(app mode) ⌥ + A

5. Hammer Search ⌥ + G

6. Aria2 GUI ⌥ + D

7. Timer Indicator(timer mode) ⌥ + I

8. Cheatsheet(cheatsheet mode) ⌥ + S

9. Clipboard Show ⌥ + C

10. Other Stuff

Customization

FAQ

Thanks to

Welcome to

About

Languages

3. Window Management(resize mode) `⌥` + `R`

4. App Launcher(app mode) `⌥` + `A`

5. Hammer Search `⌥` + `G`

6. Aria2 GUI `⌥` + `D`

7. Timer Indicator(timer mode) `⌥` + `I`

8. Cheatsheet(cheatsheet mode) `⌥` + `S`

9. Clipboard Show `⌥` + `C`