notchnull git:20260929.848f657A

Immutable. This exact content never changes and is served at /api/v1/blob/268dfeaf191d736b.

---
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), 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 | What it is |
|---|---|
| `settings.json` | Every setting. Two-way: edit it and the notch changes; the Settings window rewrites it. |
| `settings.reference.md` | Each key, its type and range, generated by the running app. Authoritative. |
| `widgets/<id>.json` | One widget per file: a command that produces data, and a view tree that draws it. |
| `status.json` | What the app made of your files: settings errors, each widget's state, data and error. |
| `bin/notchnull` | CLI: show activities, open tabs, push data, render the notch to a PNG. |

This skill folder (also copied to `~/.notchnull/skill`) ships starting points. Copy one and
change it rather than writing from nothing:

| 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.

A preset or theme is `{ "name", "summary", "order", "settings": { …partial settings.json… } }`.
Apply one with `notchnull settings set "$(jq -c .settings presets/minimal.json)"`. To make a new
one for the user, write a file in the same shape; the Setup page lists every file in these folders
the next time it opens, after the app's bundled copy is rebuilt (see references/source.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. **Edit the file.** Write whole, valid JSON. The app reloads on save; there is no restart.
3. **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.
4. **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.
5. **Iterate** until the render looks right, then tell the user what changed and where the file is.

The CLI works without PATH changes at `~/.notchnull/bin/notchnull`. `render` does 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.
- **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.

## 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.
- The API token in `~/.notchnull/token` is a secret. Do not print it into chat or commit it.