Window Management

SuperCmd includes a comprehensive window management system that lets you position and resize windows using keyboard shortcuts, similar to Rectangle or Magnet.

Overview

Window management in SuperCmd provides:

45+ layout presets (halves, thirds, quarters, sixths, center, fill)
Fine-tuning controls (resize by 10%, move in increments)
Auto-organize multiple windows in grid layouts
Visual preview before applying layouts
Keyboard-first workflow

Window management uses the node-window-manager library to interact with native window APIs (src/main/window-manager-worker.ts).

Quick Start

Open Window Manager

Press SuperCmd hotkey, then search for “Window Management” or use the dedicated hotkey (configure in Settings).

Select Layout

Browse layout presets with arrow keys or type to search (e.g., “left”, “center”).

Preview Layout

Press Shift+Enter to preview the layout without closing the panel.

Apply Layout

Press Enter to apply the layout and close the panel.

Layout Presets

Halves & Quarters

Halves
Quarters

Left - Left half of screen
Right - Right half
Top - Top half
Bottom - Bottom half

Thirds

Vertical Thirds:

First Third - Left third
Center Third - Middle third
Last Third - Right third

Two-Thirds:

First Two Thirds - Left 2/3
Center Two Thirds - Middle 2/3
Last Two Thirds - Right 2/3

Fourths

Vertical Fourths:

First Fourth - Leftmost quarter
Second Fourth - Left-center quarter
Third Fourth - Right-center quarter
Last Fourth - Rightmost quarter

Three-Fourths:

First Three Fourths - Left 3/4
Center Three Fourths - Middle 3/4
Last Three Fourths - Right 3/4

Sixths (2×3 Grid)

Top Row:

Top Left Sixth
Top Center Sixth
Top Right Sixth

Bottom Row:

Bottom Left Sixth
Bottom Center Sixth
Bottom Right Sixth

Special Layouts

Center

Center window at 60% screen size

Almost Maximize

Center at 80% (leaves margins)

Maximize

Fill entire screen

Auto-Organize

Arrange up to 4 windows in smart grid

Fine-Tuning Controls

Adjust window size and position incrementally:

Size Adjustments (10% Steps)

Action	Shortcut Preset
Increase Size	`increase-size-10`
Decrease Size	`decrease-size-10`
Expand Left	`increase-left-10`
Expand Right	`increase-right-10`
Expand Top	`increase-top-10`
Expand Bottom	`increase-bottom-10`
Shrink Left	`decrease-left-10`
Shrink Right	`decrease-right-10`
Shrink Top	`decrease-top-10`
Shrink Bottom	`decrease-bottom-10`

Position Adjustments

Action	Shortcut Preset
Move Up	`move-up-10`
Move Down	`move-down-10`
Move Left	`move-left-10`
Move Right	`move-right-10`

Fine-tuning presets require Shift+Enter to prevent accidental activation. They adjust the active window by 10% of its current size.

Auto-Organize

Arrange multiple windows automatically:

How It Works

Detects all windows on current screen
Filters out system windows and minimized windows
Sorts by position (top to bottom, left to right)
Arranges up to 4 windows in optimal grid

Layout Strategies (src/renderer/src/WindowManagerPanel.tsx:1027)

// 2 windows: Split vertically (50/50)
if (windows.length === 2) {
  splitVertical(area);
}

// 3 windows: Left half + right split
if (windows.length === 3) {
  buildAutoFill3Layout();
}

// 4 windows: 2×2 grid
if (windows.length === 4) {
  buildAutoFill4Layout();
}

Auto-organize is smart about window sizes. It preserves aspect ratios and minimum dimensions to keep windows usable.

Window Detection

Manageable Windows

SuperCmd only manages windows that meet criteria (src/renderer/src/WindowManagerPanel.tsx:518):

function isManageableWindow(win: ManagedWindow): boolean {
  // Must have valid ID and bounds
  // Not a SuperCmd window (prevents self-management)
  // Minimum size: 120×60 pixels
  // Must be positionable and resizable
  // Not minimized or hidden
}

Target Window Selection

When applying a preset, SuperCmd selects the target window:

Explicitly targeted - From Window Management context
Active window - Frontmost application window
Nearest window - Closest to layout region center (for auto-organize)

Visual Preview

Preview layouts before applying (src/renderer/src/WindowManagerPanel.tsx:1331):

Preview Mode

Navigate to a preset
Press Shift+Enter
Window outline appears showing future position
Press Enter to apply or Escape to cancel

Preview mode temporarily moves windows. Use sparingly on critical workflows.

Keyboard Shortcuts

Assign custom shortcuts to presets:

Setting Shortcuts

Settings > Hotkeys
Find “Window Management” section
Click preset (e.g., “Left Half”)
Press desired key combination
Shortcut saves automatically

Preset Command IDs (src/renderer/src/WindowManagerPanel.tsx:84)

const WINDOW_MANAGEMENT_PRESET_COMMANDS = [
  { commandId: 'system-window-management-left', presetId: 'left' },
  { commandId: 'system-window-management-right', presetId: 'right' },
  { commandId: 'system-window-management-center', presetId: 'center' },
  // ... 40+ more
];

Common shortcuts:

Ctrl+Cmd+Left - Left half
Ctrl+Cmd+Right - Right half
Ctrl+Cmd+F - Fill screen

Multi-Monitor Support

SuperCmd handles multi-monitor setups:

Screen Detection

Layouts apply to the screen containing the target window:

// Screen metrics (src/renderer/src/WindowManagerPanel.tsx:530)
function getHostMetrics(): ScreenArea {
  return {
    left: screen.availLeft,      // Accounts for menu bar
    top: screen.availTop,
    width: screen.availWidth,
    height: screen.availHeight
  };
}

Work Area Calculation

Respects menu bars, docks, and taskbars:

macOS: Excludes menu bar (top) and Dock
Windows: Excludes taskbar
Linux: Respects panel reservations

Settings

Window Management Panel

Settings > General > Window Management:

Enable Window Management - Toggle feature on/off
Show Preview - Enable/disable preview mode
Execution Delay - Minimum time between operations (default: 14ms)

Accessibility Permissions

Grant Permission

macOS requires Accessibility permission for window control.

System Settings

System Settings > Privacy & Security > Accessibility

Enable SuperCmd

Check the box next to SuperCmd in the app list.

Restart if Needed

Restart SuperCmd after granting permission.

Without Accessibility permission, window management features will not work.

Advanced Features

Smart Grid Layouts

Auto-organize uses intelligent grid calculation (src/renderer/src/WindowManagerPanel.tsx:608):

function computeGridDimensions(count: number, region: Rect) {
  // Finds optimal rows×cols to match screen aspect ratio
  // Minimizes empty cells
  // Example: 5 windows → 3×2 grid (one empty cell)
}

Window Size Hints

Preserves preferred window dimensions when possible:

// Smart vertical split (src/renderer/src/WindowManagerPanel.tsx:721)
function splitVerticalSmart(
  area: ScreenArea,
  leftWindows: ManagedWindow[],
  rightWindows: ManagedWindow[]
) {
  // Respects desired widths from current window sizes
  // Ensures both sides remain usable
}

Minimum Window Constraints

const MIN_WINDOW_WIDTH = 120;  // pixels
const MIN_WINDOW_HEIGHT = 60;  // pixels

Prevents windows from becoming too small to use.

Troubleshooting

Windows won't move

Check Accessibility permission (System Settings)
Ensure window is not fullscreen
Try a different window
Restart SuperCmd

Wrong window selected

Activate the target window first
Use Window Management panel to explicitly select
Check for hidden or minimized windows

Layouts don't fit screen

Verify screen resolution detection
Check for non-standard DPI scaling
Try simpler layouts (halves instead of sixths)

Auto-organize arranges wrong windows

Minimize windows you don’t want arranged
Close unnecessary windows
Manually position first, then fine-tune

Best Practices

Use Consistent Shortcuts

Assign keyboard shortcuts to your most-used presets

Preview First

Use Shift+Enter to preview complex layouts

Start Simple

Master halves and quarters before using sixths

Combine Presets

Apply preset, then fine-tune with 10% adjustments

Performance

Execution Throttling

Prevents rapid successive operations (src/renderer/src/WindowManagerPanel.tsx:206):

const WINDOW_PRESET_EXECUTION_MIN_INTERVAL_MS = 14;

// Queued execution ensures operations don't overlap
windowPresetExecutionQueue = Promise.resolve();

This prevents visual glitches and ensures smooth animations.

Window Inventory Caching

Window lists are cached briefly to reduce system calls:

const lastInventoryAt = Date.now();
if (Date.now() - lastInventoryAt < 100) {
  // Use cached window list
}

Platform Support

Platform	Support Level	Notes
macOS	Full	Native window APIs
Windows	Full	Win32 APIs
Linux	Partial	X11/Wayland varies

Linux support depends on window manager. Tested on GNOME and KDE.

Get Started

Core Features

Configuration

Extensions

​Overview

​Quick Start

​Layout Presets

​Halves & Quarters

​Thirds

​Fourths

​Sixths (2×3 Grid)

​Special Layouts

Center

Almost Maximize

Maximize

Auto-Organize

​Fine-Tuning Controls

​Size Adjustments (10% Steps)

​Position Adjustments

​Auto-Organize

​How It Works

​Layout Strategies (src/renderer/src/WindowManagerPanel.tsx:1027)

​Window Detection

​Manageable Windows

​Target Window Selection

​Visual Preview

​Preview Mode

​Keyboard Shortcuts

​Setting Shortcuts

​Preset Command IDs (src/renderer/src/WindowManagerPanel.tsx:84)

​Multi-Monitor Support

​Screen Detection

​Work Area Calculation

​Settings

​Window Management Panel

​Accessibility Permissions

​Advanced Features

​Smart Grid Layouts

​Window Size Hints

​Minimum Window Constraints

​Troubleshooting

​Best Practices

Use Consistent Shortcuts

Preview First

Start Simple

Combine Presets

​Performance

​Execution Throttling

​Window Inventory Caching

​Platform Support

Build docs developers (and LLMs) love

Overview

Quick Start

Layout Presets

Halves & Quarters

Thirds

Fourths

Sixths (2×3 Grid)

Special Layouts

Fine-Tuning Controls

Size Adjustments (10% Steps)

Position Adjustments

Auto-Organize

How It Works

Layout Strategies (src/renderer/src/WindowManagerPanel.tsx:1027)

Window Detection

Manageable Windows

Target Window Selection

Visual Preview

Preview Mode

Keyboard Shortcuts

Setting Shortcuts

Preset Command IDs (src/renderer/src/WindowManagerPanel.tsx:84)

Multi-Monitor Support

Screen Detection

Work Area Calculation

Settings

Window Management Panel

Accessibility Permissions

Advanced Features

Smart Grid Layouts

Window Size Hints

Minimum Window Constraints

Troubleshooting

Best Practices

Performance

Execution Throttling

Window Inventory Caching

Platform Support