Skip to content
Shoji

Overview

You will learn

  • How to react to window events with hooks
  • How to compose layouts with combinators
  • How to create custom actions and IPC commands
  • How to build full extensions with the engine pipeline

This section teaches you to extend Shoji beyond its built-in features. By the end, you’ll be able to automate window behavior, compose purpose-specific layouts, add custom keybindings, and build extensions that participate in Shoji’s engine pipeline.

Prerequisites

Before starting:

  1. Shoji installed and running (Installation)
  2. Basic Lua knowledge (variables, functions, tables)
  3. A text editor for writing Lua files

How these guides connect

Guides 1 and 2 are independent entry points. Start with whichever matches your interest:

  • Interested in automating behavior? Start with Guide 1 (Hooks)
  • Interested in layout composition? Start with Guide 2 (Combinators)

Guides 3 and 4 build on earlier material:

Guide 1: Hooks ─────────┐
                         │
Guide 2: Combinators     │
                         ↓
           Guide 3: Actions & commands
                         ↓
           Guide 4: Extensions

The guides

Guide 1: Reacting to events with hooks

Respond to window events and manipulate state. You’ll build a window activity monitor that logs events, shows app-specific alerts, and auto-floats dialog-sized windows.

What you’ll build: A hook-based system that auto-floats dialogs and monitors window activity.

Start Guide 1 →

Guide 2: Composing layouts with combinators

Build purpose-specific layouts by combining existing ones. You’ll create an adaptive layout that switches between Monocle and Tall based on window count, and an IDE layout using Partition.

What you’ll build: Two composed layouts using IfMax and Partition.

Familiarity with: Built-in layouts (Tall, Monocle, Column).

Start Guide 2 →

Guide 3: Custom actions and commands

Add new keybindings and external control points. You’ll build a “focus or launch” action, workspace presets, and a custom IPC command.

What you’ll build: Custom actions bound to hotkeys and an IPC command callable from shell scripts.

Requires: Guide 1.

Start Guide 3 →

Guide 4: Building an extension

Build a complete extension that participates in Shoji’s engine pipeline. You’ll create a display profiles extension that automatically reconfigures layouts when you dock or undock your laptop.

What you’ll build: A full extension with engine event handlers, intent interception, file persistence, and proper teardown.

Requires: Guides 1 and 3.

Start Guide 4 →

Reference material

After completing the guides, use these references:

Testing your work

Throughout these guides, you’ll test changes in Hammerspoon:

  1. Save your configuration file
  2. Reload Hammerspoon from the menu bar (Reload config) or run hs.reload() in the Hammerspoon console
  3. Check the console for output and errors (menu bar > Console)

Keep the console open while developing to catch errors early.