Skip to content

PatcherMenu

Jump to bottom
Gil Burns edited this page Jun 28, 2026 · 7 revisions

PatcherMenu

PatcherMenu is an optional menu bar app that gives users real-time visibility into patch status and lets them trigger patching phases on demand. It runs as a LaunchAgent for the logged-in user and is entirely separate from the daemon — it only reads data and sends XPC requests; it cannot apply updates on its own.

Installation

PatcherMenu is enabled by setting the ShowMenuBarApp preference to true. On each scheduler cycle, the daemon reconciles this preference against the LaunchAgent plist at /Library/LaunchAgents/com.gilburns.patcher.menu.plist:

  • When ShowMenuBarApp is true: the plist is written and bootstrapped for the current console user's UID via launchctl bootstrap.
  • When ShowMenuBarApp is false: the plist is removed and the agent is unloaded via launchctl bootout.

The app itself is installed to /Applications/PatcherMenu.app as part of the standard Third Party Patcher package. The LaunchAgent is created and managed at runtime — it is not included in the package.

Menu Bar Icon

The icon in the menu bar changes to reflect patch status. The appearance is controlled by the MenuBarIcon preference.

Default icon (no MenuBarIcon set)

Two built-in SF Symbols are used:

State Icon
All up to date Outline arrow/checkmark symbol
Pending updates staged Filled arrow/checkmark symbol

Default icon states — up to date vs. pending

Custom path (MenuBarIcon = /path/to/icon.png or ~/path/to/icon.png)

The PNG is rendered as a template image (respects dark/light mode and accent color). When updates are staged, a small orange dot badge appears in the top-right corner of the icon.

Custom icon with and without the pending badge

Custom SF Symbol (MenuBarIcon = SF Symbol name)

Any SF Symbol name (e.g. shield.fill, gear) can be used. An orange dot badge appears when updates are staged, same as the custom path mode.

Tip: The icon always reflects staged (downloaded and ready) updates, not detected-but-not-yet-downloaded updates. An icon with no badge does not necessarily mean no updates are available — only that none are staged yet.

The Popover Window

Clicking the menu bar icon opens a popover. It is divided into several sections.

Full PatcherMenu popover — overview

Header

The header shows the app title (configurable via AppTitle) and how recently the display was last refreshed. A small spinner appears while a refresh or XPC-triggered phase is in progress. An optional ? button opens the Support Info panel (controlled by ShowHelpButton).

PatcherMenu header

Actions

The Run Now button opens a dropdown menu with actions that can be triggered immediately via XPC. The available actions depend on preference settings:

Menu item Preference Behavior
Apply pending updates Always shown Runs the apply phase immediately. Disabled if no updates are staged.
Download new Updates ShowMenuDownloadAction (default: true) Runs the stage phase. Disabled if no updates have been detected.
Check for Updates ShowMenuCheckAction (default: true) Runs the check phase. Always enabled.
Full Discovery Scan ShowMenuScanAction (default: true) Runs the scan phase. Produces a progress window. Always enabled.

Triggered phases run via the scheduler's XPC service. The popover refreshes its state 3 seconds after a phase is triggered.

An Available Software button appears alongside the Run Now button when the OptionalLabels preference is non-empty. Clicking it opens the Available Software app (or brings it to the front if already running).

Actions section — Run Now dropdown open

Pending Updates

Lists all apps that have a staged (downloaded and verified) installer waiting to be applied. Each row shows the app name and the version that will be installed, with an orange dot indicator.

When nothing is staged, a green "All apps up to date" message is shown. In monthly patching mode, the upcoming patch day is also displayed while the list is empty.

Pending Updates — empty state

Pending Updates — with staged items

Pending Downloads

This section only appears when updates have been detected but not yet downloaded. Each row shows the app name and the available version, with a blue dot indicator. This tells users that updates exist but won't be applied until they are staged (either by the scheduler or by using Run Now > Download new Updates).

Pending Downloads section

Pending Downloads section

Deadline Details

This section appears only when a patch deadline is active (i.e. at least one update has been staged and the deadline clock has started). It shows:

  • Hard deadline — the date by which patching must be complete, and how many days remain. Color-coded: gray when more than 7 days out, yellow at 7 days, orange at 3 days, red on deadline day.
  • Focus ignored after — (shown when configured) the date after which Focus mode will no longer block the patching prompt.
  • Deferral count — total number of times the update prompt has been deferred, including automatic deferrals.
  • Next prompt — an approximate label for when the next patching prompt will appear, based on the active deferral expiry.

Deadline Details section — approaching deadline

See Deferral and Deadlines for how deadlines are calculated.

Last Activity

The Last Activity section (shown when ShowActivitySection is true, which is the default) displays the last time each phase ran:

Phase What it represents
Apply Last time updates were installed
Stage Last time installers were downloaded
Check Last time installed versions were compared against available versions
Scan Last time a full discovery scan ran

While a phase is actively running, the date is replaced by a "Running" label with a progress indicator.

Last Activity section — idle

Last Activity section — phase running

Footer

The footer contains a Refresh button that immediately re-reads all data files and updates the display. An optional Quit button is shown when ShowQuitButton is true and ShowMenuBarApp is true — this lets users dismiss PatcherMenu without needing to kill the process from Activity Monitor.

Support Info Panel

Clicking the ? button in the header opens a small popover with IT support contact information. The content is controlled by preferences:

Preference Default Shown as
SupportTeamName IT Support Team Section heading
SupportTeamEmail support@company.com Clickable mailto link
SupportTeamPhone None Plain text (hidden if None)
SupportTeamWebsite None Clickable link (hidden if None)

The ? button itself is hidden when ShowHelpButton is false.

Support Info panel

Refresh Behavior

PatcherMenu keeps its display current through two mechanisms:

  1. Timer — refreshes all data once per minute automatically.
  2. File system watcher — watches the patcher config folder for writes. When active_phase.json appears or disappears (indicating a phase has started or completed), the display updates immediately. This ensures the activity section and pending lists reflect the current state without waiting for the next timer tick.

The "Refreshed X ago" caption in the header shows how long since the last full data reload.

Preference Keys

The following preferences control PatcherMenu appearance and behavior. See Preference Keys for the full reference.

Key Default Purpose
ShowMenuBarApp false Enable/disable PatcherMenu entirely
MenuBarIcon (empty) Custom icon — path to PNG or SF Symbol name
AppTitle Third Party Patcher Title shown in the popover header
ShowHelpButton true Show the ? support info button
ShowActivitySection true Show the Last Activity section
ShowQuitButton false Show the Quit button in the footer
ShowMenuDownloadAction true Include Download in the Run Now menu
ShowMenuCheckAction true Include Check for Updates in the Run Now menu
ShowMenuScanAction true Include Full Discovery Scan in the Run Now menu
SupportTeamName IT Support Team Team name in the support info panel
SupportTeamEmail support@company.com Email in the support info panel
SupportTeamPhone None Phone number in the support info panel
SupportTeamWebsite None Website URL in the support info panel

Clone this wiki locally