@k5z/window-manager

A Node.js TypeScript wrapper for managing macOS windows through a Swift CLI.

Installation

npm install @k5z/window-manager
# or
pnpm add @k5z/window-manager

Note: This package is macOS-only and requires either:

• A pre-built binary (included in npm releases)
• Xcode and Command Line Tools for building from source

Usage

TypeScript/JavaScript

import { WindowManager } from '@k5z/window-manager';
// or
const { WindowManager } = require('@k5z/window-manager');

const wm = new WindowManager();

// List all windows
const windows = await wm.list();
console.log(windows);

// Focus a window by ID
await wm.focus(12345);

// Move a window
await wm.move(12345, 100, 200);

// Resize a window
await wm.resize(12345, 800, 600);

// Find windows by application name
const chromeWindows = await wm.findByApplication('Chrome');

// Find windows by title
const codeWindows = await wm.findByTitle('index.ts');

Synchronous API

All methods also have synchronous versions:

const windows = wm.listSync();
wm.focusSync(12345);
wm.moveSync(12345, 100, 200);
wm.resizeSync(12345, 800, 600);

Custom Binary Path

If you need to specify a custom path to the window-manager binary:

import { createWindowManager } from '@k5z/window-manager';

const wm = createWindowManager({
  binaryPath: '/custom/path/to/window-manager'
});

Permissions

This package requires Accessibility permissions on macOS to function properly.

Grant permissions in: System Settings > Privacy & Security > Accessibility

Add your terminal app or the Node.js process to the allowed applications.

API

WindowManager

Methods

• list(): Promise<WindowInfo[]> - List all windows
• listSync(): WindowInfo[] - List all windows (synchronous)
• focus(windowID: number): Promise<void> - Focus a window
• focusSync(windowID: number): void - Focus a window (synchronous)
• move(windowID: number, x: number, y: number): Promise<void> - Move a window
• moveSync(windowID: number, x: number, y: number): void - Move a window (synchronous)
• resize(windowID: number, width: number, height: number): Promise<void> - Resize a window
• resizeSync(windowID: number, width: number, height: number): void - Resize a window (synchronous)
• findByApplication(appName: string): Promise<WindowInfo[]> - Find windows by app name
• findByTitle(title: string): Promise<WindowInfo[]> - Find windows by title

WindowInfo

interface WindowInfo {
  windowID: number;
  applicationName: string;
  processName: string;
  windowTitle: string;
}

Development

Building from source

# Install dependencies
pnpm install

# Build TypeScript and Swift binary
pnpm run build

# Build only TypeScript
pnpm run build:ts

# Build only Swift binary
pnpm run build:binary

Requirements for building

• macOS (10.14+)
• Xcode and Command Line Tools
• Node.js 14+
• Swift 5.0+

License

ISC