malkomalko / awesome-hammerspoon

Hammerspoon is a tool for powerful automation of OS X. And here is my configuration for realizing some functionality I want.

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, dictionary translation, cheatsheets... etc.

Get started

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

and you're set.

Keep update

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.

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.

1. Desktop Widgets

More details

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.

UPDATE: Add new widget hcalendar and make it default module. The design comes from here.

2. Mode Block

More details

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
⌥ + 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 to DOCK mode. 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 ⇧ + 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 show key bindings, also available in resize, view, timer mode.

5. Hammer Search(search mode) ⌥ + G

More details

Now you can search Safari tabs and online dictionary(use ⌃ + ⇥ to switch between them).

Dictionary search supports word suggestion(see the above gif) and English thesaurus(use ⌃ + D to request). And did you notice that the translation is instant?

Due to the uncertainty of asynchronous request, usually you need to append a space to end of the word to fully translate it.

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

7. Cheatsheet(cheatsheet mode) ⌥ + S

More details

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

Let the picture talk:

Default off. To add this module to your config, please refer to the Customization section.

8. Clipboard Show(clipboard mode) ⌥ + 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.

9. 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.

Download Mode(aria2 frontend) ⌥ + D

I use glutton(a tiny webclient for aria2) to manage aria2's download queue. This mode creates an interface for glutton, so I can handle aria2 more convenient.

Default off. To add this module to your config, please refer to the Customization section.

To speed up the display of webclient, by default when you press ⎋ the interface is hiden(instead destroyed). This may increase resource occupation. If you don't use download mode for a long time, when quitting use ⌃ + ⎋ to completely destory the webclient.

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

---

For those who care about system resource:

---

Customization

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 = {
        "basicmode",
        "widgets/netspeed",
        "widgets/hcalendar",
        "widgets/analogclock",
        "modes/indicator",
        "modes/clipshow",
        "modes/hsearch",
    }
   

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

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

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	{{"alt"}, "space"}
   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 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. Create your own modal key bindings

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

5. Global options

   These options should be put into ~/.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 = "netspeed/hide/never"
   
   -- 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}

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.

: )