Modified or borrowed from Awesome-hammerspoon. It is very personal and may not suit your needs.

Hammerspoon Modal Manager

A modal-based window management tool built on Hammerspoon, inspired by Vim's modal system.

Intro

My collection of lua scripts for [Hammerspoon](http://www.hammerspoon.org/). It has highly modal-based, vim-styled key bindings, provides some functionality like desktop widgets, window management, application launcher, dictionary translation, cheatsheets... etc.
Add private dir for personal use Model hotkeys mapping and AppLaunchers. 

Core Concepts

Modal System

• Similar to Vim's modal system
• Each modal represents a specific set of functionalities (window management, app switching, etc.)
• Users can switch between different modes via hotkeys

Modal Manager

modalmgr = hs.hotkey.modal.new(modalmgr_keys[1], modalmgr_keys[2], 'Toggle Modal Supervisor')

• Acts as the top-level controller
• Manages entry/exit of all other modals
• Default activation: Alt + Space

Feature Modules

modes/
├── appM.lua -- Application management
├── clipboardM.lua -- Clipboard management
├── resizeM.lua -- Window resizing
├── viewM.lua -- View management
└── windowspace.lua -- Move Window to Space management

Code Flow

Initialization Flow

1. init.lua loads all modules
2. Initializes modal manager
3. Registers hotkeys for each module
4. Starts default modal

Modal Switching Flow

1. User presses Alt + M to enter modal manager, default key can be changed based on the private/awesomeconfig.lua
2. From modal manager, can choose:
   • Alt + A → Application Mode
   • Alt + R → Resize Mode
   • Alt + V → View Mode
   • Escape → Exit Modal

UI Feedback System

• modal_stat() - Shows current modal status
• modal_bg - Background display
• modal_show - Status display
• hotkeytext - Hotkey hints

Configuration System

• All hotkeys are customizable
• Hotkey configurations stored in variables with _keys suffix
• Examples: modalmgr_keys, appM_keys, resizeM_keys

Usage Example

1. Start Hammerspoon
2. Press Alt + M to enter modal manager
3. Choose from:
   • Alt + A → Application switching mode
   • Alt + R → Window resize mode
   • Alt + V → View management mode
   • And more...
4. Use corresponding hotkeys in each mode
5. Press Escape or Q to exit current mode

Architecture Benefits

The framework is highly modular, with each functionality encapsulated in independent modals and managed uniformly through the modal manager. This design makes feature extension and maintenance relatively easy.

Contributing

Feel free to submit issues and enhancement requests!

Key Functions

Plugins and Widgets

caffeinator  -- Prevent computer fall asleep, controlled by bar icon.
AppLauncher -- custom launcher
AClock -- custom transparent green Digital Clock show on top left of every space.
SpaceNumber -- custom transparent green Space Number show on top right of every space.
Cheatsheet -- showavailableHotkey (you don't need to remember lots of keybindings, just call cheatsheet.)
CountDownNumber -- custom plugin to display countdown number, complete with an alert sound, with a chooser
Window Resize -- using keys to control window size
SpoonInstall -- thirdparty Plugin manager
WindowGrid -- thirdparty window manager plugin
Emojis -- thirdparty Emoji plugin 
DeepLTranslate -- thirdparty translate plugin
Cherry -- thirdparty pomodoro plugin, just change some picture/time
Reload Plugins-- thirdparty reload plugin
Custom commands -- send 'exit' hotkey; hide desktop hotkey; show desktop hotkey
Clipboard -- show clipboard content
Mouse control key -- move mouse through keyboard
windowspace -- move window to lefe/right space integrated from https://github.com/Hammerspoon/hammerspoon/issues/3636#issuecomment-2384239506

Get started

1. Install Hammerspoon first.
2. Clone my configuration git clone https://github.com/zzuse/hammerspoon.git ~/.hammerspoon
3. Reload the configutation.

and you're set.

Keep update

cd ~/.hammerspoon && git pull

Details

1. Main entry point init.lua.

init.lua ==> private config (awesomeconfig.lua) ==> modalmgr(call basicmode.lua) ==> loadSpoon plugins

2. The modalmgr controls entering appMode, clipboardMode, cheatsheetMode, resizeMode, viewMode, a sign on the bottom right will show mode.

Key bindings	Movement
⌥ + M	Mode on/off
⌥ + A	Enter app mode
⌥ + C	Enter clipboard mode
⌥ + R	Enter resize mode
⌥ + S	Enter cheatsheet mode
⌥ + T	Count down number
⌥ + P	Count down number pause
⌥ + V	Enter view mode
⌥ + I	Windows Hint
⌥ + Z	Toggle Hammerspoon console
⌥ + G	Plugin Window grid
⌥ + E	Plugin Emojis
⇧ ^ + E	send EXIT to terminal
⇧ ^ + H	hide desktop file
⌘ ⇧ ^ + H	show desktop file
^ ⌥ ⌘ + C	spoon.ReloadConfigure
^ ⌥ ⌘ + D	DeepL Translate
^ ⌥ ⌘ + S	pomodoro timer tart
^ ⌥ ⌘ + P	pomodoro timer pause
^ ⌥ ⌘ + R	pomodoro timer resume
^ ⌥ ⌘ + T	toggle current time

3. App Mode, it is straightforward, just launch APPs.

4. If you enter viewMODE(ALT+V), you can using your H/I/J/K to scroll your mouse.

Key bindings	Movement
H	Scroll Leftward
L	Scroll Rightward
J	Scroll Downward
K	Scroll Upward
^ + H	Move Mouse Leftward by 50px
^ + L	Move Mouse Rightward by 50px
^ + J	Move Mouse Downward by 50px
^ + K	Move Mouse Upward by 50px
⇧ + H	Move Mouse Leftward by 10px
⇧ + L	Move Mouse Rightward by 10px
⇧ + K	Move Mouse Upward by 10px
⇧ + J	Move Mouse Downward by 10px
^ ⇧ + H	Move Mouse Leftward by 1px
^ ⇧ + L	Move Mouse Rightward by 1px
^ ⇧ + K	Move Mouse Upward by 1px
^ ⇧ + J	Move Mouse Downward by 1px
,	Left Mouse Click
.	Right Mouse Click
Q	EXIT

5. If you enter resizeMODE, you can using your Y/O/I/M/... to stretch your window.

Key bindings	Movement
⇧ + Y	'Shrink Leftward'
⇧ + O	'Stretch Rightward'
⇧ + M	'Stretch Downward'
⇧ + I	'Shrink Upward'
F	'Fullscreen'
C	'Center Window'
⇧ + C	'Resize & Center'
H	'Lefthalf of Screen'
J	'Downhalf of Screen'
K	'Uphalf of Screen'
L	'Righthalf of Screen'
Y	'NorthWest Corner'
N	'SouthWest Corner'
M	'SouthEast Corner',
O	'NorthEast Corner',
=	'Stretch Outward',
-	'Shrink Inward',
⇧ + H	'Move Leftward',
⇧ + L	'Move Rightward',
⇧ + J	'Move Downward',
⇧ + K	'Move Upward',
[	'Focus Westward',
]	'Focus Eastward',
up	'Move to monitor above'
down	'Move to monitor below'
right	'Move to monitor right'
left	'Move to monitor left',
space	'Move to next monitor'
Q	EXIT

6. Custom Countdown Number Plugin

1. A countdown number from chooser dialog

2. Result can be obtained from input box if no valid option

3. Start a countdown

4. At last there will be a completion sound alert.

---

7. Desktop Widgets

More details

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

8. Move window to Left/Right Spaces

Key bindings	Movement
⇧⌥ + 1	move window to one left space
⇧⌥ + 3	move window to one right space

9. Added SpaceNumber.spoon to show space number on every space

...

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/

sample-configurations

github move spaces Issues

Welcome to

Share your scripts and thoughts.

: )