Phoenix

Who It's For

Phoenix is for developers who want JavaScript-scriptable window management with zero overhead. Where Hammerspoon is a full macOS automation framework with APIs for audio, network, USB, drawing, and more, Phoenix is single-purpose: give it a ~/.config/phoenix/phoenix.js file and it executes your window management logic and nothing else. If you're comfortable with JavaScript and want total control without committing to Lua or a large framework, Phoenix is the leanest scriptable option on this list.

How It Works

Phoenix exposes a minimal JavaScript API: Window, App, Screen, Key, Event, and Timer. With these primitives you can query any open window, read its frame geometry, resize and reposition it, bind global hotkeys, and react to focus events. The config file is loaded at startup and reloaded on demand with a shortcut. Phoenix ships TypeScript type definitions, so editors like VS Code provide autocompletion for the entire API.

// ~/.config/phoenix/phoenix.js
const hyper = ['ctrl', 'alt', 'cmd'];

Key.on('h', hyper, () => {
  const win = Window.focused();
  if (!win) return;
  const s = win.screen().flippedVisibleFrame();
  win.setFrame({ x: s.x, y: s.y, width: s.width / 2, height: s.height });
});

Key.on('l', hyper, () => {
  const win = Window.focused();
  if (!win) return;
  const s = win.screen().flippedVisibleFrame();
  win.setFrame({ x: s.x + s.width / 2, y: s.y, width: s.width / 2, height: s.height });
});

Compared to Similar Tools

Compared to Hammerspoon, Phoenix is narrower (window management only) but simpler and uses JavaScript instead of Lua. Hammerspoon is the right choice if you also want to automate app launching, system events, clipboard, or network triggers. Phoenix is the right choice if window management is your only goal and you want JavaScript. Compared to skhd, Phoenix handles its own hotkey binding internally, while skhd is a standalone daemon designed to pair with other tools like yabai.

Requirements

• macOS 10.12 or later
• Accessibility permission required
• Free and open-source (MIT license)

Getting Started

brew install --cask phoenix
# Launch Phoenix, grant Accessibility permission
# Create ~/.config/phoenix/phoenix.js

Full API documentation is at github.com/kasper/phoenix. The README includes a comprehensive getting-started example.