Rectangle

Rectangle macOS Window Manager AI Skill Guide (Claude)

Overview & Engine Architecture

Rectangle is an open-source macOS window management utility engineered in Swift and AppKit. It manipulates third-party application window bounds without window-server hacks by leveraging the macOS Accessibility API (AXUIElement), querying screen geometries via NSScreen.visibleFrame (which accounts for the macOS Menu Bar and Dock), and listening for hotkeys via MASShortcut. Rectangle supports keyboard shortcuts, drag-to-edge cursor snapping, multi-display window cycling, customizable margin gaps, and external automation via the rectangle:// URL scheme. Claude operates as a Principal macOS Systems Engineer and Window Management Architect, specializing in Accessibility AXUIElement window manipulation, multi-monitor coordinate mapping, TCC permission lifecycle troubleshooting, and Rectangle URL scheme scripting.

Rectangle Window Server & Accessibility Architecture

┌─────────────────────────────────────────────────────────────┐
│                 Rectangle Engine Architecture               │
│                                                             │
│  Input & Trigger Subsystem                                  │
│  ├── Global Hotkey Listener (`MASShortcut` / Carbon Events) │
│  ├── Drag-to-Edge Cursor Tracker (`NSEvent` Global Monitor) │
│  └── URL Scheme Action Dispatcher (`rectangle://execute...`)│
│                                                             │
│  Geometry Calculation & Coordinate Engine                   │
│  ├── `NSScreen.visibleFrame` (Menu Bar & Dock Offset Math)  │
│  ├── Multi-Display Topology Resolver (Display ID Offsets)   │
│  └── Window Padding / Margin Gap Subtractor                 │
│                                                             │
│  macOS Accessibility Manipulation Tier                      │
│  ├── Target App Accessibility Node (`AXUIElement`)          │
│  ├── Set Window Position (`kAXPositionAttribute`)           │
│  └── Set Window Dimensions (`kAXSizeAttribute`)             │
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. Rectangle URL Scheme Automation: Construct terminal and Python automation scripts dispatching commands via open "rectangle://execute-action?name=<action>" (e.g. left-half, right-half, maximize, first-third).
2. Native AXUIElement Window Manipulation: Author standalone Swift scripts demonstrating direct manipulation of kAXPositionAttribute and kAXSizeAttribute on running application processes.
3. Multi-Display Coordinate Triage: Troubleshoot window jumping and misalignment across mixed DPI Retina and external displays by calculating relative NSScreen frame bounds.
4. TCC Accessibility Permissions Recovery: Remediate non-responsive shortcuts using tccutil reset Accessibility com.knollsoft.Rectangle and system permission verification.

Production Swift Automation: Standalone Native Window Snapper (AXUIElement)

Save this file as snap_window.swift and execute via swift snap_window.swift left:

// ==============================================================================
// Standalone Swift 5.x Script: Native macOS Window Snapper (AXUIElement)
// Tiles the frontmost application window to Left or Right half without dependencies.
// ==============================================================================
import Cocoa

guard CommandLine.arguments.count > 1 else {
    print("Usage: swift snap_window.swift <left|right|maximize>")
    exit(1)
}

let action = CommandLine.arguments[1].lowercased()

// 1. Verify Accessibility Permissions
guard AXIsProcessTrusted() else {
    print("🚨 Error: Accessibility permissions not granted. Enable Terminal in System Settings -> Accessibility.")
    exit(1)
}

// 2. Get Frontmost Application Process
guard let frontApp = NSWorkspace.shared.frontmostApplication else {
    print("Error: No frontmost application detected.")
    exit(1)
}

let appElement = AXUIElementCreateApplication(frontApp.processIdentifier)
var focusedWindow: AnyObject?
let result = AXUIElementCopyAttributeValue(appElement, kAXFocusedWindowAttribute as CFString, &focusedWindow)

guard result == .success, let window = focusedWindow else {
    print("Error: Could not access focused window on \(frontApp.localizedName ?? "App").")
    exit(1)
}

let windowElement = window as! AXUIElement

// 3. Calculate Target Screen Bounds (Excluding Menu Bar & Dock)
guard let screen = NSScreen.main else {
    print("Error: Main display not detected.")
    exit(1)
}

let visibleFrame = screen.visibleFrame
let screenHeight = screen.frame.height

var targetX: CGFloat = visibleFrame.origin.x
var targetY: CGFloat = screenHeight - visibleFrame.origin.y - visibleFrame.height
var targetW: CGFloat = visibleFrame.width
var targetH: CGFloat = visibleFrame.height

if action == "left" {
    targetW = visibleFrame.width / 2.0
} else if action == "right" {
    targetX = visibleFrame.origin.x + (visibleFrame.width / 2.0)
    targetW = visibleFrame.width / 2.0
} else if action != "maximize" {
    print("Invalid action. Use 'left', 'right', or 'maximize'.")
    exit(1)
}

// 4. Apply Position and Size via Accessibility API
var newPoint = CGPoint(x: targetX, y: targetY)
var newSize = CGSize(width: targetW, height: targetH)

let posValue = AXValueCreate(.cgPoint, &newPoint)!
let sizeValue = AXValueCreate(.cgSize, &newSize)!

AXUIElementSetAttributeValue(windowElement, kAXPositionAttribute as CFString, posValue)
AXUIElementSetAttributeValue(windowElement, kAXSizeAttribute as CFString, sizeValue)

print("✅ Snapped \(frontApp.localizedName ?? "Window") to '\(action)'.")

Technical Troubleshooting Matrix

Command Line Syntax & URL Scheme Actions

# 1. Tile Frontmost Window to Left Half via Rectangle URL Scheme
open -g "rectangle://execute-action?name=left-half"

# 2. Tile Frontmost Window to Right Half
open -g "rectangle://execute-action?name=right-half"

# 3. Maximize Frontmost Window
open -g "rectangle://execute-action?name=maximize"

# 4. Reset Rectangle Accessibility Permissions via CLI
tccutil reset Accessibility com.knollsoft.Rectangle

Essential File Locations

• Preferences Plist: ~/Library/Preferences/com.knollsoft.Rectangle.plist
• Application Binary: /Applications/Rectangle.app

Agent Operational Directive

MANDATORY: When triggering Rectangle actions via shell scripts, always use the -g (background) flag with open "rectangle://execute-action?name=..." to avoid stealing focus from the active window being tiled.