Logo for the website. A blue P-like symbol and a red K-like symbol. Pushkar Kurhekar
•
3 min read

Window Controls Plugin

Table of Contents

Overview

Window Controls Plugin is a macOS Elgato Stream Deck plugin for moving windows between displays using a key-driven app/window selection flow. It is designed for multi-monitor workflows where repetitive window movement needs to be fast and consistent.

Features

  • App list navigation directly on Elgato Stream Deck keys
  • Window-level targeting for each selected app
  • Directional movement (left / right) across displays
  • Back navigation to return to app list state
  • Dynamic key icons with app glyphs and control badges

Runtime Model

The plugin maintains a compact state store that tracks:

  • current mode (list vs direction)
  • selected app path and app name
  • selected window identity
  • list and direction page indexes
  • refresh timestamp and last move summary

This state machine keeps key rendering deterministic while moving between selection and movement modes.

Technical Architecture

  • Plugin runtime (Node.js 20): handles Elgato Stream Deck events and action routing.
  • Native backend (System.node): macOS window/screen access via windowManager APIs.
  • Domain layer:
    • app discovery/normalization
    • display mapping and work-area calculations
    • window move engine with relative bounds preservation
  • Renderer layer: Python-powered icon generation with caching for app/control tiles.

Movement Logic

Window movement is display-aware:

  1. Resolve source and target displays.
  2. Convert current bounds to relative position/size.
  3. Reconstruct target bounds while preserving visual placement.
  4. Clamp to valid target work area.
  5. Apply bounds through backend setWindowBounds.

For repeat moves, remembered bounds per window/display pair help keep round-trip positioning consistent.

Requirements

  • macOS
  • Elgato Stream Deck 6.5+
  • Node.js 20+
  • Native backend available at:
    • com.pshkrh.window-controls.sdPlugin/bin/addon/mac/System.node

Local Development

./scripts/install-window-controls.sh
npm test

The install script copies backend/runtime assets into the Elgato Stream Deck plugin directory for local iteration.

Usage

  1. Open the Window Controls folder on Elgato Stream Deck.
  2. Select an app.
  3. Select a window from that app.
  4. Move it left or right using directional keys.
  5. Press the return arrow to go back to app selection.