macos-use Ships A Second Binary Whose Whole Purpose Is To Die After One Screenshot

Because CGWindowListCreateImage has a documented side effect on macOS: the first call in a process loads the ReplayKit framework lazily, and ReplayKit spawns an internal background worker that never stops. In a short-lived CLI that is invisible. In a long-lived MCP server that sits in the menu bar for hours, the parent process measures at around 19% CPU usage indefinitely after the first screenshot. The fix encoded in the repo is architectural: keep the capture call in a sibling executable (screenshot-helper) so the ReplayKit worker dies when that subprocess exits. Sources/ScreenshotHelper/main.swift is 111 lines total; Package.swift declares it as a second .executableTarget next to the main server.

Sources/MCPServer/main.swift:435-510. The main server finds the helper next to its own binary via (myPath as NSString).deletingLastPathComponent at main.swift:436-438, builds an argv list at main.swift:445-454 (window ID, output path, optional --click and --bounds for the crosshair annotation), launches Process() at main.swift:459-469, enforces a 5-second deadline via DispatchGroup.wait at main.swift:477-489, forwards the helper's stderr verbatim at main.swift:492-495, and reads the saved PNG path off the helper's stdout at main.swift:502-506. The helper is allowed to die after every single capture; nothing is pooled.

Four things, in order. One: parse argv at Sources/ScreenshotHelper/main.swift:25-42 to pull the window ID, output path, optional click point, and optional window bounds rectangle. Two: call CGWindowListCreateImage with .optionIncludingWindow at ScreenshotHelper/main.swift:45; this is the call that loads ReplayKit. Three: if a click point was passed, open a CGContext at ScreenshotHelper/main.swift:61-90 and draw a red crosshair plus a ring at the click point, translating from screen coordinates to image-local coordinates with scaleX = imageWidth / windowRect.width. Four: write the PNG via NSBitmapImageRep at ScreenshotHelper/main.swift:94-101 and print the output path to stdout so the parent can confirm success. Then exit. ReplayKit goes with it.

Because macos-use targets long-lived MCP client sessions. Claude Desktop, Cursor, and Cline keep the server alive for the duration of the session, which is often hours. Every diff-producing tool call (click, type, press, scroll) produces a screenshot, and in-process capture would compound: the first call pins one ReplayKit worker; the thousandth call pins the same one, still burning CPU, still holding framework memory. Battery-powered developer laptops would fan up. Cache locality degrades. A subprocess that dies after every capture costs a process spawn (~10-30ms on Apple silicon) and nothing else. That trade is easy.

Via intersection scoring against the accessibility traversal's window bounds. main.swift:388-425 reads the CGWindowList via CGWindowListCopyWindowInfo with .optionOnScreenOnly plus .excludeDesktopElements, filters to windows whose kCGWindowOwnerPID matches the target PID and whose kCGWindowLayer equals 0 (real app windows, not desktop widgets), and for each candidate computes score = intersection(traversalWindowBounds, windowBounds).area. Highest score wins. If no traversal bounds are available the fallback is largest visible window. The chosen CGWindowID is printed to stderr with its score, e.g. 'log: captureWindowScreenshot: selected window 31704 (score=2073600)', so you can reconstruct which window the helper captured.

Three layered failures, all logged. One: main.swift:440-443 checks FileManager.default.fileExists(atPath: helperPath) before Process().run() and bails with 'screenshot-helper not found at <path>' if the binary did not ship alongside the server. Two: main.swift:485-489 wraps waitUntilExit() in a DispatchGroup with a 5-second deadline; if wait() returns .timedOut the parent calls process.terminate() and returns nil. Three: main.swift:497-500 checks process.terminationStatus == 0 and logs 'exited with status N' if the helper crashed after launching. In all three cases captureWindowScreenshot returns nil to its caller; the MCP response still includes the traversal and the diff, just no screenshot path.

Yes. ScreenshotHelper/main.swift:55-58 computes scaleX = imageWidth / windowRect.width and scaleY = imageHeight / windowRect.height, which accounts for any backing-scale difference between the window in screen coordinates and the CGImage the CGWindowListCreateImage call returned. The click point is translated with (clickPoint.x - windowRect.origin.x) * scaleX for horizontal and then Y-flipped at ScreenshotHelper/main.swift:67-68 because CoreGraphics drawing has origin bottom-left while screen coordinates have origin top-left. The crosshair arms are 15 points, the ring radius is 10 points, both scaled by max(scaleX, scaleY) so the annotation looks the same whether the window was captured at 1x or 2x.

The main server computes the helper path at main.swift:436-438: let myPath = CommandLine.arguments[0]; let myDir = (myPath as NSString).deletingLastPathComponent; let helperPath = (myDir as NSString).appendingPathComponent("screenshot-helper"). That is, the helper must be in the same directory as the main executable. swift build places both in .build/<config>/ automatically because Package.swift declares both as .executableTarget. npm packaging and Homebrew bottling both preserve that sibling layout. If you hand-copy the main binary to a custom location and forget the helper, you get the 'screenshot-helper not found' warning and screenshots silently disappear from the response.

steipete/macos-automator-mcp is AppleScript-oriented and does not ship window capture at all; screenshot is a separate concern. ashwwwin/automation-mcp uses a Node addon and calls screencapture via child_process; screencapture is a separate CLI that already spawns a fresh process per call, so the same isolation is accidental rather than architectural. CursorTouch/MacOS-MCP and mb-dev/macos-ui-automation-mcp both use in-process APIs (NSImage+CGWindowList paths or similar) from a long-lived server and do not mention the ReplayKit side effect. macos-use is the only one I found that declares a dedicated executableTarget whose entire reason for existing is to be thrown away after one image.

Yes. Before each invocation the main server logs 'launching screenshot-helper for window <ID>' to stderr at main.swift:456. During the roughly 200-500ms the helper is alive you can ps -ef | grep screenshot-helper and see its full argv including the --click and --bounds flags. After exit you can tail the helper's stderr from the main server's log (forwarded verbatim at main.swift:492-495), and you can read the PNG at the output path that came back via stdout. The screenshot file itself is named <timestamp>_<toolname>.png under /tmp/macos-use/, so you can correlate each helper invocation with the tool call that spawned it.

Almost none, and that is the point. The parent passes a window ID and an output path via argv, not shared memory. The helper does not call back into the parent, does not read the MCP stream, does not consume any TCC permissions the parent did not already consume. The only shared resource is the filesystem: the helper writes the PNG to the path the parent chose. Because there is no IPC beyond argv plus stdout, a helper crash cannot corrupt parent state and a parent crash does not leave the helper hanging (macOS reaps orphaned processes whose stdin is closed).

Write a tiny Swift script that calls CGWindowListCreateImage(.null, .optionOnScreenOnly, kCGNullWindowID, [.bestResolution]) once and then runs RunLoop.main.run(). Launch it, wait a few seconds, and run top -pid <pid>. You will see a background thread belonging to ReplayKit pinning CPU. Kill the process, the CPU falls to zero. Now re-run the same script but call the capture inside a child Process() that exits immediately; top will never see the leak. That is the experiment that motivated the two-binary architecture documented at Sources/MCPServer/main.swift:382-385.