Docs

Try it in your browser · 5 min

Rather press keys than read? The demo walks you through the bar in nine short tracks. Short answers for people below. Agents read llms.txt and the full guide in /skill/guide.md.

Install

With Homebrew:

brew install zalewskigrzegorz/tap/gzyms

brew upgrade gzyms updates it. On a Homebrew install the built-in updater stays off.

Or download the zip from GitHub Releases and move gzyms to Applications. That copy updates itself through Sparkle. Settings → About has Check for Updates… and Automatic updates.

Automatic updates works both ways. Turn it on in a Homebrew install and gzyms warns you that brew and Sparkle can break each other’s update. In the config it is [updates] automatic = true or false, written only when it differs from the default.

gzyms starts at login from the first launch. Turn that off in Settings → General → Login, in System Settings → General → Login Items, or with [bar] start_at_login = false.

You need macOS 26, Accessibility and Full Disk Access. More in Requirements.

For developers

One CLI to rule them all

gzyms notify puts a banner on the bar. Give it --id deploy and the next call with the same id updates that banner instead of adding a new one. It also takes a link, a sound and a screen. --alt-link <url> gives it a second action, and --alt-label "Open in agent" names it on the banner’s hints. Without a label the hint says alt.

gzyms set <key> <value> changes any setting. Every setting lives in ~/.config/gzyms/config.toml, so you can keep it in your dotfiles. The phone push keys are the one exception. They stay in the Keychain, so your dotfiles hold no secrets. There is also gzyms theme, gzyms settings and gzyms report.

gzyms help lists every command, gzyms help notify shows one command’s flags. gzyms completions install turns on tab completion in zsh, bash, fish or nushell.

Plugins are a small script

gzyms plugin new <name> gives you a working plugin folder in ~/.config/gzyms/plugins/. A plugin is a plugin.toml and a command in any language that writes JSON to stdout. Every option you declare shows up as a field in Settings.

Settings → Plugins has one row per plugin: its icon, name, one line, its state (running, error or You changed it) and a switch. A click or Enter opens a side panel with the description, the error, Update, the options and Remove. Esc closes that panel first. Add a plugin, from the catalog or from a folder, sits under the list.

Settings, Plugins: three plugins, each with its state and a switch, and Add a plugin under them

Plugins from the catalog update themselves when gzyms starts, before they run, and your options stay. A plugin you changed is left alone. When the catalog has a newer version, its panel shows Update, which keeps your copy as <name>.bak-<date>. A .gzyms-catalog file in the folder tells your edit from an old copy.

A plugin’s notifications wait on its pill, with a count in the corner and a list at the top of its popup, not under the bell. dd clears that list like any other.

A plugin pill with a count of waiting notifications in its corner

A plugin’s banner can have a second action too: alt_label names it and alt_link is the URL it opens. With a label and no link, gzyms sends notify_alt back to the plugin, so the plugin does the work itself.

A notification’s row ties it to one of the plugin’s rows, so it leaves the list once that row is gone. {"log":"..."} writes a line to the gzyms log. :glyph@colour: in a text draws an SF Symbol in a theme colour or #rrggbb.

The full protocol is in /skill/plugins.md. Or ask your agent to write one for you.

GitHub on the bar

Two plugins from the catalog, both on top of the gh CLI you already have.

gzyms plugin add gh-prs shows your pull requests behind a branch icon, one glyph per state with the number of PRs in it: fix (red cross), merge (green tick), comments (blue bubble) and draft (purple pencil). A PR counts in every state it is in, a draft only as draft. Each row in the popup shows its CI (passed, running, failed or done) and why it waits: a conflict, changes requested, run e2e, comments. A new approval or comment gets a notification.

The gh-prs popup: each pull request with its state, like fix, merge or draft, its CI and why it waits

gzyms plugin add gh-builds watches CI of your pull requests and of the branches you pick: failed in red, running in yellow, passed in green, each PR or branch once. A cancelled check counts as passed. You get a notification when a run fails or ends green.

The gh-builds popup: pull requests and a branch, each failed, running, passed, done or without CI

On both, green means it passed, red means it failed, yellow or peach means it waits.

Both take a normal GitHub search, so org:NAME or repo:OWNER/NAME narrows them. One call every 2 minutes uses about 26 of the 5000 points GitHub gives you an hour.

Your agents on one pill

One pill for every coding agent. Each agent has one row that says what it waits for, like the question it asks or the command it wants to run. Agents that wait for you come first. Idle ones fade to the bottom. You get a ping when one waits for you and when a long run is done. Answer it and the ping goes away by itself. Click a row or the banner to jump to that agent.

While an agent works, a light runs around the pill. Settings → Animations has a breathing border, a glow, a still border or none.

Agents come from sources, and each source has its own switch in Settings → Agents. A new source never breaks the ones you have.

More agents are on the way.

Settings, Agents: tuios with 3 agents and Claude Code, each with its own switch

Log watcher

Point it at a log file and a pattern. When a new line matches, you get a banner, and you can make it armageddon if that line means production is on fire.

Keyboard first

Banners answer the same keys as the rest of the bar: o opens, x lets it go, z snoozes. Some banners have a second action too, then a runs it. When more wait in the queue, n and p walk through them, and so do j and k. The banner shows its keys, so you never have to remember them.

A banner with its keys under the text: o open, x dismiss, z snooze

A named second action shows its name in the hints, like Open in agent.

A banner whose hints end with its second action, Open in agent

A leader key puts a letter over every pill. Then j and k move, Enter opens, x clears, Esc leaves. In an open popup h and l jump to the next pill’s popup. Settings too: h l for tabs, j k and Enter. While the leader is active, the banner countdown pauses, like with the pointer on it.

Command palette

Press the leader, then Space. One search goes through Settings tabs, actions, themes and the notifications in gzyms’s lists. A few letters in order are enough: tst bnr finds Test banner, slack kasia finds Kasia’s Slack message. dnd 1h, dnd 30 or dnd 1h30 turns on Do Not Disturb for that long.

The command palette: so typed, with Sounds, Notifications, Shortcuts and Animations from Settings

Arrows pick, Enter runs, Esc or a click outside closes. On a notification Enter is a click and ⌘Enter runs its second action. The actions: Do Not Disturb on and off, Test banner, Usage HUD, Report a problem, Check for updates, What’s new, Open config.toml, Open the event log, Restart, Quit and Theme followed by its name.

Dock badges on the bar

gzyms reads the red counts from the Dock and puts them on the app’s icon in the bar. So you can hide the Dock and still see that Slack wants you.

The colour says where a count comes from. Red is the app’s own Dock badge, and only the app clears it. Clearing a list in gzyms leaves it alone. Blue is what waits in gzyms’s list. Purple means both, and the number is their sum. It is always the real number up to 99+. More digits get a smaller font, so the icon stays in sight. In the grayscale theme blue and purple come out as much the same grey.

App icons on the bar with counts: red 3, blue 2, purple 13 and 99+

Notifications

Five levels

Info goes away after 6 s, warning after 8 s, error after 12 s. Critical waits until you act. Armageddon turns every screen red and blinks until you click, and it calms down when Reduce motion is on. A rule per app can raise any app to critical or armageddon.

A critical banner with a pink edge: Build finished, Disk almost full Armageddon: the whole screen goes red with one banner in the middle

One at a time

Only one banner is on screen. Up to three wait behind it. They come up in the order they arrived, whatever the level. Only an armageddon cuts in at once, and the one it pushed aside keeps its time left. Anything past that goes quietly into its list. n and p walk the queue.

One banner on screen with three coloured edges under it, one for each banner that waits

Trackpad and pointer

Hand on the trackpad? A two-finger click runs the second action. A long sideways swipe with two fingers lets the banner go. Up and down step through the ones that wait. Rest the pointer on a banner and its hints show. The one under the pointer lights up, and a click runs it. The letters the hints show act right away too, no leader needed.

Snooze that comes back

Snooze a banner for 3, 5, 10 or 30 minutes. It comes back as a gold reminder and stays until you deal with it.

Snoozes survive a restart of gzyms too.

A snoozed banner back as a gold reminder

Nothing gets lost

A banner you ignore waits in its app’s list. Click the app’s icon on the bar to see it. A bell holds things from apps without an icon on the bar. Press x on a banner and it is gone for good.

The lists survive a restart of gzyms.

An app's list with two unread banners and a Clear all button

Do not disturb

Click the moon on the bar and banners go quiet. Everything still lands in its list, so you catch up when you are back. gzyms dnd on [minutes] and gzyms dnd off do the same from a script. Armageddon and meetings still get through, and dnd.breaks_through changes that.

The moon popup: quiet for 45 more minutes, with 1 h, until tomorrow, forever and turn off

Banners from other apps, at once experimental

A Slack or WhatsApp message shows on the gzyms bar in under half a second. gzyms reads the macOS banner through Accessibility the moment it appears and moves the real one off screen, so you see it once, in gzyms.

Apps that show no banner still get through. Their text comes from the Notification Center database a few seconds later, and nothing shows twice. The app’s icon can show the moment macOS logs the delivery, before the text.

A macOS update can break the trick. Then the text comes from the database a few seconds later. Turn it off with Instant banners in Settings → Hacks, or banner_ax = false under [notifications]. Instant app icons is signal = false.

A macOS Focus, like Sleep, Work or Do Not Disturb, holds every banner back on purpose. Then nothing is instant and the text comes from the database about 5 s later. Turn the Focus off and banners are instant again.

Sometimes Notification Center hangs and shows no banners at all. Restart a hung Notification Center fixes that.

Don’t run NotificationNanny at the same time. Both would grab the same banners.

Click opens the original experimental

Click a banner from Slack, WhatsApp or Calendar and you land where the original notification would take you: the thread, the chat, the event. Not just the app.

This is a trick, not an API. macOS gives a notification’s details, like the thread, only to the app that sent it. So gzyms presses the macOS banner while it is still up. Once it is gone, gzyms opens Notification Center with 🌐 N, moves it off screen so nothing flashes and presses the same notification there.

A macOS update can break this. Then gzyms quietly opens just the app.

To make both tricks work:

  1. In System Settings → Notifications → the app, keep Allow notifications, Desktop and Notification Center on and turn Play sound off. gzyms plays the sound. Lock Screen, Badge, grouping and summaries don’t matter.
  2. At the top of Notifications set Show previews to Always or When Unlocked, once. Apps on Default follow it.
  3. In System Settings → Keyboard → Keyboard Shortcuts → Mission Control, keep Show Notification Center (🌐 N) on. gzyms presses it to reach a notification whose banner is already gone.
  4. Give gzyms Accessibility and Full Disk Access.

You don’t have to click through it alone. Settings → Apps says how many apps need a change in macOS, and Set up step by step opens their pages one by one. A small window next to System Settings shows what to click, and gzyms moves on by itself once you did. Skip this app or Stop when you like. Closing System Settings ends it too. Turn off your tiling window manager, like HyprMac, while you set up.

Set up step by step: Messages, app 2 of 4, with Desktop to tick and Play sound to turn off

Mail is the exception. macOS doesn’t let you set anything for Mail, so a Mail banner opens just Mail. Apps without a sound switch, like Xcode, Safari or Raycast, get no warning about sound.

It’s on by default. Turn it off with Open the exact chat in Settings → Hacks, or open_original = false under [notifications] in config.toml. Then a click opens just the app. To read an app’s macOS settings, gzyms needs Full Disk Access and either Open the exact chat or Instant banners on.

Rules per app

Every app that sent something is in Settings → Apps. Drag one in, or use Choose app…, to set it up before it sends anything. Click an app and pick what its notifications do:

More sets each part on its own: Banner, Sound, Count on the bar, Phone, the level (normal, critical, armageddon) and Skip it. A mix shows as Custom. Phone works with any preset. In the config it is [notifications.apps."<app id>"], with skip = true for Off. Remove from list forgets the app and its rule. It comes back when it sends something again.

Under the presets sits a copy of the app’s page in macOS. What needs a change pulses, with what to do. Open in System Settings opens the real page, and the copy follows your clicks live.

Settings, Apps: Slack needs 2 changes in macOS, its presets, and its macOS page with Notification Center to tick and Play sound to turn off

Same notification, several apps

When two or more apps send the same notification, or almost the same, within about 10 s, gzyms tells you once per pair of apps: Apps send the same notification. A click opens Settings → Debug. Under Same notification, several apps you see which apps, how often and when last, with Open in macOS for each app’s notification settings, Forget, and a Tell me about them switch.

gzyms drops nothing by itself. You decide which app goes quiet. The anomaly log keeps only the app names, never the text.

Settings, Debug: Make report, and two groups of apps that sent the same notification, each with Forget and Open in macOS

Away from the Mac

When a banner sits untouched for 5 minutes, gzyms sends it to ntfy, Pushover or any webhook that takes JSON. By default only critical and armageddon go out, or any app you mark. There is no gzyms app for the phone. You need ntfy or Pushover there.

The address and the Pushover keys are secrets, so gzyms keeps them in the macOS Keychain and never in config.toml. Set them in Settings → Notifications, or pipe them in so they stay out of your shell history: pbpaste | gzyms set notifications.phone.pushover_token.

Meetings

A calendar event with a call link (Meet, Zoom, Teams, Slack huddle, Webex, Whereby, Jitsi) gets a banner that does not go away on its own. It comes 3 minutes before the start, and calendar.points changes that. A snooze brings it back at the start and 3 minutes in. Before you join you can check your camera, mic and speaker. Calendar access is optional.

The mic and speaker you pick there become the macOS default. That helps only when your call app uses the system default device. If Zoom or Teams has its own device set, you pick it there, not in gzyms.

The bar

The gzyms bar in Mocha Neon: workspaces, CPU, battery, network, sound, mic, do not disturb and the clock

The file shelf

Drop a file under the notch and it waits there.

The drop zone under the notch: Drop here to keep it on the shelf, then Let go to keep it on the shelf

Drag it out and it moves there. The shelf is empty again. Hold ⌥ while you drop and it copies instead.

The shelf with three files waiting and a Clear the shelf button

⌃⌥M mutes the mic

⌃⌥M mutes your mic in every app. You can change the keys in Settings. The mic pill shows the input level, so you see it worked, and the audio pills show which device you use.

Your own device icons

Two pills with the same laptop? In Settings, Audio, pick a device and choose its icon from a grid, or type any SF Symbol name. A tag of up to 3 letters next to the icon tells two speakers of one kind apart. From the terminal: gzyms set audio.icons."MacBook Pro Microphone" mic.

Devices you never want

That virtual mic you tried once, the TV speaker, your iPhone. Ban them and they stop showing up. In Settings, Audio, pick the device and turn on Hide, or set [audio] banned = ["exact device name"] in the config.

A banned device is gone from the sound and mic popups on the bar and from the lists before a meeting, and the keys that switch devices skip it. If macOS picks it on its own, you still see it, greyed out with a tick. Ban the iPhone mic or speaker and its Continuity camera leaves the meeting preview too.

Like the picker before a meeting, this changes the macOS default only. A call app with its own device set does not care.

System pills

CPU with the top processes, memory, network up and down with a Tailscale badge and a warning when a proxy is still on, battery with time left and a note when the charger is too weak, caffeine that survives a restart of gzyms, and what is playing now.

The network pill with a Tailscale badge and a PX warning for a proxy that is still onThe battery pill at 78 percent with a warning: it still drains 14 W, the charger is too weakThe CPU popup with the processes that use the mostThe caffeine popup: awake for 1 h 45 more, with 30 min, 1 h, 2 h, 4 h and forever

Nothing jumps

Numbers have a fixed width, so a changing value never pushes the rest of the bar. Old data dims instead of pretending. If you take Accessibility away, the bar shows ⚠ instead of a wrong count. A change to Full Disk Access shows after gzyms restarts, and Settings → Permissions has the Restart button for that.

The bar without Accessibility: a warning sign and dashes instead of numbers

Notch and monitors

On a screen with a notch the banner grows out of the notch and never spills onto a monitor above. On other screens it sits under the bar. It shows on the screen you work on, or the one you name with --screen.

How a banner arrives

Settings → Animations picks how a banner comes in. Drop, the default, slides down from under the edge with a spring. Icon drops the app’s icon first and the text unrolls from it. Notch grows out of the notch. Unroll is the old entry. Pop grows from 85% as it shows up. Fade blends in where it stands. Speed is slow, normal or fast.

Animations off means nothing moves at all. With it on and macOS Reduce motion on, every style turns into a fade, unless you turn off Follow macOS Reduce motion. In the config it is [appearance] banner_entry and animation_speed, or gzyms set appearance.banner_entry pop.

The countdown is a thin line under the banner’s text.

Settings, Animations: animations on, follow Reduce motion, entry Drop, speed Normal

Settings

Click the gzyms logo on the bar and Settings opens on the tab you used last. Click it again, or press ⌘,, and it closes. ⌘Q in Settings quits gzyms. About has Check for Updates…, Automatic updates, Learn Gzyms, which opens this site’s browser demo, and Quit Gzyms. It also thanks Sparkle, NotificationNanny and TOMLDecoder.

gzyms sits where the macOS menu bar was. Need File or Edit of the app you use? Hold ⌘ with the pointer on the bar and gzyms steps aside. Move the pointer off the bar and it comes back.

Tiling or not

Workspaces come from OmniWM, HyprMac, AeroSpace or Mission Control, whichever runs. OmniWM tells gzyms about a switch at once. Without a tiling manager the bar shows one desktop with your Dock apps.

Sounds

Every kind of event can have its own sound: the gzyms tone, a macOS sound or your own file. Letting a banner go has one too, Tink by default. Change it in Settings or with [sounds] dismiss in the config.

Settings, Sounds: one sound each for message, success, fail, waiting, armageddon and dismiss, with a play button

Bug reports

Something broken, or an idea? Use GitHub Discussions, not issues. Settings → Debug → Make report… puts a zip on your Desktop and opens a new discussion. Attach the zip there. gzyms report makes the same zip from the terminal.

The zip has the log, the config and the versions. It leaves out the text of your notifications, tokens like Pushover or ntfy, and personal names: calendars, audio devices, log watcher files. Your home folder shows as ~ and sites from browser tabs as <site>.

Ask the bar what it sees

A banner doesn’t show, or a key does nothing? Run gzyms debug before you guess. The running bar answers, since it holds Full Disk Access and Accessibility. One fact per line, never the text of a notification. --json gives one flat object.

Without a topic you get notifications and keys. Two things are flagged on their own: a key tap that macOS turned off, and Secure Input held for a minute or more, since then no key reaches gzyms.

No telemetry

No analytics, no crash reporter, no usage stats, no ads. gzyms sends nothing home on its own.

A bug report or the log zip from gzyms report leaves your Mac only when you send it yourself. Phone pings go only where you point them: ntfy, Pushover or your own webhook.

The one request gzyms makes by itself is the update check, and only on a copy from GitHub Releases with Automatic updates on.

gzyms is open source under the MIT license, on GitHub.

Hacks

Some parts of gzyms ride on private macOS APIs or on tricks. They work today and a macOS update can break them. Settings → Hacks lists every one: what it does, its state right now, and the one switch or button it needs.

Settings, Hacks: every hack with one line on what it does, its state right now and the button it needs

Media keys for the music player only

The browser leaves the media keys to the music player.

A browser with a video in some tab takes the play and pause keys from your music. Turn that off in the browser and the keys go to the music player again.

  1. Firefox, Zen, Vimma and other Firefox-based browsers: open about:config and set media.hardwaremediakeys.enabled to false. It works at once, no restart. Settings → Hacks shows each profile it finds and whether the pref is off.
  2. Chrome and other Chromium browsers: start them with --disable-features=HardwareMediaKeyHandling. We haven’t tested this one.

Browser tabs in the music pill

Tabs that play show in the music pill. Needs Tampermonkey and the script.

With the pref off, macOS no longer sees the browser’s videos. A small userscript tells gzyms instead. Every tab with video or audio shows in the music popup with its own play, pause, next and Go to. One tab is one entry: what plays now, or else what played last.

Calls are not media. Meet, Zoom, Teams and any other WebRTC stream or camera stay out, and so do muted autoplays and previews.

  1. Install Tampermonkey. Violentmonkey works too, but there Go to can’t switch to the tab.
  2. In Settings → Hacks turn on Browser tabs in the music pill, or set browser_media = true under [hacks].
  3. Press Open script and then Install in the page Tampermonkey shows.

After you update gzyms, install the script again from http://127.0.0.1:47100/gzyms-media.user.js, so it matches the new version.

gzyms listens on 127.0.0.1:47100 only, and only for its own script. It can play, pause, skip and focus what the script reported, nothing else.

A tab you just reloaded needs one click on the page before Play from gzyms works. Browsers block autoplay until you touch the page. Pause always works.

Music.app off the media keys

A running Music.app takes the media keys. Quit it when you play from Spotify.

Once the browser lets go of the keys, Music.app takes them even when it plays nothing. The same goes for any other player. Settings → Hacks has the Quit button.

What plays

Reads what plays from macOS for the music pill.

macOS keeps Now Playing in a private framework, and since macOS 15.4 only Apple-signed programs may read it. gzyms loads a tiny reader into /usr/bin/perl, which is one. If that fails, it falls back to osascript, which sees Now Playing only. If Apple closes both doors, the music pill goes away and the log says why.

The music popup: Spotify playing with controls, a YouTube tab and a podcast under it

macOS lets one app take commands: the one that is Now Playing. Music.app and Spotify also take them through AppleScript. Every other app in the popup only has Go to.

In the music popup j and k move between sources and the one you are on opens. a plays or pauses it, x skips, ↩ goes to it.

Instant banners

The banner text shows at once, not a few seconds later.

gzyms reads each macOS banner through Accessibility the moment it shows and hides the real one off screen. During a macOS Focus there are no banners to read, so the text comes from the database. A macOS update can break it too. More in Banners from other apps.

Restart a hung Notification Center

Restarts it when it shows no banners. Nothing is lost.

The switch needs Instant banners and Instant app icons.

Sometimes apps send notifications and Notification Center shows no banner. Restart runs killall NotificationCenter and macOS starts it again. Nothing in it is lost, the screen flickers for a second. The button works even with the switch off, and it also sits next to the No banners warning in Settings → Permissions.

The switch, or nc_auto_restart = true under [notifications], does it by itself, at most once in 10 minutes and once per hang. If no banner shows after the restart, gzyms warns you and stops. It is off by default. Each restart lands in the anomaly log as nc_restart or nc_restart_failed. A Focus that holds banners back does not count as a hang.

Open the exact chat

A click opens the right chat or thread, not just the app. Set each app in Apps.

gzyms presses the macOS banner while it is up, or its row in Notification Center, opened off screen, once the banner is gone. More in Click opens the original.

Instant app icons

The app’s icon shows at once, the text follows.

gzyms follows the macOS notification log, so an app’s icon shows the moment it sends something, before the text. A macOS update can change the log. Then the icon just comes with the text.

Notifications from other apps

Needs Full Disk Access.

Slack, Mail and the rest also reach gzyms through the private notification database of macOS. It is the backup for banners gzyms could not read, and for apps that show none. Reading it needs Full Disk Access. A macOS update can move it.

FAQ

Why can’t I approve my agent from gzyms?

Because saying yes to something you haven’t read is a bad habit. If you click “approve” all day, your agent harness isn’t set up for you. Ask for approval only when there is really something to check.

Still want it? Ask your agent for a plugin. Every gzyms banner has two actions built in.

Requirements

macOS 26 on Apple Silicon. gzyms needs Accessibility (banner keys, Dock badges) and Full Disk Access (notifications from other apps). Calendars is optional. A wizard walks you through it on first launch, and again when the bar shows a warning sign. Settings → Permissions shows every grant any time.

The setup wizard: Accessibility granted, Full Disk Access missing with a button to open System Settings

Builds are signed and notarized by Apple, so gzyms opens like any other app. This is 0.0.1, so expect rough edges. Tell us in Discussions when something breaks.