Skip to content
Hushtop

Troubleshooting

Last updated: 8 October 2026

In short
Most problems come down to a permission, a setting, or an app Hushtop can’t see yet. Find the section that matches what you see. If you’re still stuck, email [email protected] with your version from Settings › About.
On this page
  1. macOS won’t open Hushtop
  2. Macs and displays without a notch
  3. The notch doesn’t open or show anything
  4. The ears cover menu bar icons
  5. A feature stopped working after an update
  6. Music doesn’t show, or controls are missing
  7. Lyrics don’t show
  8. Claude Code or Codex agents don’t show
  9. Meetings or reminders are missing
  10. License problems
  11. Start over with default settings
  12. Still stuck

macOS won’t open Hushtop#

The first time you open Hushtop, macOS asks whether you want to open an app downloaded from the Internet. Click Open; Get started has the steps. If macOS says instead that Hushtop is damaged or can’t be checked, the download was likely cut short or didn’t come from hushtop.app. Delete it and download Hushtop again from this website.

If Hushtop says This copy of Hushtop was changed, its code signature no longer matches. This can happen when an app is copied through a chat or cloud service. Download Hushtop again, install it from the disk image and open it from Applications.

Macs and displays without a notch#

On a display without a notch, Hushtop shows a floating island at the top of the screen instead. It works the same way: hover or click to open it.

  • To turn the island on or off, use Settings › General › Displays › Floating island on displays without a notch. It’s on by default.
  • To choose where it shows, use Show the notch on: Built-in display or Main display.

If the island is off and no connected display has a notch, for example with the lid closed on an external display, Hushtop shows nothing until you open the lid or turn the island back on.

The notch doesn’t open or show anything#

  • Click the Hushtop icon in the menu bar. If it says Resume notch, the notch is paused; click it.
  • During full-screen video, Movie mode keeps the notch out of the way. Turn it off in Settings › Notch & ears › While something plays › Movie mode.
  • Check how the notch opens in Settings › Notch & ears › Opening: on hover or on click.
  • Alerts stay quiet while Quiet mode is on. Turn it off from the menu bar icon or with ⌃⌥Q.

The ears cover menu bar icons#

Turn on Settings › Notch & ears › Ears › Fit to the menu bar. The ears then size themselves to fit beside your menu bar icons. It needs Accessibility, because it reads where the menu bar items are. You can also set the Ear width yourself.

A feature stopped working after an update#

After an update, macOS may ask for a permission again. Open Settings › Privacy: each permission turns green once it’s allowed. For one that isn’t, use its button to open the right place in System Settings and allow Hushtop there.

  • Screen Recording, used for copying text from the screen, only takes effect after Hushtop reopens. Click Relaunch Hushtop when it asks.
  • Permissions stick only when Hushtop runs from the Applications folder.

Music doesn’t show, or controls are missing#

Media shows what’s playing in Spotify, Apple Music and browser tabs. What works where:

  • Play, pause, previous and next work for all of them.
  • Shuffle and repeat work only in Spotify and Apple Music. For music in a browser tab, those buttons don’t show.

If nothing shows:

  1. Start playing a song. Media shows “Nothing playing” until something plays.
  2. If Media offers Allow control of Spotify or Allow control of Music, click it and allow it when macOS asks.
  3. If you said no before, turn Hushtop back on for that app in System Settings › Privacy & Security › Automation.

If Spotify and Apple Music show but browser tabs never do, your copy of Hushtop may have been changed. Install it again from the original disk image.

Lyrics don’t show#

Lyrics are off until you turn them on in Settings › Music › Media › Lyrics. They come from LRCLIB: Hushtop sends only the song’s title, artist, album and length, and saves the lyrics on your Mac.

  • Hushtop shows synced lyrics only. A song LRCLIB has no synced lyrics for shows none.
  • Looking up a new song needs an internet connection.
  • Wrong lyrics? In the Lyrics tab, click Not this version? and pick another one.
  • Out of sync? Use −0.5 s and +0.5 s in the Lyrics tab. Hushtop remembers it for that song.
  • To see the current line beside the notch, turn on Settings › Notch & ears › While something plays › Lyrics in the ears.

Claude Code or Codex agents don’t show#

Hushtop finds agent sessions by reading the files Claude Code and Codex already keep on your Mac. It reads them for token counts and activity only; conversation text is never stored.

  • Claude Code: ~/.claude/projects, or the folder in CLAUDE_CONFIG_DIR.
  • Codex: ~/.codex/sessions, or the folder in CODEX_HOME.

Sessions show up as they work. Usage appears after your first Claude Code or Codex session. If yours don’t show:

  1. Run the setup check: Settings › AI agents › AI setup check › Open in Notch…. It checks hooks, the statusline and logs for each agent, and fixes what it can. You see each change first, and you can undo it.
  2. If you set CLAUDE_CONFIG_DIR or CODEX_HOME, set it in your login shell’s settings. When Hushtop can’t read them, Settings › Integrations says so and uses the default folders.
  3. Click Reindex in Settings › AI agents › Agents to read the session files again.

No card when Claude Code needs you? That card comes from a Claude Code hook. Connect it in Settings › Integrations › Claude Code hooks › Connect…, and check that Show a card when Claude Code needs you is on in Settings › AI agents. On a Mac managed by your company, hooks may be locked; the row then says Can’t connect automatically and why.

No Claude limits? The 5-hour and weekly limits come from Claude Code’s statusline. Connect Claude Code statusline in Settings › Integrations; your own statusline keeps running. A project that sets its own statusline overrides it in that project. Codex limits come from its session files, with nothing to connect.

Meetings or reminders are missing#

Calendar asks for the Calendars and Reminders permissions the first time you open it. If you said no, allow Hushtop in Settings › Privacy. To choose which calendars it reads, use Settings › Calendar › Meetings › Calendars.

License problems#

Activating, moving to a new Mac and lost keys are covered in Your license.

Start over with default settings#

Open Settings › General, then Transfer or Reset, and click Reset All Settings…. Every preference goes back to its default and the agent session history is cleared. Usage data, notifications and Keychain items stay. Export your settings first with Export… if you might want them back.

Still stuck#

Open Settings › About and click Copy Version, then email it with a short description to [email protected]. You can also send feedback.