Window Management

Arrange, resize, and organize windows with keyboard shortcuts

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

1. Open Window Manager

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

2. Select Layout

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

3. Preview Layout

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

4. Apply Layout

   Press Enter to apply the layout and close the panel.

Layout Presets

Halves & Quarters

Halves

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

Quarters

• Top Left - Upper-left quarter
• Top Right - Upper-right quarter
• Bottom Left - Lower-left quarter
• Bottom Right - Lower-right quarter

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

1. Detects all windows on current screen
2. Filters out system windows and minimized windows
3. Sorts by position (top to bottom, left to right)
4. 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:

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

Visual Preview

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

Preview Mode

1. Navigate to a preset
2. Press Shift+Enter
3. Window outline appears showing future position
4. 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

1. Settings > Hotkeys
2. Find “Window Management” section
3. Click preset (e.g., “Left Half”)
4. Press desired key combination
5. 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

1. Grant Permission

   macOS requires Accessibility permission for window control.

2. System Settings

   System Settings > Privacy & Security > Accessibility

3. Enable SuperCmd

   Check the box next to SuperCmd in the app list.

4. 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

1. Check Accessibility permission (System Settings)
2. Ensure window is not fullscreen
3. Try a different window
4. 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.