focus_window
Activate macOS applications and raise specific windows by title using fuzzy matching for app names. Switch between windows quickly to improve workflow efficiency.
Instructions
Activate an application and optionally raise a specific window by title. App name supports fuzzy matching.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app | Yes | Application name to activate. | |
| title | No | Window title to raise. If omitted, the frontmost window of the application is activated. |
Implementation Reference
- src/tools/window.ts:157-199 (handler)The 'handleFocusWindow' function acts as the handler for the 'focus_window' tool. It parses input arguments, resolves the application name, and executes an AppleScript to activate the application and optionally raise a specific window.
/** Handle focus_window tool call. */ async function handleFocusWindow( args: Record<string, unknown>, ): Promise<CallToolResult> { const parsed = FocusWindowInputSchema.parse(args); const app = await resolveAppName(parsed.app); const safeApp = escapeAppleScriptString(app); // Activate the application let script = `tell application "${safeApp}" to activate`; // If a specific window title is requested, raise it via System Events if (parsed.title) { const safeTitle = escapeAppleScriptString(parsed.title); script += ` delay 0.3 tell application "System Events" tell process "${safeApp}" set frontmost to true try perform action "AXRaise" of (first window whose name is "${safeTitle}") on error error "Window titled \\"${safeTitle}\\" not found in ${safeApp}" end try end tell end tell`; } await runAppleScript(script); return { content: [ { type: "text" as const, text: JSON.stringify({ success: true, app: parsed.app, ...(parsed.title ? { title: parsed.title } : {}), }), }, ], }; } - src/tools/window.ts:26-35 (schema)'FocusWindowInputSchema' defines the structure and validation for input arguments required by the 'focus_window' tool.
const FocusWindowInputSchema = z.object({ app: z.string().max(1_000).describe("Application name to activate."), title: z .string() .max(1_000) .optional() .describe( "Window title to raise. If omitted, the frontmost window of the application is activated.", ), }); - src/tools/window.ts:88-97 (registration)The 'focus_window' tool is defined within the 'windowToolDefinitions' array, which provides the metadata and schema for the tool.
{ name: "focus_window", description: "Activate an application and optionally raise a specific window by title. App name supports fuzzy matching.", inputSchema: zodToToolInputSchema(FocusWindowInputSchema), annotations: { readOnlyHint: false, destructiveHint: false, }, }, - src/tools/window.ts:252-252 (registration)The 'focus_window' tool is registered in 'windowToolHandlers', mapping it to its handler function with queuing.
focus_window: (args) => enqueue(() => handleFocusWindow(args)),