Notchnull

---
name: notchnull
description: Reshape the user's MacBook notch with NotchNull. Use when the user asks to add a widget or panel to the notch, show something beside the notch (build status, deploys, timers, alerts), change how the notch looks or behaves (colors, size, motion, tabs, which activities appear), design a whole notch or a look of their own, package their notch to share or apply one somebody sent them, undo a change to the notch, update NotchNull, notify them through the notch from a script, or change NotchNull's own source for things files cannot do.
---

# NotchNull

NotchNull is a notch app built to be rebuilt by its user and their agent. Almost everything
is a file under `~/.notchnull` that the app watches and applies while it runs:

| Path | Whose | What it is |
|---|---|---|
| `settings.json` | the user's | Every setting. Two-way: edit it and the notch changes; the Settings window rewrites it. |
| `widgets/<id>.json` | the user's | One widget per file: a command that produces data, and a view tree that draws it. |
| `presets/<id>.json`, `themes/<id>.json` | the user's | Presets and looks of their own. Listed in Settings › Setup beside the shipped ones. |
| `scripts/` | the user's | Longer logic for widget commands, if you need it. |
| `backups/<time>-<why>/` | the app's | Copies of everything above. See "Undo" below. |
| `settings.reference.md` | the app's | Each key, its type and range, generated by the running app. Authoritative. |
| `status.json` | the app's | What the app made of the files: settings errors, each widget's state, data and error, and whether an update is waiting. |
| `bin/notchnull` | the app's | CLI: show activities, open tabs, push data, apply and export recipes, back up, update, render the notch to a PNG. |
| `skill/` | the app's | This skill. **Rewritten on every launch**: anything you save inside it is gone the next time the app starts. |

Files that are the app's are regenerated; never put the user's work there. Files that are the
user's are never rewritten by an update, and that is the promise to keep: whatever you make for
them goes in `widgets/`, `presets/`, `themes/` or `scripts/`.

This skill folder ships starting points. Copy one out and change the copy:

| Folder | What it holds |
|---|---|
| [examples/](examples/) | Working widgets (CI with a wing, open PRs, disk, todo, world clock). Each has a `description`. See [examples/README.md](examples/README.md). |
| [presets/](presets/) | `minimal`, `balanced`, `complete`: how much the notch shows. The same files as the Setup page in Settings, each with a rendered `.png`. |
| [themes/](themes/) | Twelve looks (`graphite`, `plum`, `ocean`, `terminal`, `frost`, `brutal`, …): only the `look` section. |

The body is a notch or a floating island: `look.shape` is `"auto"` (island when the screen shows
no notch, such as a MacBook at a resolution that leaves it out), `"notch"` or `"island"`, and the
`island.*` keys set what the idle pill shows, its size, its distance from the top and its satellites.
Sizes accept any value up to the window the notch draws in; see settings.reference.md.

## The loop

Work like this every time, so you never guess whether something worked:

1. **Read first.** `cat ~/.notchnull/status.json` and the file you will change. For settings, read
   `settings.reference.md`; never invent keys.
2. **Keep a way back** before a change that touches many things at once (several settings
   sections, replacing widgets): `notchnull backup before-<what>`. A single widget file or one
   setting does not need it.
3. **Edit the file.** Write whole, valid JSON. The app reloads on save; there is no restart.
4. **Check status.** Read `status.json` again. A widget in `"state": "error"` has an `"error"`
   string that says what is wrong (bad JSON, missing `view`, command exit code and stderr).
   `settingsErrors` lists unknown keys and bad values.
5. **Look at it.** `~/.notchnull/bin/notchnull render /tmp/notch.png --tab widgets` draws the
   notch with the user's real files (commands run once) and exits. Open the PNG and judge it
   the way the user will see it. `--closed`, `--tab <name>` and `--activity '<json>'` render other
   states; `--demo` fills music, agents and the rest with sample data.
6. **Iterate** until the render looks right, then tell the user what changed, where the file is
   and how to undo it.

The CLI works without PATH changes at `~/.notchnull/bin/notchnull`. `render`, `backup`, `backups`,
`restore`, `recipes` and `export` work on files and do not need the app running; every other
command talks to the running app and says so if it is not open.

## What to reach for

- **A panel with live data** (PRs, CI, server health, a counter, a checklist): a widget file.
  See [references/widgets.md](references/widgets.md). Start from a file in [examples/](examples/).
- **Something beside the notch while a condition holds** (CI failing, deploy running): a widget
  with a `wing` block, which appears while `when` is true and goes away on its own.
- **A one-off notification from a script or at the end of a task**:
  `notchnull show "Deploy finished" --subtitle "vercel · production" --symbol checkmark.circle.fill --tint green`.
  Progress: re-run with the same `--id` and a new `--progress 0..1`, then `notchnull hide <id>`.
- **Look, size, motion, tabs, which activities appear**: `settings.json`.
  See [references/settings.md](references/settings.md). For "make it quieter" or "show me
  everything", start from a preset; for "make it pink" or "rounder", start from a theme.
- **A look or a whole notch the user can come back to, or give to someone**: a recipe file.
  See [references/recipes.md](references/recipes.md). It covers designing one from a brief,
  saving it so Setup lists it, exporting the user's notch as one file and applying a file
  somebody sent.
- **Scripts and other programs**: the CLI and the local HTTP API.
  See [references/cli-and-api.md](references/cli-and-api.md).
- **Anything files cannot express** (a new view type, a new tab, a new system integration,
  different animation physics, a redesigned settings page): change the app itself. It is open
  source Swift. See [references/source.md](references/source.md). Ask the user before rebuilding
  and replacing their installed app; a build of your own stops receiving the app's updates
  until they install a release again.

## Undo

The app copies the user's files to `~/.notchnull/backups/` the first time a new version runs, and
`notchnull apply` and `notchnull restore` copy them before they change anything.

```sh
notchnull backup before-redesign   # a copy now; prints its folder
notchnull backups                  # newest first: 2026-10-01T09-10-22-before-redesign
notchnull restore                  # the newest one back; or: notchnull restore <id>
```

`restore` puts back `settings.json` and every file the backup holds, and leaves files made since
where they are. If the user says "put it back the way it was", this is the answer; do not
reconstruct their settings from memory.

## Updates

`notchnull update` says whether a newer release exists; `notchnull update install` installs it
and relaunches the app. An update replaces the app only: nothing under `~/.notchnull` that is the
user's changes, and their hooks stay connected. Ask before installing, since the notch restarts
and macOS asks for Accessibility again afterwards. `status.json` → `update` has the same facts
without a network call.

## Taste

The notch sits at the top of every screen, all day. Keep what you add calm and legible:

- One idea per widget. A number with a label, a short list, a gauge. Not a dashboard.
- Use the named colors (`accent`, `green`, `red`, `orange`, `secondary`, …) so the widget follows
  the user's theme; reserve red and orange for things that need attention.
- Short text. Wings hold a symbol and a few characters per side.
- Refresh no faster than the data changes. `refresh` has a 2 second floor; most things want 30–300.
- Commands run in the user's login shell with a timeout. Keep them read-only unless the user asked
  for a button that does something, and never put secrets in widget files.

## Safety

- Only edit files under `~/.notchnull` unless the user asked you to change the app's source.
- `settings.json` accepts partial files: keys you leave out keep their value.
- Do not delete the user's widgets to "clean up"; set `"enabled": false` if one should stop.
- A recipe from someone else can carry widgets, and widgets run shell commands. `notchnull apply`
  lists them and installs none until it is run with `--widgets`. Read each command, tell the user
  what it does, and add `--widgets` only when they agree.
- The API token in `~/.notchnull/token` is a secret. Do not print it into chat or commit it.