Skip to main content
← Back to list
01Issue
FeatureOpenSwamp CLIPublic
AssigneesNone

Relationships

↑ child of #2008

#2023 feat(cli): tell operatives they have swamp-club notifications waiting

Opened by keeb · 9/4/2026

Filed against swamp (the CLI). Parent: the swamp-club product-nurture epic. Depends on the swamp-club unread-count endpoint.

What ships

A one-line notice after a command finishes, when the operative has unread swamp-club notifications:

You have 3 unread notifications on swamp-club.com — see them at
https://swamp-club.com/inbox

Follow the update-notice pattern exactly

UpdateNotificationService already solves this problem in this codebase, and the shape is the requirement, not a suggestion:

  • getNotification() reads local state only — a cache file, no network. The rendered line costs zero milliseconds.
  • backgroundCheck() is fire-and-forget, refreshes the cache only when stale, catches everything, and writes a timestamp even on failure so the cooldown is respected while offline.
  • Never break the CLI for it. Every path swallows.

New: src/domain/notifications/notification_notice_service.ts and src/infrastructure/persistence/notification_cache_repository.ts, mirroring AuthNudgeRepository (~/.config/swamp/, atomic write, {} on any read failure).

Gates, all of which already exist for the auth nudge

  • outputMode === "log" only. Never with --output json — a stray line in a JSON stream breaks every programmatic consumer.
  • Authenticated only. No key, no check, no line, no network call. The auth nudge already covers the logged-out case and must not be shown alongside it.
  • Throttled. Refresh at most every 4h (proposed); show at most once per 24h even when the count is unchanged, so a persistently unread inbox does not nag on every command.
  • Suppressible. swamp config toggle plus a SWAMP_NO_NOTIFICATION_CHECK environment escape, matching how update checks are opted out of.
  • Silent in CI and non-TTY. Same detection the other notices use.

The count is a hint, not a truth

The cache can be up to 4h stale, and that is fine — the line says how many were waiting, and the inbox is authoritative. Do not add a synchronous refresh to make the number exact; that trades the entire latency property for a correctness the operative does not need.

Verification

  • Unit: a fresh cache shows nothing; a cache with unread > 0 inside the window shows the line; a stale cache triggers exactly one background refresh; a network failure still writes the timestamp.
  • --output json emits nothing extra, asserted on the raw stdout bytes.
  • Manually: log in, generate an unread notification from swamp-club, run any command, see the line. Log out, run again, see nothing.
02Bog Flow
◉OPEN○TRIAGED○IN PROGRESS○SHIPPED

Open

9/4/2026, 7:40:56 PM

No activity in this phase yet.

03Sludge Pulse
keeb linked parent of #20089/4/2026, 7:41:19 PM

Sign in to post a ripple.