AgentLayer▸docs
Reference

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.

NoticeWhen it showsLevelRun
↑ UpgradeThe installed plugin is newer than the home's recorded baselinenudge; alert at two or more releases behindupgrade
↑ Turn on update trackingThe home has no .state/version.json yetnudgeupgrade
⟳ SyncThree or more days since the last sync, or no sync everhint at 3 days, nudge at 5, alert at 8 or neversync

Each notice carries a few facts beside its title:

NoticeFacts
UpgradeThe two versions and how many releases behind the home is
SyncWhat 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.

LevelWhat it adds
hintA line in the session banner, and the suggested command in an empty prompt
nudgeThe row above the prompt, with a button that acts on it
alertA toast at session start

Where they show

SurfaceWhat it shows
Above the prompt, in the Claude Code terminalThe top nudge or alert as one row, drawn by a mod
The session banner, in the Claude Code terminalHints 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 dashboardThe 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:sync

In the Claude Code terminal, the banner hands nudges and alerts to the row only while the row is known to work:

  1. At each session start the mod fetches notices and stamps .state/notices.json with the plugin version and the date.
  2. While that stamp is from the installed version and at most seven days old, the banner keeps only hints.
  3. After a plugin update, nudges and alerts are back in the banner until the mod runs on the new version.
  4. A mod that stops running hands them back within a week, so a broken row never hides a notice for long.

Acting and snoozing

YouWhat happens
Press the action button, or type the command in a Claude Code session where the notice is showingRecorded as acted: the snooze streak resets
Press TomorrowHidden for the rest of today, back tomorrow
Snooze an unpinned notice five times in a rowIt drops one level, never below hint
Snooze a pinned noticeIt 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=acted

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

On this page