What actually makes something a desktop AI agent on the Mac

A desktop AI agent is an app that can receive input and render output outside of a single application viewport, on top of every Space and every fullscreen context on the Mac. That is different from a browser extension, which is clipped to a browser tab, and from a menu bar app, which is pinned to the status bar. The structural primitives that define it on macOS are a borderless NSWindow with NSWindow.Level.floating and a collectionBehavior that contains .canJoinAllSpaces and .fullScreenAuxiliary, plus a Carbon RegisterEventHotKey so the agent can be invoked when it is not the frontmost app. Fazm implements both primitives at FloatingControlBarWindow.swift lines 82-103 and GlobalShortcutManager.swift lines 86-100.

A normal AppKit NSWindow is created on one Desktop Space and stays pinned there. If the user switches Spaces (Ctrl+Right Arrow), the window disappears from view. For a desktop agent that claims to work on any Mac workflow, that is fatal. The agent has to be present on every Space the user switches to, including Spaces created seconds ago, without the developer writing per-Space tracking code. .canJoinAllSpaces tells AppKit to make the window a member of every existing and future Space. Fazm sets it at FloatingControlBarWindow.swift line 99.

When any app enters macOS fullscreen, the system moves that app to its own dedicated Space and hides everything else. Keynote, Final Cut Pro, Zoom screen share, fullscreen games, and Safari PiP all use this mode. Without .fullScreenAuxiliary, a desktop agent is invisible during exactly the moments users care about most: during a presentation, during a recording, during screen share. .fullScreenAuxiliary tells AppKit to render this window on top of the fullscreen app's dedicated Space, not just the Space it was created on. Fazm sets it at the same line as .canJoinAllSpaces, FloatingControlBarWindow.swift line 99.

It is a FourCharCode, a 32-bit integer that Carbon Event Manager uses to namespace hotkey registrations per application. Each byte is an ASCII character: 0x46 is F, 0x41 is A, 0x5A is Z, 0x4D is M, so the signature spells FAZM. Carbon uses the signature to deduplicate hotkey IDs across applications. Without a unique signature, two apps registering a hotkey with the same ID would collide. The value is at GlobalShortcutManager.swift line 88. The reason it is a Carbon call rather than an AppKit local monitor is that Carbon hotkeys fire system-wide, even when Fazm is not the frontmost app. An AppKit local monitor only fires when the app has focus, which is the opposite of what a desktop agent needs.

Because there is no modern AppKit API for system-wide hotkeys. NSEvent.addGlobalMonitorForEvents observes events but cannot consume them. NSEvent.addLocalMonitorForEvents only fires when the app is key. Carbon's RegisterEventHotKey is the only path on macOS that both observes and consumes a global hotkey, and Apple has preserved it precisely because every serious desktop utility (Alfred, Raycast, CleanShot, 1Password) depends on it. Fazm calls it at GlobalShortcutManager.swift line 90.

Cmd+\\ is the global toggle. It has to work even when the user is in Xcode, Safari, or Slack with those apps frontmost. That is Carbon territory. Cmd+N only has to work when the floating bar is already visible and focused, so it uses NSEvent.addLocalMonitorForEvents, an AppKit API, at FloatingControlBarWindow.swift lines 108-114. The local monitor is layered above the text field so it fires before the field consumes the N keystroke. Fazm returns nil from the monitor closure to consume the event instead of letting it reach the text field.

AppKit treats borderless NSWindow instances as non-key by default because most borderless windows are inspector panels, HUDs, or notifications that should not steal keyboard input from the frontmost application. A desktop agent is the opposite: it needs to accept keystrokes directly so the user can type into the chat without having to click first. Overriding canBecomeKey and canBecomeMain to true (FloatingControlBarWindow.swift lines 139-140) tells AppKit to route keyboard events to this window when it is visible.

The window primitives are the same. Launchers like Raycast and Alfred also use borderless NSWindows with .floating level and a Carbon hotkey. The difference is what the window does after it appears. A launcher looks up commands and apps; a desktop AI agent reads the accessibility tree of the frontmost app, invokes tools in a background agent loop, and renders streaming model responses with in-place follow-up prompts. Fazm uses the same window class as a launcher for the visible layer, then hooks it to an agent runtime via acp-bridge. The launcher stops at the palette; the agent keeps going.

No, but if it is not a floating window it is not really a desktop agent. A menu bar app is pinned to the status bar and can only render a dropdown; a browser extension is clipped to the browser tab; a normal app window is hidden by Cmd+Tab. An agent that wants to overlay any app, follow the user across Spaces, and keep working during fullscreen needs all four of: .borderless, .floating, .canJoinAllSpaces, .fullScreenAuxiliary. You can skip any one of them, but the product that results is something else.

It is the seam between Carbon and AppKit. Carbon hotkey callbacks run on the main thread but use a C-level API that does not know about any of Fazm's Swift classes. Rather than pass closures into Carbon, Fazm posts a NotificationCenter notification inside the hotkey handler and subscribes to it from AppKit classes like FloatingControlBarManager. The three names are com.fazm.desktop.toggleFloatingBar, com.fazm.desktop.askAI, and com.fazm.desktop.newPopOutChat (GlobalShortcutManager.swift lines 10-12). This makes the Carbon layer testable: DistributedNotificationCenter posts with the same names fire the same code paths, which is how Fazm's programmatic test hooks work.

Yes. The relevant files are in the public Fazm tree at Desktop/Sources/FloatingControlBar/. Run wc -l FloatingControlBarWindow.swift GlobalShortcutManager.swift and you should see 2,188 and 141 lines respectively. Grep for 'canJoinAllSpaces' inside FloatingControlBarWindow.swift, you will find it at line 99. Grep for '0x46415A4D' inside GlobalShortcutManager.swift, you will find it at line 88. Grep for 'com.fazm.desktop' and you will find the three notification names at lines 10-12. Everything on this page is a direct line-number reference to that tree.

Once the window and hotkey are in place, the agent runtime lives behind them. Fazm wires the floating bar to acp-bridge/src/index.ts, which runs the ACP (Agent Client Protocol) loop, mounts MCP servers for macos-use, whatsapp, google-workspace, playwright, and fazm_tools, and streams model responses back to the SwiftUI view inside the NSWindow. The window and the hotkey are the desktop primitives. The accessibility tree reads and MCP tool invocations are the agent primitives. This guide is about the first half, because without it there is no place for the second half to surface.