Notices
The one list of upkeep only you can start, how loud each item gets, and where every surface shows it.
A notice is a reminder of upkeep only you can start: applying an upgrade, running a sync. The plugin works out one list of notices from the home's state whenever something asks, and every surface draws from that list. Nothing is stored except what you did with each notice and one stamp.
What becomes a notice
In priority order. Upgrade comes first because an upgrade ends in a sync, or asks for one after the restart, so doing it first answers both.
| Notice | When it shows | Level | Run |
|---|---|---|---|
| ↑ Upgrade | The installed plugin is newer than the home's recorded baseline | nudge; alert at two or more releases behind | upgrade |
| ↑ Turn on update tracking | The home has no .state/version.json yet | nudge | upgrade |
| ⟳ Sync | Three or more days since the last sync, or no sync ever | hint at 3 days, nudge at 5, alert at 8 or never | sync |
Each notice carries a few facts beside its title:
| Notice | Facts |
|---|---|
| Upgrade | The two versions and how many releases behind the home is |
| Sync | What is waiting to compile (session logs, inbox items, new feedback) and, above the prompt, how long a sync usually takes on this machine |
The sync notice stays quiet until the first-session welcome has run. Its age is counted in calendar days in your timezone.
Levels
Each level adds to the one before it.
| Level | What it adds |
|---|---|
| hint | A line in the session banner, and the suggested command in an empty prompt |
| nudge | The row above the prompt, with a button that acts on it |
| alert | A toast at session start |
Where they show
| Surface | What it shows |
|---|---|
| Above the prompt, in the Claude Code terminal | The top nudge or alert as one row, drawn by a mod |
| The session banner, in the Claude Code terminal | Hints only, once the row has proven it runs. Until then, every notice, colour-coded by level |
The session banner, everywhere else (the VS Code panel, the desktop app, claude -p, Codex) | Every notice with the command that acts on it, as plain text |
| The dashboard | The last-sync age, from the same stamp the sync notice reads. sync writes it when it refreshes the dashboards |
The row above the prompt
The row has the notice's icon in the level's colour, its title, its facts, and two buttons.
↑ Upgrade ready · 1.0.0 → 1.0.1 · 1 release behind [ Upgrade now ] Tomorrow
⟳ Brain 5 days behind · 3 session logs · 2 in the inbox · ~6m12s [ Sync now ] Tomorrow- One row at a time. When more than one notice applies, the row shows the first and a
+1 more. - Tab runs it. The top notice's command is the Tab suggestion, so an empty prompt plus Tab runs it. An alert raises a toast at session start that says so.
- It steps aside while the command it started is running, then comes back recomputed once that turn ends.
- It refreshes on its own every 30 minutes.
The session banner
⟳ Sync: Brain 5 days behind · 3 session logs · 2 in the inbox · run /agentlayer:syncIn the Claude Code terminal, the banner hands nudges and alerts to the row only while the row is known to work:
- At each session start the mod fetches notices and stamps
.state/notices.jsonwith the plugin version and the date. - While that stamp is from the installed version and at most seven days old, the banner keeps only hints.
- After a plugin update, nudges and alerts are back in the banner until the mod runs on the new version.
- A mod that stops running hands them back within a week, so a broken row never hides a notice for long.
Acting and snoozing
| You | What happens |
|---|---|
| Press the action button, or type the command in a Claude Code session where the notice is showing | Recorded as acted: the snooze streak resets |
| Press Tomorrow | Hidden for the rest of today, back tomorrow |
| Snooze an unpinned notice five times in a row | It drops one level, never below hint |
| Snooze a pinned notice | It keeps its level however often you snooze it. Upgrade and sync are both pinned |
What you did lives in .state/notices.json: snooze streaks, what is snoozed through which date, and the row's stamp. A hand-edited value of the wrong type is ignored, so a typo can't hide a notice for good.
From the terminal
bun "<plugin root>/src/cli.ts" notices # every notice that applies now, as JSON, top first
bun "<plugin root>/src/cli.ts" notices record sync --outcome=snoozed # or --outcome=actedrecord prints the updated list too, and --outcome=acted also lifts a snooze. This is the same call the row makes, so a script or another surface can show notices the way the row does. See CLI.
Mods
The plugin's in-process module for Claude Code. Instant commands, queued prompts, this conversation's reports, repo manuals on first touch, sync progress, and notices above the prompt.
Upgrades and releases
How the upgrade skill reconciles a home after a plugin update, what each version asks of you, and the format maintainers write.