Awesome configuration for Hammerspoon.
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 153 commits ahead, 46 commits behind ashfinal:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

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

  1. Install Hammerspoon first.
  2. git clone --depth 1 ~/.hammerspoon
  3. Reload the configutation.

and you're set.

Keep update

See awesome-hammerspoon whiteboard for project changlog and todos.

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:

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.


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.

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:

+ + 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


More details

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

  1. Add application launching hotkey

    See the section App launcher(app mode) above.

  2. Add/Remove the plugin modules

    default modules:

     module_list = {

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

     module_list = {
  3. 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"}
    Enter View Mode viewM_keys {{"alt"}, "V"}
    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 = {{}, ""}
  4. 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}


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 = {

Thanks to

More details

Welcome to

Share your scripts and thoughts.

: )