Open StableBar.dmg, drag StableBar to Applications, then open the app. Setup starts with a tour: a line of light swells into a glass bar under StableBar's name, over slowly shifting amber colors, and Get Started (Return) plays a short demo in that bar. It builds a bar from widgets, clicks two of them open and tries a few themes. The last theme turns it into your own bar, which flies up into place; Skip intro (Esc) jumps to that last part. When the macOS menu bar is visible, the demo bar first stops and asks Make it your menu bar.: Replace the menu bar (Return) hides the macOS menu bar and lands the bar on the top edge in its place, and Keep the menu bar (Esc) lands it below. Four steps then let you pick a preset, a theme and appearance, and a placement and clock, choose access, window clearance and Open at login, and try the bar itself. Each choice shows on your real bar right away; in the last step, click a widget to open its popup. Finish setup then saves everything. Reopen it with Getting Started… in the menu-bar icon's menu, or Settings → General → Help → Open setup…. With Reduce Motion on, the tour skips its opening animation.
Widgets are the items on your bar. Packages provide extra widgets or themes. After setup, Edit Bar in Place turns the bar itself into the editor; Open Settings opens Settings → Bar, where you can change content, appearance and behavior. The menu-bar icon also links to this user guide.
The first step offers presets under Widgets and themes under Theme. Each preset names its theme and shows its widgets as icons in bar order, with the ones it adds brighter. Every preset ends the bar with Sound, Battery when it adds it, the clock and Menu bar items, in that order: Minimal keeps the app menus on Built-in; Developer adds Workspaces, System and Battery on Phosphor in Dark; Workday adds Meetings and Battery on Léman; Notch puts the Notch theme on the top edge and adds Battery; Everything adds Workspaces, Meetings, System and Battery on Catppuccin. A preset chooses the built-in widgets to add, a theme and an appearance; pick another theme afterwards and the preset's widgets stay. Click the chosen preset again to keep your current bar.
Under Theme, a row of cards shows each theme that ships with StableBar or that you have installed, drawn as a small bar. Click a card, or move through them with ← and →; the card marked Current keeps your theme as it is. Light, Dark and Automatic, beside the heading, control the bar's appearance, and the cards follow it. Setup shows your current appearance, placement and clock, and Keep current leaves them untouched. The bar shows the effect of active profiles, and the last step names any profile that still controls a setting, with a button to edit it. Setup saves your defaults and preserves custom widgets, scripts and imported files.
A new configuration places the bar on the top edge when the macOS menu bar hides automatically, and below the menu bar otherwise; existing configurations retain their position. Choosing Top edge in setup, or the Notch preset, turns on Automatically hide and show the menu bar, so the menu bar no longer covers the bar; Below menu bar turns it off; later, Automatically hide the menu bar in Settings turns it on or off. Setup makes this change through System Events, so the first time macOS asks to let StableBar control System Events. Skipping or closing setup puts the menu bar setting back. Quitting StableBar leaves the setting as it is, but StableBar remembers when setup or Settings turned auto-hide on, so Uninstall turns it off again. Neither placement reserves space for windows. Setup's third step asks for Accessibility access, offers Keep windows clear of StableBar and Keep notifications clear of StableBar, and gives separate guidance when it detects AeroSpace, yabai or OmniWM, or when Workspaces uses macOS Spaces. See Keeping windows clear of the bar.
System shows CPU and memory use with details in its popup; Meetings shows your next meeting and today's agenda; Battery shows the charge with details in its popup; Sound shows the volume; Menu bar items lists the items in the macOS menu bar. Workspaces uses AeroSpace, yabai or OmniWM when one is installed: AeroSpace and yabai on your login shell's PATH, OmniWM as its app or omniwmctl on the PATH. It prefers your configured source and otherwise uses the first one installed, in that order; yabai still needs its signals, and OmniWM needs Enable IPC. Without any of them, Workspaces shows your macOS Spaces, which switch desktops through the Switch to Desktop shortcuts. These widgets use native providers and run no scripts. A preset adds widgets but never removes any. A matching widget already on your bar stays as it is; a turned-off one is turned on with its settings kept. A different widget with the same ID is kept. Active profile overrides still apply.
The starter bar shows the frontmost app's menus, Sound, the clock and Menu bar items. The menus need Accessibility access; until you allow it, a warning icon takes their place, except while setup is open. Setup's third step lists Accessibility, which clearance and menu widgets use, and Calendars when a calendar widget needs it, shows their status and offers a permission action or System Settings link. The first Allow… for Accessibility, in setup or in Settings → General → Access, shows the macOS prompt; later clicks open System Settings → Privacy & Security → Accessibility. Status updates when you return from System Settings, and the bar shows the app menus. A newly chosen Meetings widget stays off your bar during the tour until you allow Calendar access, so macOS does not prompt in the middle of it. Allow Calendar access in the third step, or choose Set up Meetings later: finishing without access saves that widget turned off, so it does not prompt immediately after setup. Enable it later in Bar. Existing calendar widgets stay unchanged. Scripts that control other apps ask for Automation access when used; AeroSpace and yabai manage their own Accessibility permission.
Until Finish setup, your choices are temporary changes, like command-line changes without --persist: the bar shows them, but the file is unchanged. Skip setup (Esc) puts your bar back as it was. Permission buttons act immediately through macOS. Open at login is off until enabled and requires the app to be in Applications. If macOS requires Login Items approval, setup shows the remaining action. A setup that has never been completed opens again on the next launch; you can always reopen it from Settings → General.
Stable releases after v0.4.0 on the releases page include StableBar.dmg. Betas of the next version are marked Pre-release. Both are built for Apple silicon. Releases signed with a Developer ID are notarized and open like any app. Earlier ones are ad-hoc signed, so macOS blocks them the first time you open them: allow it in System Settings → Privacy & Security → Open Anyway.
To install the latest stable release with Homebrew instead, run brew install --cask seb-graf/tap/stablebar.
The first launch creates ~/.config/stablebar/config.json from Resources/config.json, with the bar on the top edge, or below the menu bar when the menu bar doesn't hide. Subsequent launches keep your file. If it is a symbolic link, Setup, Settings and command-line saves update the linked file and keep the link. Right-click the bar or use its macOS menu-bar icon to choose Edit Bar in Place, Try Themes…, Settings… or Quit StableBar. While editing, the menus offer Finish Editing Bar. Settings → General controls login, window and notification clearance, access and workspace connections, opens or reloads the configuration file, and links to updates, setup and help. Placement is in Settings → Bar → Bar → Placement.
Keep personal settings in ~/.config/stablebar/config.json and personal scripts in ~/.config/stablebar/widgets/, outside the repository. Point commands directly at those scripts. Resources/config.json is the shared starter configuration; rebuilding the app does not overwrite your personal file. Local scripts should load any supporting files from their own directory.
StableBar sits at the top edge of each display. bar.offset moves it down from that edge. It hides on native fullscreen Spaces. AeroSpace gaps are managed separately. Of the macOS menu-bar settings, StableBar changes only auto-hide, in setup and in Settings. Keep the center clear on a notched display. The default configuration uses only the left and right groups.
A release signed with a Developer ID checks GitHub for a newer version shortly after launch and every four minutes. These silent checks pause while an update check, offer, download or installation is already active, and stop making requests when automatic checks are off. A failed check retries at the next interval. Sparkle still chooses the compatible release and handles its download and installation. As soon as a check finds one, a filled circular download icon with a small theme-accent dot fades in at the right end of the bar and moves the neighboring widgets aside. Reduce Motion disables that animation. Click it to see the changes from every release published after your installed version through the offered version, grouped newest first. The popup loads this history from GitHub, including releases no longer in the update feed. Its height stays at 420 points, with scrolling release notes and the download action kept below them. If the history cannot be loaded, it shows the offered release's notes and a link to all changes on GitHub. Download checks again and downloads the newest compatible release on your update track, so an older pending offer does not require an intermediate installation. Then choose Install and Relaunch once it's downloaded. Updates already downloaded keep their install action. The bar button stays icon-only and changes to a filled circular sync icon when the update is ready; its tooltip describes the current stage. Download and preparation progress appear inside the popup without increasing its height. Check for Updates… in the menu-bar icon's menu or in Settings → General → Updates checks right away and remains available while an update waits. Settings → General → Updates also turns off automatic checks, or lets StableBar download updates and install them when it quits.
Update track chooses the releases you get. Stable gets stable releases. Beta gets betas of the next version and stable releases, whichever is newer. An installed beta starts on Beta. Switching back to Stable keeps your beta until a newer stable release is out, because StableBar never installs an older version.
Beta version names include a UTC timestamp and build number, such as 0.5.0-beta.20261020103000.114, to keep new betas in order on GitHub. In-app updates compare the build number.
Only an app signed with a Developer ID updates itself, because the update must be signed by the same developer as the app it replaces. Ad-hoc signed releases and the builds you make yourself don't check for updates; Settings → General → Updates links to the releases page instead.
When the macOS menu bar hides automatically, Settings → General → Native menu bar → Reveal delay sets how long to hold the pointer at the top edge before it appears. Enter milliseconds: 1000 is one second, 2000 is two, and 3000 is three. 0, the default, adds no delay. Allow StableBar in System Settings → Privacy & Security → Accessibility.
StableBar holds mouse movement six points below each display's top edge until the delay expires, out of reach of the band where macOS 27 reveals the menu bar by itself. Moving away cancels the wait. Drag events pass through. This works while menu-bar auto-hide is enabled and StableBar is running; turning the delay off or quitting restores normal pointer behavior. The wait is added before macOS's own reveal animation.
Set bar.menuBarRevealDelay in JSON, including in an included file or a profile. See the menu-bar delay example:
{ "bar": { "menuBarRevealDelay": 2000 } }Settings → General → Native menu bar → Automatically hide the menu bar turns macOS's Automatically hide and show the menu bar on or off, as setup's Top edge and Below menu bar do. Turn it on when the bar sits on the top edge in the menu bar's place, and off to show the menu bar again, for example after moving the bar down with Offset from top. It changes the macOS setting through System Events, so it stays after StableBar quits, and the first time macOS asks to let StableBar control System Events. System Settings → Menu Bar, or Control Center before macOS 26, shows the same setting. Uninstall turns it off when StableBar turned it on.
On macOS 27, while the menu bar hides automatically, a display with a notch shows the menu bar when you click where it would be. StableBar keeps its bar above that area there, so clicks reach the bar, and steps under the menu bar while macOS shows it.
Settings → General → Native menu bar → Always hide keeps the macOS menu bar invisible while StableBar runs, even when the pointer reaches the top edge. Quitting StableBar shows it again. In JSON, set "bar": { "hideMenuBar": true }.
Without it, the menu bar shows on hover as usual. StableBar makes it invisible only while its Control Center and Menu bar items widgets open an item, and shows it again once the item closes.
macOS provides no public API for a custom bar to reserve screen space. Without a tiling window manager, enable Settings → General → Windows and notifications → Keep windows clear of the bar (bar.keepWindowsClear, off by default) and allow StableBar in System Settings → Privacy & Security → Accessibility. StableBar then moves overlapping ordinary windows below the bar and reduces their height when needed to keep them above the Dock. It follows each display's bar height, offset and scale, and waits until you finish dragging before adjusting a window. See the window clearance example.
Native fullscreen windows, minimized windows and dialogs are left alone. Some apps do not expose movable or resizable windows, or enforce a minimum size that cannot fit; StableBar cannot keep those clear. Disabling the option stops adjustments and leaves windows where they are. Revoking Accessibility access pauses adjustments; granting it resumes them. A locally rebuilt, ad-hoc signed app may need to be authorized again.
Leave this option off when another window manager controls your gaps. With AeroSpace, set gaps.outer.top in ~/.aerospace.toml to the bar's panel height (40 by default), plus any bar.offset beyond the menu bar; AeroSpace accepts per-monitor values. yabai users can set external_bar with the same clearance. OmniWM measures gaps.outer.top in its settings.toml from the display's top edge and subtracts the menu bar itself, so set it to the panel height plus bar.offset. A below-bar underline adds its maximum configured gap plus thickness beyond the existing bottom margin. For example, a 38 pt bar with no margin, a 2 pt underline and a 3 pt gap needs 43 pt. With display scale s, round upward to whole screen points: max(ceil(height × s), ceil(height × s − margin + maximum gap × s) + ceil(maximum thickness × s)). StableBar reserves this maximum across states, so focus or mode changes never move windows or resize panels.
On macOS 26, enable Settings → General → Windows and notifications → Keep notifications clear of the bar (bar.keepNotificationsClear, off by default) to move notification banners 16 points below the bar on the display that shows them. It uses the same Accessibility access and can stay on with AeroSpace, yabai or OmniWM. The Notification Center panel and desktop widgets stay where macOS puts them. This depends on Notification Center's Accessibility structure and does not support macOS 14 or 15.
Settings → General → Uninstall → Uninstall… removes StableBar and undoes what it changed on your Mac; search Settings for "uninstall" to find it. Its confirmation lists each step, then StableBar:
- quits any other StableBar that's running. If one doesn't quit, Uninstall stops before changing anything;
- turns off the macOS menu bar's auto-hide when setup or Settings turned it on. Auto-hide that StableBar didn't turn on, for example because you hid the menu bar before installing it, stays on unless you check Turn off the macOS menu bar's auto-hide. Setups finished before Uninstall existed didn't record this, so check it if setup hid your menu bar. Auto-hide that setup turned off stays off;
- turns off Open at login;
- removes the
stablebarcommand that Command line installed, asking for an administrator password when its folder needs one. Astablebarcommand that StableBar didn't write stays; - deletes package and source tokens from the Keychain;
- resets its Accessibility, Calendars and Automation permissions;
- deletes its caches and preferences;
- moves StableBar to the Trash and quits.
Also move ~/.config/stablebar to the Trash is off by default, because that folder holds your configuration, scripts and packages. A configuration elsewhere, opened with --config, stays. If a step fails, for example because you cancel the password prompt, the other steps still run, and StableBar lists what's left to do by hand before you quit it.
When Homebrew installed StableBar, the app stays in Applications: run Uninstall first, then brew uninstall --cask stablebar. brew uninstall --zap --cask stablebar does both: it runs stablebar --uninstall --yes, then also deletes ~/.config/stablebar.
stablebar --uninstall does the same from Terminal; see Command-line controls.
If StableBar is already gone, undo its changes by hand:
- Turn off Automatically hide and show the menu bar in System Settings → Menu Bar, or Control Center before macOS 26.
- Remove StableBar from System Settings → General → Login Items and from Accessibility, Calendars and Automation in System Settings → Privacy & Security.
- Run
sudo rm /usr/local/bin/stablebarif StableBar installed that command, andsecurity delete-generic-password -s StableBaruntil it finds no item. - Delete
~/.config/stablebar,~/Library/Caches/org.stablebar.app,~/Library/Caches/org.stablebar.app.sparkle,~/Library/Caches/StableBar,~/Library/HTTPStorages/org.stablebar.appand~/Library/Preferences/org.stablebar.app.plist.