git404hub

what is hammerspoon fr?

hammerspoon/hammerspoon — explained in plain English

Analysis updated 2026-06-24

15,406Objective-CAudience · developerComplexity · 3/5Setup · easy

tl;dr

macOS desktop automation tool scripted in Lua. Gives programmatic control over windows, keyboard shortcuts, app launching, and system events on your Mac.

vibe map

mindmap
  root((hammerspoon))
    Inputs
      Lua config
      Keyboard events
      System triggers
    Outputs
      Window actions
      Notifications
      App launches
    Use Cases
      Window tiling
      Custom hotkeys
      Context aware macros
    Tech Stack
      Lua
      Objective-C
      macOS APIs

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

what do people make with this?

VIBE 1

Write a Lua script that auto-tiles windows when you connect an external monitor

VIBE 2

Bind a global hotkey to launch a specific workspace of apps and windows

VIBE 3

Trigger actions automatically when a particular application becomes active

what's the stack?

LuaObjective-CmacOS

how it stacks up fr

hammerspoon/hammerspoonjdg/mbprogresshudkeycastr/keycastr
Stars15,40615,95114,815
LanguageObjective-CObjective-CObjective-C
Setup difficultyeasyeasyeasy
Complexity3/52/51/5
Audiencedeveloperdevelopergeneral

Figures from each repo's GitHub metadata at analysis time.

how do i run it?

Difficulty · easy time til it works · 30min

macOS only, you must write a Lua config file before it does anything.

in plain english

Hammerspoon is a macOS desktop automation tool that acts as a bridge between the operating system and a scripting engine powered by Lua, a lightweight, easy-to-learn programming language. It gives you programmatic control over many aspects of your Mac: window management, keyboard shortcuts, application launching, system events, notifications, and more. Out of the box, Hammerspoon does nothing on its own. To use it, you create a configuration file at a specific location on your Mac and fill it with Lua scripts that define your automations. The tool exposes macOS system functionality through a set of built-in extensions, each covering a different area of the system. You might write a script to automatically resize and position windows when you connect a monitor, trigger actions when specific applications become active, or set up custom key combinations that do anything you can describe in code. Installation is straightforward, download the app and drag it to Applications, or install it via Homebrew with a single command. Hammerspoon started as a fork of a similar project called Mjolnir, but with the goal of providing a more integrated and complete experience rather than relying on external packages. A getting started guide, full API documentation, and a collection of sample configurations contributed by users are all available to help new users build their first automations.

prompts (copy fr)

prompt 1
Write a Hammerspoon Lua config that snaps the focused window to the left half of the screen with cmd-alt-left
prompt 2
Set up Hammerspoon to launch Safari and Slack in specific positions when I connect my work monitor
prompt 3
Build a Hammerspoon hotkey that toggles dark mode and changes wallpaper
prompt 4
Show me how to detect when Zoom is in a meeting and mute Slack notifications via Hammerspoon
prompt 5
Convert this Karabiner config to equivalent Hammerspoon Lua bindings

Frequently asked questions

what is hammerspoon fr?

macOS desktop automation tool scripted in Lua. Gives programmatic control over windows, keyboard shortcuts, app launching, and system events on your Mac.

What language is hammerspoon written in?

Mainly Objective-C. The stack also includes Lua, Objective-C, macOS.

How hard is hammerspoon to set up?

Setup difficulty is rated easy, with roughly 30min to a first successful run.

Who is hammerspoon for?

Mainly developer.

peek the repo → explain another one

This repo across BitVibe Labs

double-check against the repo, no cap.