https://github.com/Hammerspoon/hammerspoon

Staggeringly powerful macOS desktop automation with Lua
https://github.com/Hammerspoon/hammerspoon

automation hammerspoon irc lua macos mjolnir objective-c osx

Last synced: about 1 month ago
JSON representation

Staggeringly powerful macOS desktop automation with Lua

• Host: GitHub
• URL: https://github.com/Hammerspoon/hammerspoon
• Owner: Hammerspoon
• License: mit
• Created: 2014-10-08T19:24:44.000Z (over 10 years ago)
• Default Branch: master
• Last Pushed: 2024-09-19T21:54:28.000Z (7 months ago)
• Last Synced: 2024-10-29T12:02:35.358Z (6 months ago)
• Topics: automation, hammerspoon, irc, lua, macos, mjolnir, objective-c, osx
• Language: Objective-C
• Homepage: http://www.hammerspoon.org
• Size: 155 MB
• Stars: 12,044
• Watchers: 122
• Forks: 584
• Open Issues: 588
• Metadata Files:
  • Readme: README.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

• awesome - Hammerspoon/hammerspoon - Staggeringly powerful macOS desktop automation with Lua (Objective-C)
• Metal-Guide - Hammerspoon
• awesome-starred-test - Hammerspoon/hammerspoon - Staggeringly powerful macOS desktop automation with Lua (Objective-C)
• open-source-mac-os-apps - Hammerspoon - Staggeringly powerful macOS desktop automation with Lua. ![lua_icon] ![objective_c_icon] (Applications / Window Management)
• Xcode-Guide - Hammerspoon
• macOS-iOS-iPadOS-Guide - Hammerspoon
• CoreML-Guide - Hammerspoon
• awesome-web-dev - hammerspoon
• StarryDivineSky - Hammerspoon/hammerspoon
• open-source-mac-os-apps - Hammerspoon - Staggeringly powerful macOS desktop automation with Lua.</summary><p><b>Languages:</b> ![lua_icon] ![objective_c_icon] <br></p></details> (Applications / 🪟 Window Management (11))
• my-awesome - Hammerspoon/hammerspoon - c,osx pushed_at:2025-02 star:12.8k fork:0.6k Staggeringly powerful macOS desktop automation with Lua (Objective-C)
• definitive-opensource - Hammerspoon

README

        
# Hammerspoon

[![CI](https://github.com/Hammerspoon/hammerspoon/workflows/CI/badge.svg)](https://github.com/Hammerspoon/hammerspoon/actions?query=workflow%3ACI)

[![codecov.io](https://codecov.io/github/Hammerspoon/hammerspoon/coverage.svg?branch=master)](https://codecov.io/github/Hammerspoon/hammerspoon?branch=master)

[![Downloads current release](https://img.shields.io/github/downloads/Hammerspoon/hammerspoon/latest/total.svg)](https://github.com/Hammerspoon/hammerspoon/releases)

[![Downloads all releases](https://img.shields.io/github/downloads/Hammerspoon/hammerspoon/total.svg?maxAge=2592000)](https://github.com/Hammerspoon/hammerspoon/releases)

[![Latest tag](https://img.shields.io/github/tag/Hammerspoon/hammerspoon.svg)](https://github.com/Hammerspoon/hammerspoon/tags)

[![Latest release](https://img.shields.io/github/release/Hammerspoon/hammerspoon.svg)](https://github.com/Hammerspoon/hammerspoon/releases/latest)

Discord: [Click to join](https://discord.gg/vxchqkRbkR)

## What is Hammerspoon?

This is a tool for powerful automation of OS X. At its core, Hammerspoon is just a bridge between the operating system and a Lua scripting engine.

What gives Hammerspoon its power is a set of extensions that expose specific pieces of system functionality, to the user. With these, you can write Lua scripts to control many aspects of your OS X environment.

## How do I install it?

### Manually

 * Download the [latest release](https://github.com/Hammerspoon/hammerspoon/releases/latest)

 * Drag `Hammerspoon.app` from your `Downloads` folder to `Applications`

### Homebrew

  * `brew install hammerspoon --cask`

## What next?

Out of the box, Hammerspoon does nothing - you will need to create `~/.hammerspoon/init.lua` and fill it with useful code. There are several resources which can help you:

 * [Getting Started Guide](https://www.hammerspoon.org/go/)

 * [API docs](https://www.hammerspoon.org/docs/)

 * [FAQ](https://www.hammerspoon.org/faq/)

 * [Sample Configurations](https://github.com/Hammerspoon/hammerspoon/wiki/Sample-Configurations) supplied by various users

 * [Contribution Guide](https://github.com/Hammerspoon/hammerspoon/blob/master/CONTRIBUTING.md) for developers looking to get involved

 * An IRC channel for general chat/support/development (#hammerspoon on Libera)

 * [Google Group](https://groups.google.com/forum/#!forum/hammerspoon/) for support

## What is the history of the project?

Hammerspoon is a fork of [Mjolnir](https://github.com/sdegutis/mjolnir) by Steven Degutis. Mjolnir aims to be a very minimal application, with its extensions hosted externally and managed using a Lua package manager. We wanted to provide a more integrated experience.

## What is the future of the project?

Our intentions for Hammerspoon broadly fall into these categories:

 * Ever wider coverage of system APIs in Extensions

 * Tighter integration between extensions

 * Smoother user experience