Skip to content

Latest commit

 

History

History
157 lines (86 loc) · 41.1 KB

getting-started.md

File metadata and controls

157 lines (86 loc) · 41.1 KB

Getting started

Install and set up

Open StableBar.dmg, drag StableBar to Applications, then open the app. Setup starts with a tour: a felt-pen line swells into a glass bar under StableBar's name, drawn like the website over colors that shift slowly from day to dusk, 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. Five steps then ask where the bar goes, let you pick a preset, a theme, an appearance and the clock, choose window clearance and Open at login, ask for the permissions that bar needs, and let you try the bar itself; when the intro asked where the bar goes, setup starts at the second step, and Back returns to the first. Your bar previews your choices right away; window and notification clearance changes wait for Finish setup. 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 Run setup again in Settings → Help. The intro plays only the first time, before you finish or skip setup, and not with Reduce Motion on: then setup starts at its first step, where Watch the intro plays it.

Setup follows System Settings → Accessibility → Display → Reduce motion as you change it, without reopening setup. With it on, each step fades out before the next fades in, without blur or movement. The selected theme comes into view immediately, and cards and buttons keep their highlights without growing or shrinking. Progress dots and permission rows update without movement, and the completion window opens and closes without scaling.

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 asks Make it your menu bar., like the intro. Replace the menu bar, the larger choice and the one setup recommends, puts StableBar on the top edge and hides the macOS menu bar; Keep the menu bar, under it, puts StableBar below the menu bar, which stays visible. Neither is picked until you choose one, whatever the bar's placement, and Continue waits until the macOS menu bar hides or shows to match your choice; answering the intro's question counts. Either choice also resets a custom bar.offset to 0, so set it again afterwards if you use one. Hiding or showing the menu bar needs Automation, which macOS asks for right there, and Continue waits until you allow it. Replace the menu bar while it already hides, or Keep the menu bar while it shows, needs no Automation. When an active profile sets bar.offset or bar.belowMenuBar, this step names it with a button to edit it: setup saves your choice as the default, but what the profile sets still applies over it, so the bar may not end up where you chose, even once Continue moves on. Presets, the clock and what the bar needs depend on this choice, so it comes first. On a short screen, a step that doesn't fit scrolls above Continue. Skip setup closes setup without saving.

The fourth step lists the permissions the bar you chose needs, each with Allow…: Accessibility (Device Control and Data Access from macOS 27) always, because the app menus, the Apple menu, Menu bar items, Workspaces and window clearance depend on it; Automation, to let StableBar control System Events, when setup has changed or still needs to change the macOS menu bar setting; and Calendars when your bar has Meetings. Once macOS has asked, Automation and Calendars offer Open Settings… instead; Accessibility keeps Allow…. Setup asks for nothing before this step, apart from Automation in the first: picking a preset with Meetings doesn't open the Calendars dialog. The live bar still works while setup is open, so clicking its Apple logo without Accessibility asks for it, as it does any time. Each turns to Allowed as soon as macOS allows it, and Continue waits until all of them have. Keep the menu bar instead drops the need for Automation. Set up Meetings later drops it for Calendars when only the preset's Meetings asks: a calendar widget already on your bar still needs Calendars. If one is still missing at the last step, it shows above Finish setup, which waits for it.

When your chosen bar has Workspaces on macOS Spaces, the permissions step also checks Desktop shortcuts. It shows how many desktops cannot be switched from the bar yet and Open Keyboard Shortcuts…; choose Mission Control there and enable Switch to Desktop N for each desktop you need. It shows Ready when all are on and names desktops beyond macOS’s shortcut range. This check never holds up Continue or Finish setup: you can turn the shortcuts on later in Settings → General → Access. It re-checks when you return to StableBar, open the page or add or remove a desktop, without polling or changing your shortcuts.

The second 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. From the starter bar on the top edge, 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 adds Battery on the Notch theme, and appears only while the bar is on the top edge and a connected display has a notch, since that black bar blends into the notch only there; Everything adds Workspaces, Meetings, System and Battery on Catppuccin. On a Mac without a battery, such as a Mac mini, presets leave Battery out and don't show its icon. Below the macOS menu bar, which already shows the Apple menu, the app's menus, the clock and its menu bar items, presets build on the starter with Workspaces, System and Sound instead, without a clock, and leave out Menu bar items. On a bar you have changed, a preset adds its widgets to yours. 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. A chosen Notch preset stays available to deselect, even if the notched display disconnects or you move the bar below the menu bar.

Choosing another preset, or clicking the chosen one again, changes only its widgets, theme and appearance: your clock, window and notification clearance, Set up Meetings later and Open at login choices stay, and the clock and Meetings choices apply whenever the bar has those widgets.

Under the presets, Found on your Mac lists the Store packages the Store suggests for tools on your login shell's PATH or apps on your Mac, such as AI usage and Quick ask when claude or codex is there, and Homebrew outdated when brew is. A package already on your bar isn't listed, and the row is hidden when the Store can't be reached. Nothing is downloaded until you click a package. These packages run commands, so clicking one downloads it and opens the same review as Add here in Edit Bar in Place; Add to bar there installs it and puts its widgets on the bar setup shows, and Back leaves it out. Click an added package again to take it off. Choosing a preset keeps the packages you added, and, like your other choices, they are saved when you finish setup. Skipping setup leaves them installed in Settings → Store, but not on your 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. Tab and Shift-Tab reach the placement, preset and theme tiles even with macOS Keyboard navigation off; the focused tile has a ring, and Space chooses it. VoiceOver reads each tile's name and selected state, with widget names for presets. Light, Dark and Automatic, beside the heading, control the bar's appearance, and the cards follow it; Clock next to them switches between 24-hour and 12-hour, and shows only while your bar has a clock. Setup shows your current appearance and clock, and Keep current leaves them untouched; the placement is always the first step's choice. The bar shows the effect of active profiles, and the last step names any profile that still controls a setting, each 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. Below the menu bar, each display's bar starts right under that display's own menu bar, whatever its height (bar.belowMenuBar). Earlier versions placed it there with a fixed bar.offset instead, which a taller menu bar partly covers; the first time StableBar starts while the menu bar shows, it turns such an offset into "belowMenuBar": true with an offset of 0, in your configuration and in each screen setup's own bar. Choosing Replace the menu bar in setup turns on Automatically hide and show the menu bar, so the menu bar no longer covers the bar; Keep the menu bar turns it off, and so does Put it at the bottom, which puts the bar on the bottom edge (bar.position); later, Automatically hide the menu bar in Settings turns it on or off. Setup makes this change through System Events, so it first checks that StableBar may control System Events: the first time, macOS asks, and setup waits for your answer. Without that access, setup leaves the menu bar as it is and offers Open Automation Settings…; turn on System Events under StableBar in System Settings → Privacy & Security → Automation, come back, and setup hides or shows the menu bar. 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 offers Keep windows clear of StableBar and, on macOS 26 or later, Keep notifications clear of StableBar, and gives separate guidance when it detects AeroSpace, yabai or OmniWM; when Workspaces uses macOS Spaces, the fourth step checks the Desktop shortcuts instead. See Keeping windows clear of the bar. Its Open at login switch shows whether StableBar opens at login. Once you choose Replace the menu bar with StableBar in an Applications folder, the switch starts on, since macOS then keeps the menu bar hidden even while StableBar isn't running; turning it off keeps StableBar from opening at login. Outside an Applications folder, the step offers Move to Applications instead of the switch.

In Finishing touches, Keep windows clear of StableBar starts on when setup detects no window manager running, and off when it detects one running. This also applies when you run setup again. An explicit bar.keepWindowsClear value in your configuration, including an included file or an active profile, keeps its value. You can turn the switch off before Finish setup; choosing another preset keeps this default. It uses the Accessibility access setup already requires, and starts moving windows only once you finish. Skip setup saves nothing. Outside setup, omitting bar.keepWindowsClear still leaves window clearance off.

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. These widgets use native providers and run no scripts.

Workspaces uses AeroSpace, yabai, OmniWM or Rift when one is installed and running: AeroSpace and yabai on your login shell's PATH, OmniWM as its app or omniwmctl on the PATH, Rift as rift-cli on the PATH. When setup picks the source, or you add a Workspaces widget, StableBar keeps the source your configuration names while that one is installed, and otherwise takes the first one installed and running, in that order; a running bar keeps its source and doesn't switch on its own. When the first launch finds none, for example because your login shell's PATH arrives late, its starter uses macOS Spaces. Setup looks for a manager once, when it opens: until a setup finishes, reopening setup looks again, as long as that starter is unchanged. yabai needs its signals, OmniWM needs Enable IPC, and Rift needs each Space turned on. Without any of them, Workspaces shows your macOS Spaces, which switch desktops through the Switch to Desktop shortcuts and need Accessibility access to do it.

Finishing touches checks the connection when the previewed bar has yabai or OmniWM Workspaces. For yabai it offers the missing refresh signals to copy, or a reminder to load saved signals with yabai --restart-service. For OmniWM it asks you to open the app first if needed, then points to Enable IPC if the connection is unavailable. Choose Check Again after making the change; returning to StableBar checks again while that step is open, keeping the last result and any expanded signals visible. Slow or unavailable checks stay unverified. Checks stop when you leave the step and never run on a timer. You can finish setup with any of these results and follow the linked guide later.

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 Apple menu, the frontmost app's menus, Sound, the clock and Menu bar items. Below the menu bar, the starter shows Workspaces, System and Sound instead, since the menu bar right above it shows the rest: choosing Keep the menu bar in setup turns an unchanged starter into this one, and Replace the menu bar turns it back. On a bar you have changed, including with widgetOverrides, widgetOrder or a screen's layout, in the file or in a profile, setup keeps your widgets; below the menu bar it removes only unchanged copies of the starter's Apple menu, app menus, clock and Menu bar items, and none when your configuration uses includes or packages, whose files can refer to them. The menus need Accessibility access; until you allow it, a warning icon takes the app's menus' place, except while setup is open, and clicking the Apple logo asks for access. Setup's permissions step lists Accessibility, which clearance and menu widgets use, and Calendars when a calendar widget needs it, with their status and a permission action or System Settings link. Allow… for Accessibility, in setup or in Settings → General → Access, opens System Settings → Privacy & Security → Accessibility (Device Control and Data Access from macOS 27) with a panel at the bottom of its window. Drag the StableBar tile from the panel into the list and confirm with Touch ID or your password; if StableBar is already in the list, turn its switch on instead. The panel closes once access is allowed, when you quit System Settings, or with its close button. Status updates when you return from System Settings, or within a second for Accessibility, and the bar shows the app menus. A newly chosen Meetings widget stays off your bar during the tour until you allow Calendar access in the permissions step. Allow it, or choose Set up Meetings later, which saves that widget turned off so Finish setup doesn't wait for Calendars. 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. Setup never asks for Screen Recording: a menu bar item shown as in the menu bar asks for it when you choose As in the menu bar, and Settings → General → Access lists it while your bar has one. Nor does it ask for Location: a wifi provider asks for it the first time it updates, to show the network's name, and Settings → General → Access lists it while your bar has one.

Outside Applications, Finishing touches → Open at login → Move to Applications moves StableBar and relaunches it at the same setup step, with your choices and configuration file kept. It uses /Applications when writable, otherwise ~/Applications, without asking for an administrator password. It copies the app into Applications, then moves the original to the Trash once it confirms the new copy is running. An original on a read-only disk image or running with App Translocation stays where it is. An older copy in Applications needs your confirmation and goes to the Trash only once the new copy opens; the same or a newer version offers Use the One in Applications instead, which opens that copy and leaves the original where it is. Quit a destination copy that is already running before trying again. If moving fails, the row explains why and offers Show in Finder. After a successful relaunch, Open at login is selected; registration still waits for Finish setup. If macOS reports that the new copy could not open and it is not running, setup returns to the original with Open at login left off. If saving setup’s choices fails, StableBar still reopens the original and explains how to continue. If launching times out or cannot be confirmed, both copies stay in place; a note explains how to open StableBar from Applications with Finder. If the Applications copy has changed or opened during recovery, every copy stays in place and the note lists their locations. A previous copy kept for manual recovery is named StableBar (previous).app beside the Applications copy, or StableBar (previous 2).app and so on if that name is taken. If it cannot be renamed, the note names its hidden location: press ⇧⌘. (Shift-Command-Period) in Finder to show it. These recovery copies stay until you choose what to keep. StableBar only tries to move leftover previous copies from completed moves to the Trash on its next launch from Applications. While setup is open, Settings directs you back to Finishing touches to move the app. Setup can resume for 15 minutes after the move.

Until Finish setup, your choices are temporary changes, like command-line changes without --persist: the bar shows them, but the file is unchanged. Window and notification clearance keep following your bar as it was when setup opened, including earlier unsaved command-line changes, so no window moves for a choice you might skip; they follow setup's choices, including where the bar goes, once you finish. Skip setup (Esc) puts your bar back as it was; once you have changed something, it first asks Skip setup?, where Keep Setting Up (Return or Esc) takes you back. Permission buttons act immediately through macOS. Open at login requires the app to be in Applications. If macOS requires Login Items approval, setup shows the remaining action. Setup opens by itself at launch until you finish or skip it. After that, Getting Started… in the menu-bar icon's menu and Run setup again in Settings → Help open it. While a skipped setup was never finished, Settings → General → Access also shows Finish setting up.

Download a release

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 stablebox/tap/stablebar.

First launch

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, where it starts with Workspaces, System and Sound. 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…, Get Widgets…, Share My Bar…, Settings… or Quit StableBar; the menu-bar icon also offers Hide Bar. Get Widgets… opens Settings → Store. 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, or, with bar.belowMenuBar (Below the menu bar in Settings → Bar → Bar → Placement), right under each display's macOS menu bar; a display whose menu bar hides keeps the bar on its top edge. bar.offset moves the bar further down from there. It hides on native fullscreen Spaces, and when you hide it.

With "position": "bottom" (Edge → Bottom in Settings → Bar → Bar → Placement), the bar sits on the bottom edge of each display instead, and bar.offset moves it up from that edge. It counts from the display's edge, not from the Dock: with the Dock at the bottom and always shown, the Dock covers the bar, so hide the Dock, move it to a side, or raise the bar with bar.offset. At the bottom, popups and tooltips open upward, belowBar underlines sit on the bar's top side, the notch positions place widgets as on a display without a notch, and belowMenuBar has no effect. A screen setup or kind of screen can set its own position in its bar, like offset. 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.

Hide the bar

Choose Hide Bar in the menu-bar icon's menu, or run StableBar --hide, to put the bar away on every display, for example while you present or watch a video. Show Bar or StableBar --show brings it back, and StableBar --toggle switches between the two; see Command-line controls. The bar stays hidden until you show it or quit StableBar, and your configuration file doesn't change.

To hide it while an app is in front, set bar.hidden in a profile:

{ "name": "tv", "when": { "app": "com.apple.TV" }, "configuration": { "bar": { "hidden": true } } }

The bar shows only when neither Hide Bar nor the configuration hides it, so Show Bar doesn't bring back a bar that bar.hidden hides. While the bar is hidden, its popup closes, providers set to whenVisible pause as they do when none of their widgets is visible, and window and notification clearance leaves windows where they are.

Share your bar

Choose Share My Bar… in the bar's right-click menu or the menu-bar icon's menu, or the button above the bar's preview in Settings → Bar, to share your bar. The right-click menu uses that screen's bar; the menu-bar icon uses the screen under the pointer, and Settings the screen it shows. As with Settings, StableBar appears in the Dock while the panel is open, and clicking its Dock icon brings the panel back when Settings isn't open. The panel has no title bar and floats above other windows: drag its background to move it, and close it with × at the top right, Esc or ⌘W. A larger panel shows a larger preview, over a blur of the image. It makes an image of your bar for social media: the bar as it is now, with its real data and the time, at its place over your desktop wallpaper. It needs no screen-recording permission.

Pick a screen in the menu at the top left:

  • This screen: the bar as it is on the screen you shared from, at that screen's width. On a screen with a notch, Notch in the same menu draws it and lays the bar out around it; turn it off to leave the notch out.
  • 13″ MacBook Air (1470 points wide), 14″ MacBook Pro (1512) or 16″ MacBook Pro (1728): the bar laid out for that MacBook's screen at its default size, with your laptop screen's layout and look. Notch draws the notch and lays the bar out around it; turn it off for a MacBook without one. A narrower screen gives a narrower image, where the bar shows larger.

And a shape in the toolbar under the image:

  • Bar: the bar across the screen's width, on a strip of wallpaper, at twice the screen's width in pixels.
  • 16:9 (3200 × 1800), 1:1 (2160 × 2160) or 4:5 (2160 × 2700): the top of your desktop, or its bottom with a bar at the bottom, scaled to the image's width. When the image is taller than the screen, the wallpaper fills it.

The image carries StableBar's badge, its logo, name and website, in the bottom-right corner, or the top-right one with a bar at the bottom, so it sits on the wallpaper beyond the bar. To leave it out, point at the image and click × on the badge, or turn off StableBar Badge in the menu at the top left. + Badge on the image, or the same menu, brings it back. StableBar remembers your choice for the next image.

The toolbar's buttons copy the image to the clipboard as PNG, save it to a file, open the bar link, and Share (or Return) opens the macOS share menu for AirDrop, Messages, Mail and more. A dynamic or aerial wallpaper that has no still image is replaced with StableBar's own backdrop.

The link button opens your bar link above the toolbar: anyone with StableBar can try your look and your built-in and Store widgets on their own bar, and keep the widgets they like. Copy Link copies it. What it shares opens a list of your look and each widget the link carries, with the settings a Store widget takes along, and under Stays on your Mac, the widgets it leaves out and why, such as a script widget, a custom provider, or a package from a folder or a private source, and the Store settings it doesn't carry: secrets and free text. Click the link button again, or press Esc, to close it.

Updates

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, download or installation is already active, and stop making requests when automatic checks are off. They keep running while an update waits to be downloaded, so a newer release replaces it in the popup, and the tile goes away when no update is left, for example after switching back to the Stable track. 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, each with its author's GitHub name when the release notes give one. 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. The popup also shows Enjoying StableBar? Star it on GitHub above the download button until you dismiss it with ×. When the GitHub CLI gh is on your login shell's PATH and signed in, clicking it stars StableBar on github.com as that account, which its tooltip names, and says thanks; the line doesn't come back, and it doesn't appear at all once gh sees that account has starred StableBar. Without gh, or when the star fails, clicking it opens the GitHub repository, where you can star StableBar yourself, and the line stays until you dismiss it. Star on GitHub in Settings → Help works the same way, even after you dismiss the line, and reads Starred on GitHub once gh sees the star. Check for Updates… in the menu-bar icon's menu checks right away, also while an update waits to be downloaded, and so does Check now in Settings → General → Updates when no update is waiting. 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.

Delay the native menu bar

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 (Device Control and Data Access from macOS 27).

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 } }

Hide the native menu bar

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 Replace the menu bar and Keep the 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 turning on Below the menu bar in Settings → Bar → Bar → Placement. It changes the macOS setting through System Events, so it stays after StableBar quits. The first time, macOS asks to let StableBar control System Events; without that access, the toggle stays as it is and Open Settings… opens Privacy & Security → Automation, where you turn on System Events under StableBar. Back in StableBar, the change applies. 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.

Keeping windows clear of the bar

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; setup turns it on when no window manager runs) and allow StableBar in System Settings → Privacy & Security → Accessibility (Device Control and Data Access from macOS 27). StableBar then moves overlapping ordinary windows below the bar, or above a bar at the bottom, and reduces their height when needed to keep them clear of the Dock and the menu bar. It follows each display's bar height, offset and scale, and waits until you finish dragging before adjusting a window, including when you drag it back to a position StableBar already corrected. 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, menu bar included, so set it to the panel height plus bar.offset, plus the menu bar's height when the bar sits below a menu bar that shows. With Rift, set top under [settings.layout.gaps.outer] in ~/.config/rift/config.toml. For a bar at the bottom, set the bottom gap instead, such as gaps.outer.bottom in AeroSpace, 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.

When AeroSpace, yabai or OmniWM runs and one of its windows starts under the bar, Settings → General → Windows and notifications and setup's last step warn about it and give the setting for your bar, such as outer.top = 40 under [gaps] in ~/.aerospace.toml. For AeroSpace it names the file AeroSpace reads, ~/.aerospace.toml or aerospace/aerospace.toml in XDG_CONFIG_HOME (~/.config by default). When the window manager's configuration file exists, a button such as Open aerospace.toml opens it in your app for plain text. StableBar reads the windows' frames through Accessibility when you open that section or reach that step, and again when you click Check Again. It never changes the window manager's configuration.

On macOS 26 or later, 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: setup hides the switch there, and Settings shows it disabled with Needs macOS 26 or later. A configuration shared with a newer Mac can still set bar.keepNotificationsClear; older macOS versions keep the saved value without moving notifications.

Uninstall

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 stablebar command that Command line installed, asking for an administrator password when its folder needs one. A stablebar command that StableBar didn't write stays;
  • deletes package and source tokens from the Keychain;
  • quits. Once it has quit, it resets its Accessibility, Screen Recording, Calendars and Automation permissions, deletes its caches and preferences and moves StableBar to the Trash. These steps wait so the bar doesn't keep running without its permissions or its app.

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. StableBar lists what's left to do by hand and stays whole until you click Quit StableBar, which finishes the rest, unless another StableBar kept running: then quit that one and uninstall again. If StableBar can't start the steps that wait for it to quit, it lists them too, to do by hand. If a step fails after StableBar has quit, an alert lists what's left to do by hand.

When Homebrew installed StableBar, the app stays in Applications: run Uninstall first and click Quit StableBar, then run 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:

  1. Turn off Automatically hide and show the menu bar in System Settings → Menu Bar, or Control Center before macOS 26.
  2. Remove StableBar from System Settings → General → Login Items and from Accessibility (Device Control and Data Access from macOS 27), Screen Recording, Calendars, Automation and Location Services in System Settings → Privacy & Security.
  3. Run sudo rm /usr/local/bin/stablebar if StableBar installed that command, and security delete-generic-password -s StableBar until it finds no item.
  4. Delete ~/.config/stablebar, ~/Library/Caches/org.stablebar.app, ~/Library/Caches/org.stablebar.app.sparkle, ~/Library/Caches/StableBar, ~/Library/HTTPStorages/org.stablebar.app and ~/Library/Preferences/org.stablebar.app.plist.