Hammerspoon

Project links

Resource Link
Website https://www.hammerspoon.org/
GitHub page https://github.com/Hammerspoon/hammerspoon
Getting Started Guide https://www.hammerspoon.org/go/
Spoon Plugin Documentation https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md
Official Spoon repository https://www.hammerspoon.org/Spoons
Discord Click here to join
Mailing list https://groups.google.com/forum/#!forum/hammerspoon/
LuaSkin API docs https://www.hammerspoon.org/docs/LuaSkin/

API documentation

hs

Core Hammerspoon functionality

hs.alert

Simple on-screen alerts

hs.appfinder

Easily find hs.application and hs.window objects

hs.applescript

Execute AppleScript code

hs.application

Manipulate running applications

hs.application.watcher

Watch for application launch/terminate events

hs.audiodevice

Manipulate the system's audio devices

hs.audiodevice.datasource

Inspect/manipulate the data sources of an audio device

hs.audiodevice.watcher

Watch for system level audio hardware events

hs.axuielement

This module allows you to access the accessibility objects of running applications, their windows, menus, and other user interface elements that support the OS X accessibility API.

hs.axuielement.axtextmarker

This submodule allows hs.axuielement to support using AXTextMarker and AXTextMarkerRange objects as parameters for parameterized Accessibility attributes with applications that support them.

hs.axuielement.observer

This submodule allows you to create observers for accessibility elements and be notified when they trigger notifications. Not all notifications are supported by all elements and not all elements support notifications, so some trial and error will be necessary, but for compliant applications, this can allow your code to be notified when an application's user interface changes in some way.

hs.base64

Base64 encoding and decoding

hs.battery

Battery/power information

hs.battery.watcher

Watch for battery/power state changes

hs.bonjour

Find and publish network services advertised by multicast DNS (Bonjour) with Hammerspoon.

hs.bonjour.service

Represents the service records that are discovered or published by the hs.bonjour module.

hs.brightness

Inspect/manipulate display brightness

hs.caffeinate

Control system power states (sleeping, preventing sleep, screen locking, etc)

hs.caffeinate.watcher

Watch for display and system sleep/wake/power events

hs.camera

Inspect the system's camera devices

hs.canvas

A different approach to drawing in Hammerspoon

hs.canvas.matrix

A sub module to hs.canvas which provides support for basic matrix manipulations which can be used as the values for transformation attributes in the hs.canvas module.

hs.chooser

Graphical, interactive tool for choosing/searching data

hs.console

Some functions for manipulating the Hammerspoon console.

hs.crash

Various features/facilities for developers who are working on Hammerspoon itself, or writing extensions for it. It is extremely unlikely that you should need any part of this extension, in a normal user configuration.

hs.deezer

Controls for Deezer music player.

hs.dialog

A collection of useful dialog boxes, alerts and panels for user interaction.

hs.dialog.color

A panel that allows users to select a color.

hs.distributednotifications

Interact with NSDistributedNotificationCenter

hs.doc

Create documentation objects for interactive help within Hammerspoon

hs.doc.builder

Builds documentation support files. Still experimental.

hs.doc.hsdocs

Manage the internal documentation web server.

hs.doc.markdown

Markdown to HTML and plaintext conversion support used by hs.doc

hs.dockicon

Control Hammerspoon's dock icon

hs.drawing

DEPRECATED. Primitives for drawing on the screen in various ways.

hs.drawing.color

Provides access to the system color lists and a wider variety of ways to represent color within Hammerspoon.

hs.eventtap

Tap into input events (mouse, keyboard, trackpad) for observation and possibly overriding them

hs.eventtap.event

Create, modify and inspect events for hs.eventtap

hs.expose

Keyboard-driven expose replacement/enhancement

hs.fnutils

Functional programming utility functions

hs.fs

Access/inspect the filesystem

hs.fs.volume

Interact with OS X filesystem volumes

hs.fs.xattr

Get and manipulate extended attributes for files and directories

hs.geometry

Utility object to represent points, sizes and rects in a bidimensional plane

hs.grid

Move/resize windows within a grid

hs.hash

Various hashing algorithms

hs.hid

HID interface for Hammerspoon, controls and queries caps lock state

hs.hid.led

HID LED interface for Hammerspoon, controls the state of keyboard LEDs

hs.hints

Switch focus with a transient per-application keyboard shortcut

hs.host

Inspect information about the machine Hammerspoon is running on

hs.host.locale

Retrieve information about the user's Language and Region settings.

hs.hotkey

Create and manage global keyboard shortcuts

hs.hotkey.modal

Create/manage modal keyboard shortcut environments

hs.http

Perform HTTP requests

hs.httpserver

Simple HTTP server

hs.httpserver.hsminweb

Minimalist Web Server for Hammerspoon

hs.httpserver.hsminweb.cgilua

Provides support functions in the cgilua module for Hammerspoon Minimal Web Server Lua templates.

hs.httpserver.hsminweb.cgilua.lp

Support functions for the CGILua compatibility module for including and translating Lua template pages into Lua code for execution within the Hammerspoon environment to provide dynamic content for http requests.

hs.httpserver.hsminweb.cgilua.urlcode

Support functions for the CGILua compatibility module for encoding and decoding URL components in accordance with RFC 3986.

hs.image

A module for capturing and manipulating image objects from other modules for use with hs.drawing.

hs.inspect

Produce human-readable representations of Lua variables (particularly tables)

hs.ipc

Provides Hammerspoon with the ability to create both local and remote message ports for inter-process communication.

hs.itunes

Controls for iTunes music player

hs.javascript

Execute JavaScript code

hs.json

JSON encoding and decoding

hs.keycodes

Convert between key-strings and key-codes. Also provides functionality for querying and changing keyboard layouts.

hs.layout

Window layout manager

hs.location

Determine the machine's location and useful information about that location

hs.location.geocoder

Converts between GPS coordinates and more user friendly representations like an address or points of interest.

hs.logger

Simple logger for debugging purposes

hs.math

Various helpful mathematical functions

hs.menubar

Create and manage menubar icons

hs.messages

Send messages via iMessage and SMS Relay (note, SMS Relay requires OS X 10.10 and an established SMS Relay pairing between your Mac and an iPhone running iOS8)

hs.midi

MIDI Extension for Hammerspoon.

hs.milight

Simple controls for the MiLight LED WiFi bridge (also known as LimitlessLED and EasyBulb)

hs.mjomatic

tmuxomatic-like window management

hs.mouse

Inspect/manipulate the position of the mouse pointer

hs.network

This module provides functions for inquiring about and monitoring changes to the network.

hs.network.configuration

This sub-module provides access to the current location set configuration settings in the system's dynamic store.

hs.network.host

This sub-module provides functions for acquiring host information, such as hostnames, addresses, and reachability.

hs.network.ping

This module provides a basic ping function which can test host availability. Ping is a network diagnostic tool commonly found in most operating systems which can be used to test if a route to a specified host exists and if that host is responding to network traffic.

hs.network.ping.echoRequest

Provides lower-level access to the ICMP Echo Request infrastructure used by the hs.network.ping module. In general, you should not need to use this module directly unless you have specific requirements not met by the hs.network.ping module and the hs.network.ping object methods.

hs.network.reachability

This sub-module can be used to determine the reachability of a target host. A remote host is considered reachable when a data packet, sent by an application into the network stack, can leave the local device. Reachability does not guarantee that the data packet will actually be received by the host.

hs.noises

Contains two low latency audio recognizers for different mouth noises, which can be used to trigger actions like scrolling or clicking.

hs.notify

This module allows you to create on screen notifications in the User Notification Center located at the right of the users screen.

hs.osascript

Execute Open Scripting Architecture (OSA) code - AppleScript and JavaScript

hs.pasteboard

Inspect/manipulate pasteboards (more commonly called clipboards). Both the system default pasteboard and custom named pasteboards can be interacted with.

hs.pasteboard.watcher

Watch for Pasteboard Changes.

hs.pathwatcher

Watch paths recursively for changes

hs.plist

Read and write Property List files

hs.razer

Razer device support.

hs.redshift

Inverts and/or lowers the color temperature of the screen(s) on a schedule, for a more pleasant experience at night

hs.screen

Manipulate screens (i.e. monitors)

hs.screen.watcher

Watch for screen layout changes

hs.serial

Communicate with external devices through a serial port (most commonly RS-232).

hs.settings

Serialize simple Lua variables across Hammerspoon launches

hs.sharing

Share items with the macOS Sharing Services under the control of Hammerspoon.

hs.shortcuts

List and run shortcuts from the Shortcuts app

hs.socket

Talk to custom protocols using asynchronous TCP sockets.

hs.socket.udp

Talk to custom protocols using asynchronous UDP sockets.

hs.sound

Load/play/manipulate sound files

hs.spaces

This module provides some basic functions for controlling macOS Spaces.

hs.spaces.watcher

Watches for the current Space being changed

hs.speech

This module provides access to the Speech Synthesizer component of OS X.

hs.speech.listener

This module provides access to the Speech Recognizer component of OS X.

hs.spoons

Utility and management functions for Spoons

hs.spotify

Controls for Spotify music player

hs.spotlight

This module allows Hammerspoon to preform Spotlight metadata queries.

hs.spotlight.group

This sub-module is used to access results to a spotlightObject query which have been grouped by one or more attribute values.

hs.spotlight.item

This sub-module is used to access the individual results of a spotlightObject or a spotlightGroupObject.

hs.sqlite3

Interact with SQLite databases

hs.streamdeck

Configure/control an Elgato Stream Deck.

hs.styledtext

This module adds support for controlling the style of the text in Hammerspoon.

hs.tabs

Place the windows of an application into tabs drawn on its titlebar

hs.tangent

Tangent Control Surface Extension

hs.task

Execute processes in the background and capture their output

hs.timer

Execute functions with various timing rules

hs.timer.delayed

Specialized timer objects to coalesce processing of unpredictable asynchronous events into a single callback

hs.uielement

A generalized framework for working with OSX UI elements

hs.uielement.watcher

Watch for events on certain UI elements (including windows and applications)

hs.urlevent

Allows Hammerspoon to respond to URLs

hs.usb

Inspect USB devices

hs.usb.watcher

Watch for USB device connection/disconnection events

hs.utf8

Functions providing basic support for UTF-8 encodings

hs.vox

Controls for VOX music player

hs.watchable

A minimalistic Key-Value-Observer framework for Lua.

hs.websocket

Simple websocket client.

hs.webview

Display web content in a window from Hammerspoon

hs.webview.datastore

Provides methods to list and purge the various types of data used by websites visited with hs.webview.

hs.webview.toolbar

Create and manipulate toolbars which can be attached to the Hammerspoon console or hs.webview objects.

hs.webview.usercontent

This module provides support for injecting custom JavaScript user content into your webviews and for JavaScript to post messages back to Hammerspoon.

hs.wifi

Inspect WiFi networks

hs.wifi.watcher

Watch for changes to the associated wifi network

hs.window

Inspect/manipulate windows

hs.window.filter

Filter windows by application, title, location on screen and more, and easily subscribe to events on these windows

hs.window.highlight

Highlight the focused window

hs.window.layout

WARNING: EXPERIMENTAL MODULE. DO NOT USE IN PRODUCTION.

hs.window.switcher

Window-based cmd-tab replacement

hs.window.tiling

WARNING: EXPERIMENTAL MODULE. DO NOT USE IN PRODUCTION.