list_windows
Read-only
Lists visible macOS windows with app details, titles, IDs, positions, sizes, and states. Filter windows by application name using fuzzy matching.
Instructions
List visible windows with their app name, title, ID, position, size, and minimized state. Optionally filter by application name. App name supports fuzzy matching (case-insensitive, partial names like 'chrome' for 'Google Chrome').
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app | No | Application name to filter by. If omitted, list windows from all applications. |
Implementation Reference
- src/tools/window.ts:129-155 (handler)The handler function responsible for processing the 'list_windows' tool request, which uses `runInputHelper` to communicate with the system.
/** Handle list_windows tool call. */ async function handleListWindows( args: Record<string, unknown>, ): Promise<CallToolResult> { const parsed = ListWindowsInputSchema.parse(args); const app = parsed.app ? await resolveAppName(parsed.app) : undefined; const response = await runInputHelper("list_windows", app ? { app } : {}); const result = ListWindowsResponseSchema.parse(response); const windows: WindowInfo[] = result.windows.map((w) => ({ app: w.app, title: w.title, id: w.id, position: { x: w.x, y: w.y }, size: { w: w.width, h: w.height }, minimized: w.minimized, })); return { content: [ { type: "text" as const, text: JSON.stringify({ windows }, null, 2), }, ], }; } - src/tools/window.ts:46-61 (schema)Zod schema for validating the response returned by the 'list_windows' helper.
/** Schema for validating the Swift helper list_windows response. */ export const ListWindowsResponseSchema = z.object({ success: z.boolean(), windows: z.array( z.object({ app: z.string(), title: z.string(), id: z.number(), x: z.number(), y: z.number(), width: z.number(), height: z.number(), minimized: z.boolean(), }), ), }); - src/tools/window.ts:78-87 (registration)Registration of the 'list_windows' tool definition in `windowToolDefinitions`.
{ name: "list_windows", description: "List visible windows with their app name, title, ID, position, size, and minimized state. Optionally filter by application name. App name supports fuzzy matching (case-insensitive, partial names like 'chrome' for 'Google Chrome').", inputSchema: zodToToolInputSchema(ListWindowsInputSchema), annotations: { readOnlyHint: true, destructiveHint: false, }, },