Pelmet troubleshooting

Short answer: Pelmet is a menu-bar-only app, so it has no Dock icon and no window — after launching, look next to the clock for a ╱ divider and a ‹ chevron. Most reported problems are one of five things: a full menu bar, two copies running, a lost divider, a +N badge people have not seen before, or swift run quitting with its terminal.

Nothing appeared in the menu bar#

Pelmet seeds its toggle and divider right next to the clock — the last spot macOS gives away — so this should be rare.

1. Check the far right of the menu bar, just left of the clock, for ╱ and ‹.
2. Press ⌥⌘B. If the chevron flips between ‹ and ›, Pelmet is running and you were looking in the wrong place.
3. If your bar is packed edge to edge there may be genuinely no room. Quit another menu bar app to free some space, then relaunch Pelmet.
4. Confirm Pelmet is actually running: open Activity Monitor and search for "Pelmet".

Remember there is no Dock icon and no main window. That is normal, not a failed launch.

A number like +3 sits next to the chevron#

That is not an error. It means three menu bar items do not fit beside the notch, so macOS is hiding them — and Pelmet is the only thing telling you.

• Click the count, or press ⌥⌘N, to open the Shelf and see which apps they are.
• Right-click the chevron for ways to make room.
• Or work through the notch guide and the spacing guide.

I cannot find the ╱ divider#

Right-click Pelmet's chevron and choose Reset Divider Position. That puts the divider back next to the toggle, and you can Command-drag it wherever you want from there.

My icons keep rearranging themselves#

Almost always two menu bar managers running at once. Pelmet, Ice, Hidden Bar, Bartender and Vanilla all write status item positions, and two of them will overwrite each other continuously.

Quit all but one. The same applies to two copies of Pelmet: right-click the chevron → Quit Pelmet, or press Ctrl-C in its terminal if you started it with swift run.

Pelmet quit when I closed the terminal#

Expected. Under swift run the app belongs to your terminal session, so Ctrl-C — or closing the tab — quits it.

For a standalone install, either use the released app:

brew install --cask ismatBabirli/pelmet/pelmet

or build a real .app bundle:

brew install xcodegen
xcodegen generate
open Pelmet.xcodeproj   # then build & run with ⌘R

Launch-at-login also needs the bundle — it is the one feature that cannot work under swift run.

The build fails#

Building needs a Swift 6 toolchain: Xcode 16 or newer, or recent Command Line Tools. The app itself runs on macOS 13+, but the compiler requirement is separate from the runtime requirement.

swift --version   # confirm 6.x

If that reports Swift 5, update Xcode or run xcode-select --install.

An update is available but will not install#

An ↑ in the menu bar means an update is ready to review. Pelmet never installs one without your explicit approval — open Settings and confirm.

If checks appear stuck, note that Pelmet only checks every 6 hours, and after a network failure it performs at most three recovery checks before waiting for the next scheduled one. Settings shows the retry state.

One-click access is not working on an item#

One-click access only works with items that publish an action through the macOS Accessibility API. If an item publishes nothing suitable, Pelmet does nothing rather than faking a click — it never synthesises mouse events or moves your pointer.

Check that:

1. The feature is enabled in Settings (it is off by default).
2. Pelmet has Accessibility permission in System Settings → Privacy & Security → Accessibility.

If both are true and the item still does not respond, it is one of the incompatible ones. More on how this works.

Pelmet crashed#

Nothing is uploaded automatically. After a crash, Pelmet offers to open a prefilled GitHub issue that you review and submit yourself — crash data never leaves your Mac on its own.

Something else#

Open an issue on GitHub with your macOS version, your Mac model, and what you were doing. If you are on a notched MacBook, mentioning whether a +N badge was showing is genuinely useful.

The FAQ covers the questions that are not failures, and the features page has the full cheat sheet of every action and its shortcut.