Hammerspoon

Overview

Hammerspoon is a powerful macOS automation tool that bridges the operating system with the Lua scripting engine, enabling users to deeply control and automate various aspects of macOS by writing Lua scripts.

Core Features

• System API Bridging: Exposes macOS system functionalities to Lua via a set of extension modules
• Comprehensive Coverage: Supports applications, windows, mouse pointers, file systems, audio devices, battery, screens, keyboard/mouse events, clipboard, location services, Wi-Fi, and more
• Event-Driven Automation: Connects system events to custom actions through Lua configuration files

Key Features

🎯 Window Management

• Customize keyboard shortcuts to control window layout and positioning
• Quickly arrange and switch between application windows
• Create complex sequences of window operations

⌨️ Input Device Control

• Low-level monitoring and remapping of keyboard and mouse events
• Create global shortcuts to trigger complex operations
• Implement custom input device behaviors

🌐 Network Automation

• Trigger actions based on Wi-Fi network connection status
• Automatically execute network-related configurations and tasks
• Adjust system settings according to changes in network environment

🔋 System Status Monitoring

• Monitor and alert on battery level
• System event triggers (e.g., screen lock, user switch)
• Automated responses to hardware state changes

🔧 Deep Integration

• Seamless integration with AppleScript
• Access to native macOS APIs
• Support for location-based triggers (e.g., geolocation-based automation)

Advantages

💪 Powerful & Flexible

• Unlimited Automation: Capable of controlling nearly every aspect of macOS
• Lua Scripting: Uses lightweight yet powerful Lua language for programming
• Modular Design: Easily extend functionality via modules

🎨 Highly Customizable

• Personalized Configuration: Each user can create unique automation setups
• Community Plugins: Supports “Spoons” (prebuilt plugin packages)
• Progressive Learning: Suitable for beginners to experts, from simple scripts to complex systems

🔄 Responsive Architecture

• Event-Driven: Real-time response to system state changes
• Background Operation: Low resource usage, continuous monitoring
• Instant Effect: Configuration changes apply immediately without restart

Use Case Examples

1. Boost Productivity: One-click window layout organization
2. Smart Environment Adaptation: Automatically switch work modes based on network connection
3. Health Reminders: Timed reminders to rest, adjust screen brightness
4. Creative Automation: Automatically play music when detecting specific geolocation
5. Developer Assistance: Custom hotkeys and automation workflows for development environments

Community & Ecosystem

• Active Community: Discord server for user discussion and support
• Rich Documentation: Complete API reference and beginner’s guide
• Open Source Contributions: Developers welcome to contribute new extensions and features
• Plugin Ecosystem: A wide selection of “Spoons” plugins available for use

Technical Foundations

• Core Language: Lua 5.3/5.4
• System Requirements: macOS 10.12 or higher
• Architecture: Hybrid Objective-C + Lua
• Configuration File: ~/.hammerspoon/init.lua as the main config

Ideal For

• Professionals seeking maximum productivity
• Users who enjoy automating repetitive tasks
• Developers and tech enthusiasts
• Users needing deep customization of macOS

Hammerspoon is more than just an automation tool—it’s like giving macOS a programmable, intelligent brain, allowing users to use their computer exactly the way they want. While there is a learning curve, mastering it makes it the ultimate tool for enhancing your macOS experience.

Tip: Beginners are encouraged to start with the official getting-started guide and explore gradually. The community is very supportive—feel free to seek help on Discord or GitHub if you encounter issues.