NotchNull

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 with the actual reset time, a daily budget and an optional forecast based on locally observed usage by hour. Forecasts appear only after sufficient coverage and are estimates, not provider warnings.
• 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.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗