get-windows

Supported Platforms

• macOS: 10.14+
• Windows: 7+
• Linux: Supported, but with limitations.

Platform Specifics

• Windows: The id property returns the memory address of the window handle. This handle is unique per window and can be used for identification.
• Linux: Wayland is not supported because it does not provide a way to identify the active window for security reasons.
• Electron: If using in a sandboxed Electron app and you need the .url property, you must add the proper entitlements and usage description.

Install the package using npm. Note that get-windows is an ESM package and requires you to use ESM in your project.

npm install get-windows

Use openWindows() to asynchronously retrieve an array of metadata for all open windows, ordered from front to back. Returns Promise<Result[]>.

Use openWindowsSync() for the synchronous version, which returns Result[].

import {openWindows} from 'get-windows';

const windows = await openWindows();
for (const win of windows) {
  console.log(win.title);
}

Use activeWindow(options?) to asynchronously retrieve metadata about the currently focused window. It returns a Promise<Result> or Promise<undefined> if no active window is found.

For synchronous access, use activeWindowSync(options?).

import {activeWindow} from 'get-windows';

const window = await activeWindow();
console.log(window);

When running on macOS, you can pass an options object to activeWindow(options?) to manage permission prompts:

• accessibilityPermission (boolean, default: true): If set to false, it prevents the accessibility permission prompt on macOS 10.15+. Note that the url property will not be retrieved if this is disabled.
• screenRecordingPermission (boolean, default: true): If set to false, it prevents the screen recording permission prompt on macOS 10.15+. Note that the title property will always be an empty string if this is disabled.

The Options object allows you to control macOS permission prompts. By default, both accessibility and screen recording checks are enabled.

• accessibilityPermission (boolean, default: true): If set to false, prevents the accessibility permission prompt on macOS 10.15+. Note that the url property will not be retrieved if this is disabled.
• screenRecordingPermission (boolean, default: true): If set to false, prevents the screen recording permission prompt on macOS 10.15+. Note that the title property will always be an empty string if this is disabled.

The Result object contains metadata about a window. Fields vary by platform:

• platform (string): 'macos' | 'linux' | 'windows'
• title (string): Window title
• id (number): Window identifier (On Windows, this is the memory address of the window handle)
• bounds (Object): { x, y, width, height }
• contentBounds (Object): { x, y, width, height } (Windows only; excludes title bar, menu bar, and frame)
• owner (Object): { name, processId, bundleId, path } (bundleId is macOS only)
• url (string, optional): URL of the active browser tab (macOS only; supported browsers include Safari, Chrome, Edge, Brave, Mighty, Ghost Browser, Wavebox, Sidekick, Opera, or Vivaldi)
• memoryUsage (number): Memory usage by the window owner process

Use activeWindow(options?) to asynchronously retrieve metadata about the currently focused window. It returns a Promise that resolves to a Result object or undefined if no active window is found. The returned Result is platform-specific (macOS, Windows, or Linux).

import {activeWindow} from 'get-windows';

const result = await activeWindow();

if (!result) {
	return;
}

if (result.platform === 'macos') {
	// Among other fields, `result.owner.bundleId` is available on macOS.
	console.log(`Process title is ${result.title} with bundle id ${result.owner.bundleId}.`);
} else if (result.platform === 'windows') {
	console.log(`Process title is ${result.title} with path ${result.owner.path}.`);
} else {
	console.log(`Process title is ${result.title} with path ${result.owner.path}.`);
}

Use activeWindowSync(options?) to retrieve metadata about the currently focused window synchronously. It returns a Result object or undefined if no active window is found.

import {activeWindowSync} from 'get-windows';

const result = activeWindowSync();

if (result) {
	if (result.platform === 'macos') {
		// Among other fields, `result.owner.bundleId` is available on macOS.
		console.log(`Process title is ${result.title} with bundle id ${result.owner.bundleId}.`);
	} else if (result.platform === 'windows') {
		console.log(`Process title is ${result.title} with path ${result.owner.path}.`);
	} else {
		console.log(`Process title is ${result.title} with path ${result.owner.path}.`);
	}
}

Use the asynchronous openWindows(options) function to retrieve a list of all currently open windows on the system. This function supports macOS (darwin), Linux, and Windows (win32).

import { openWindows } from 'get-windows';

const windows = await openWindows();
console.log(windows);