Skip to main content
← Back to list
01Issue
FeatureClosedSwamp 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◉CLOSED

Closed

10/27/2026, 5:55:22 PM

No activity in this phase yet.

03Sludge Pulse
keeb linked parent of #20089/4/2026, 7:41:19 PM
Editable. Press Enter to edit.

stack72 commented 10/27/2026, 5:55:22 PM

@keeb closing this as replaced. The post-command notice was redesigned: instead of a fire-and-forget check, slow commands poll /api/inbox/summary in the background, and the notice is printed from a local cache. Done so far: swamp-club#3997 (poll policy and per-key cache), swamp-club#4024 (a 404 retries after 24 hours) and swamp-club#4025 (the swamp skill relays the notice; the notice text is pinned in design/surfaces/inbox.md). The PR that turns the notice on will be filed separately.

Sign in to post a ripple.