@bobfrankston/winpos

TypeScript implementation of WinPos - A Windows window positioning utility for multi-monitor setups.

Features

• Cross-Runtime: Works with both Node.js (24+) and Bun
• FFI-based: Direct Windows API calls via koffi (Node.js) or bun:ffi (Bun)
• Multi-Monitor: Full support for multiple displays
• Flexible Matching: Find windows by exact title, prefix, or regex
• Window State Management: Minimize, maximize, restore windows programmatically
• Auto-Restore: Windows are automatically restored from minimized/maximized state when positioning
• Library or CLI: Use as a command-line tool or import as a library

Installation

npm install @bobfrankston/winpos

Or with Bun:

bun add @bobfrankston/winpos

Usage

Command Line

# Move window to screen 0 at position (100, 200)
winpos "Notepad" 100 200 0

# Move window using percentages
winpos "Chrome*" 50% 50% 1

# Set window size as well
winpos "Visual Studio Code" 0 0 0 1920 1080

# List all windows
winpos *

# Get screen count
winpos -c

# Debug mode
winpos -d "Firefox" 0 0 1

Pattern Matching

• Exact match: winpos "Notepad" 0 0 0
• Prefix match: winpos "Chrome*" 0 0 0
• Regex match: winpos "/Visual.*Code/" 0 0 0

As a Library

import { run } from '@bobfrankston/winpos';

// Move a window programmatically
run(['Chrome*', '0', '0', '1', '1920', '1080']);

Screen Numbering

Screens are numbered starting from 0, sorted by position:

  +---+---+
  | 2 | 3 |
  +---+---+
  | 0 | 1 |
  +---+---+

• 0: Lower right (primary)
• 1: Lower left
• 2: Upper left
• 3: Upper right

Options

• -d - Debug mode
• -dbg - Verbose debug output
• -c - Return screen count
• -v / -version - Show version
• -title <name> - Window title/pattern (alternative to positional)
• -pos x,y[,screen] - Position (comma-separated, screen optional)
• -size w,h - Window size (width,height)
• -min - Minimize window
• -max - Maximize window
• -load <file> - Load config from JSON file
• -save <file> - Save config to JSON file (merges if exists)
• * - List all windows
• ** - List all windows including ignored

Parameters

Positional (legacy)

winpos <title> <x> <y> <screen> [<width> <height>]

Flag-based (new)

winpos <title> -pos x,y[,screen] [-size w,h]
winpos -title <name> -pos x,y,screen -size w,h
winpos <title> -min

JSON Config

winpos layout.json
winpos -load layout.json [-save output.json]

JSON Config Format

Single window:

{
  "name": "Notepad",
  "pos": { "x": 100, "y": 100, "screen": 0 },
  "size": { "w": 800, "h": 600 }
}

Multiple windows:

[
  { "name": "app1", "pos": { "x": 0, "y": 0, "screen": 0 } },
  { "name": "app2*", "pos": { "x": 100, "y": 100, "screen": 1 } },
  { "name": "pattern", "regex": true, "pos": { "x": 0, "y": 0, "screen": 2 } },
  { "name": "minimize-me", "minimize": true }
]

• name - Window title (exact match, prefix with *, or regex if regex: true)
• regex - If true, name is treated as a regex pattern
• pos - Position with x, y, and optional screen index
• size - Size with w (width) and h (height)
• minimize / maximize - Window state

Known Issues

Windows batch file working directory

When calling winpos from a batch file without call, the working directory may not be inherited correctly due to a Windows cmd.exe quirk.

Workarounds:

• Use call winpos instead of winpos in batch files
• Use winpos.ps1 instead of winpos
• Use absolute paths for config files: winpos "%~dp0config.json"

Requirements

• Windows OS
• Node.js 24+ or Bun 1.0+

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

License

MIT

Author

Bob Frankston