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.
- Install Hammerspoon first.
git clone --depth 1 https://github.com/jeoygin/awesome-hammerspoon.git ~/.hammerspoon- Reload the configutation.
and you're set.
See awesome-hammerspoon whiteboard for project changlog and todos.
cd ~/.hammerspoon && git pull
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
appmode, 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,
Findermode, 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.
So, following above procedures, you have reloaded Hammerspoon's configutation. Let's see what we've got here.
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 …
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.
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.
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.
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
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.
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.
More details
It shows the cheatsheet of current application's hotkeys. Code comes from here.
Let the picture talk:
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.
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.
-
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
bingdailymodule, add your own modulemymodule: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"} 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 Supervisorkey binding:modalmgr_keys = {{"alt"}, "F"}To completely remove
Lock Screenkey binding:lockscreen_keys = {{}, ""} -
Global options
These options should be put into
~/.hammerspoon/private/awesomeconfig.luafile.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 = {
...
"private/mymodule",
}
More details
https://github.com/zzamboni/oh-my-hammerspoon
https://github.com/scottcs/dot_hammerspoon
Share your scripts and thoughts.
: )