Building a Dynamic macOS Window Manager for AI Agents

macOS developers and power users have long relied on window management tools like Raycast (Pro tier), Magnet, and Rectangle Pro to tile and organize desktop windows. These tools work exceptionally well for manual keyboard shortcuts, but they share two fundamental limitations:

1. No AI Agent Integration: While tools like Raycast offer powerful AI chat features, none of them expose a programmable API or CLI that an autonomous AI agent can invoke to rearrange windows during automated workflows.
2. Static Layouts: Most use hardcoded pixel coordinates or predefined grid presets that break across different display resolutions — a MacBook Retina 13" (1440x900) layout completely misaligns on a 4K ultrawide (3840x2160).

To solve both problems, I built Window Manager — a free, open-source, resolution-independent macOS window layout skill powered by Python and AppleScript. It is designed from the ground up for AI agent computer use, while also being instantly usable by any developer from the terminal. In this post, we'll explore its architecture, dynamic solver algorithm, compact layout DSL, and how it handles OS-level window sizing quirks.

🎬 Demo Showcase

1. Architecture of the Dynamic Window Layout Engine

The layout engine eliminates hardcoded pixel values entirely by calculating positions relative to the active display bounds at runtime.

┌─────────────────────────────────────────────────────────────┐
│                    Active macOS Display                     │
├──────────────────────────────┬──────────────────────────────┤
│                              │       App 2 (Top 50%)        │
│     App 1 (100% Height)      ├──────────────────────────────┤
│                              │      App 3 (Bottom 50%)      │
└──────────────────────────────┴──────────────────────────────┘

Screen Bounds Detection via AppleScript

Before arranging any windows, the layout engine queries the desktop bounds directly from Finder via System Events:

def get_screen_bounds():
    script = """
    tell application "Finder"
        set b to bounds of window of desktop
        return (item 3 of b as string) & "," & (item 4 of b as string)
    end tell
    """
    out = run_applescript(script)
    parts = out.split(",")
    return int(parts[0].strip()), int(parts[1].strip())

This returns the exact screen width (sw) and screen height (sh), allowing the engine to adapt dynamically whether you are on a laptop screen or an ultrawide display.

2. Dynamic Column Splitting & Row Stacking Algorithm

The solver organizes windows using a 2D column and row grid structure:

• Columns: Divided equally across screen width (target_w = round(rem_sw / rem_cols)).
• Rows: When a column contains 2 applications, vertical height is split 50/50 (usable_h / 2).

def apply_column_layout(columns, sw: int, sh: int, top_y: int = 39):
    num_cols = len(columns)
    if num_cols == 0:
        return

    usable_h = sh - top_y
    current_x = 0
    rem_sw = sw

    for c_idx, col_apps in enumerate(columns):
        if not col_apps:
            continue
        rem_cols = num_cols - c_idx
        target_w = round(rem_sw / rem_cols)
        num_in_col = min(len(col_apps), 2)

        if num_in_col == 1:
            app = col_apps[0]
            tx, ty, actual_w, actual_h = set_window_bounds(
                app, current_x, top_y, target_w, usable_h
            )
            used_w = max(target_w, actual_w)
            current_x += used_w
            rem_sw -= used_w
        else:
            app_top = col_apps[0]
            app_bot = col_apps[1]
            half_h = round(usable_h / 2)

            tx, ty, tw, th = set_window_bounds(
                app_top, current_x, top_y, target_w, half_h
            )
            used_w = max(target_w, tw)
            bot_y = ty + th
            bot_h = (top_y + usable_h) - bot_y

            set_window_bounds(app_bot, current_x, bot_y, used_w, bot_h)
            current_x += used_w
            rem_sw -= used_w

3. Compact Layout DSL & Command Examples

The skill exposes a concise domain-specific language (DSL) using | for column separation and , for vertical app stacking within a column:

Case 1: IDE Left | Antigravity & Spotify Stacked Right

python3 scripts/layout_manager.py \
  --mode split --layout "ide|antigravity,spotify"

Case 2: Antigravity & Spotify Stacked Left | IDE Right

python3 scripts/layout_manager.py \
  --mode split --layout "antigravity,spotify|ide"

Case 3: 3-Column Side-by-Side Split

python3 scripts/layout_manager.py \
  --mode split --layout "ide|antigravity|spotify"

Case 4: 2-Column Side-by-Side Split

python3 scripts/layout_manager.py \
  --mode split --layout "ide|antigravity"

4. Key Takeaways

1. Resolution Independence: Always query display bounds at runtime via AppleScript instead of hardcoding pixel coordinates.
2. AI Agent Integration: Providing simple column string layouts ("ide|antigravity,spotify") makes it effortless for LLM agents to manage window state autonomously.
3. Clean Developer Workflow: Replaces manual window alignment with a single CLI command or agent action across any display setup.

Explore more software engineering tools and projects on my projects page.