NotchNull

Any notch you want. Just ask your agent.
A MacBook notch you rebuild by asking. Tell the Claude Code or Codex on your Mac what it should be: widgets, colors, animations, tabs, even its Settings page. It edits plain files or the source, renders the notch to check its work, and the change is live.

Website · Download · Build your notch · Built in · Install · Privacy

Why

Other notch apps ship their notch. NotchNull ships yours.

Every setting is a file, every widget is a file, and your agent can read them, write them and look at the result. When files are not enough, the app itself is open source, and the same skill explains how to change it. Think of it as the Arch Linux of notches: small, fast and built out of pieces you can see.

It is free, open source and runs entirely on your Mac.

Start with a preset

The first launch opens Settings › Setup: pick a shape (classic notch, floating island, or automatic), then Minimal, Balanced or Complete (everything, the way it ships) and one of twelve looks. None of it is fixed. Each preset and look is a JSON file, and after you pick one, your agent can change anything.

Island mode. Set a MacBook to a resolution that leaves the notch area out (or use a screen without one) and NotchNull floats as an island inside the menu bar: a clock pill with two satellites that grow into a music card and Control Center on hover. Every activity and the panel work the same. Settings › Style › Shape forces either one.

Build your notch

Your agent can change all of it:

Ask for	What it changes
“A card with today’s Stripe revenue.”	A widget file in widgets/.
“A red dot by the camera while prod is down.”	A widget’s wing.
“Plum, a pink accent, rounder corners.” / “Slower, and no bounce.”	look and motion in settings.json.
“Only Home and Widgets, and a wider panel.”	Tabs, Home rows, sizes, which activities appear.
“Add a section to Settings with my widgets’ options.” / “A radial gauge.”	The Swift source, which the skill maps out.

Install the skill from Settings › Build (one click each for Claude Code and Codex), then ask:

Use the notchnull skill: add a widget with my open pull requests, and show a red wing beside the notch while CI is failing.

The agent works in ~/.notchnull, which the app watches and applies while it runs:

Path	What it is
widgets/<id>.json	A widget: a shell command whose output becomes data, and a view tree that draws it (values, gauges, bars, sparklines, lists, buttons, badges). Hot-reloaded on save. An optional wing slides it out beside the camera while a condition holds.
settings.json	Every setting, synced both ways with the Settings window. settings.reference.md next to it lists each key, generated by the app.
presets/, themes/	Presets and looks of your own. They show up in Settings › Setup next to the ones that ship, and no update touches them.
backups/	Copies of the files above, taken the first time a new version runs and before a preset or a shared notch is applied. notchnull restore puts one back.
status.json	What the app made of your files: each widget's state, data and error, and any bad settings. Agents read it instead of guessing.
bin/notchnull	The CLI. notchnull show "Deploy finished" --symbol checkmark.circle.fill --tint green, notchnull widget ci data '{…}', notchnull settings set '{…}', notchnull apply ocean, notchnull export my-notch.json.
skill/	The agent skill: widget format, settings, CLI and local API, and how to change and rebuild the Swift source.

There is an example of everything in skills/notchnull: working widgets in examples/ (CI with a wing, open PRs, disk, todo, world clock; Settings › Build › Examples adds one in a click), the Setup presets in presets/, the looks in themes/ and the full references in references/.

The piece that makes it work is notchnull render out.png --tab widgets: it draws the notch with your real files to a PNG, so the agent sees what you will see and fixes it before it tells you it is done.

A notch can be handed to someone else as one file. notchnull export my-notch.json writes your look, layout and widgets; notchnull apply my-notch.json applies one on another Mac after backing up what is there. Widgets run shell commands, so they are listed and only installed with --widgets, and a file like this can never change what happens to your downloads.

Scripts can use the same surface: every CLI command is a call to a local API on 127.0.0.1:47823 that needs the per-install token in ~/.notchnull/token.

Built in

AI agents

• Claude Code and Codex usage limits as % left, reset time and a pace forecast that warns when you will run out before the reset.
• Other coding plans found on your Mac, with the same bars: GLM Coding Plan (Z.ai), Kimi Code, MiniMax, OpenCode Go and GitHub Copilot. Keys are picked up from OpenCode, Claude Code's settings, the Copilot sign-in or environment variables.
• Live Claude Code, Codex and opencode sessions, detected automatically from their transcripts and local stores.
• A glowing Needs you alert the moment an agent asks for permission or asks you a question, with the project, the terminal it runs in and the question itself. Several agents waiting at once stack in one banner, a row each. A Done banner shows the agent's final message. Click to jump to the right terminal.
• Tokens used today with an hourly chart, including opencode (agent • model shown; no rate limits — BYO keys).

Now playing

• Any player, including videos in your browser: artwork, controls, scrubbing, output volume. Live streams get a LIVE badge.

Ambient activities — slide out of the notch as wings, then tuck back in

• Volume and brightness HUD (optionally replaces the system one).
• Charging, low battery, and battery color that follows Low Power / High Power mode.
• Devices: Bluetooth headphones and speakers with AirPods battery, keyboards, mice, controllers, ESP32 / Arduino boards with their serial port, drives, displays, AirDrop.
• Downloads with progress, screenshots, timers (presets or any HH:MM:SS), meeting countdowns, a hello on login.
• The notch steps aside on a display while a fullscreen app covers it, each display on its own (Settings › General).

Downloads that clean themselves

• Each new download asks, right in the notch, how long to keep it: 10 minutes, an hour, a day, a week, 30 days, or Keep. Then it goes to the Trash, with Undo.
• NotchNull follows the file itself, so renaming it is fine and moving it out of Downloads keeps it. Overdue files go when the Mac wakes or the app starts.
• Remember an answer per file type ("Always .dmg"), tag counting-down files as Temporary in Finder, and see every deadline in the Downloads tab.

Panel

• Home, Recent (what the notch told you about lately: finished agent runs, downloads, screenshots, timers, meetings; tap one to open it), Agents, Controls (Wi-Fi, Bluetooth, dark mode, keep awake, lock, sleep, sound output, brightness), Widgets, Downloads, Tray, Clipboard history (encrypted, real file previews).
• ⌃⌘V opens Clipboard from any app, Raycast style: type to search, arrows to pick, Return pastes (⌘Return only copies). Change or turn off the shortcut in Settings.
• Drag a file toward the notch to park it, copy it or AirDrop it.

Yours to shape

• Notch and panel sizes, roundness, black / tinted / glass body, accent (any color, or match the macOS accent), animation speed and bounce, tab order, Home rows and which activities appear. All of it in settings.json too.

Install

1. Download NotchNull.zip from the latest release and move NotchNull.app to Applications.

2. NotchNull is not notarized by Apple yet, so the first launch needs one extra step. Either right-click the app → Open → Open, or run:

   xattr -dr com.apple.quarantine /Applications/NotchNull.app

3. Grant only what you want to use; every permission is optional:

Permission	Used for
Accessibility	Replacing the system volume/brightness HUD; pasting from the Clipboard shortcut
Calendars	The "Up next" meeting row
Bluetooth	Headphone and device connections
Camera	The optional mirror tab (off by default)

Requires macOS 14 or later on a Mac with a notch. On other displays NotchNull draws a virtual notch.

Update

From 1.4.0 on, NotchNull updates itself: Settings › About › Updates shows when a release is newer than yours and Update installs it (notchnull update install does the same from a terminal). It downloads NotchNull.zip from this repository's release, checks it against the checksum GitHub publishes, checks that it is NotchNull, that version, with an intact signature, then replaces the app and relaunches.

Nothing you made is touched. Your settings, widgets, presets and looks live in ~/.notchnull and are copied to ~/.notchnull/backups the first time a new version runs; notchnull restore brings the newest copy back. The Claude Code hook and the opencode plugin, if you enabled them, are refreshed on launch, so there is nothing to reconnect.

macOS asks for Accessibility again after an update (HUD replacement, pasting from Clipboard), because each build is signed on its own rather than with an Apple developer certificate. Coming from 1.3.x, install 1.4.0 by hand once, the same way as above.

Privacy

Nothing is collected. Your Claude plan's usage is read from Anthropic's API with the Claude Code login already on your Mac, other coding plans are read with the keys your tools saved, and once a day NotchNull asks GitHub whether a newer release exists (Settings › About turns that off). Clipboard history is encrypted at rest. See PRIVACY.md for every file NotchNull reads and writes.

Build from source

Requires Xcode 16 or the Swift 6 toolchain.

git clone https://github.com/Obed0101/NotchNull.git
cd NotchNull
swift test                     # unit tests
scripts/build-app.sh           # builds build/NotchNull.app
scripts/build-app.sh --install # and copies it to /Applications

.build/debug/NotchNull --snapshots <dir> renders every state of the notch to PNGs with demo data. python3 scripts/render-images.py (needs Pillow) turns those renders into the pictures in this README, on a wallpaper, and the transparent shots on the website.

How it works

• Window: a borderless panel above the menu bar, click-through except where the notch is.
• Now playing: macOS 15.4+ restricts the private MediaRemote framework to Apple-signed processes, so a tiny bridge (MediaBridge/) runs inside /usr/bin/perl and streams the system's now-playing state as JSON.
• Platform: FSEvents watches ~/.notchnull; widget commands run in your login shell with a timeout and capped output; the CLI and local API share the hook server's token. notchnull render runs in its own process and never touches the running app's files.
• Downloads cleanup: each download is tracked by a bookmark, so renames follow it; only files still inside Downloads are ever trashed, always to the Trash.
• Agents: Claude Code and Codex write session transcripts under ~/.claude and ~/.codex; opencode keeps sessions in ~/.local/share/opencode/opencode.db; NotchNull tails/reads them. The optional hooks (Settings → Agents) add instant approval alerts and back up your settings first; the optional opencode plugin adds instant running/approval/finished events.
• Devices: IOKit notifications for USB (serial ports are found from the drivers under each device), IOBluetooth, NSWorkspace for volumes, quarantine records for AirDrop.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md.

License

GPL-3.0. You can use, study, change and share NotchNull; derived apps must stay open under the same license.

README wallpaper: aerial photo of foggy mountains by Sam Ferrara on Unsplash.

Claude is a trademark of Anthropic. OpenAI and Codex are trademarks of OpenAI. Their logos appear in the app only to identify each provider; NotchNull is not affiliated with or endorsed by either company.