Mentions and notifications system for issues
Opened by stack72 · 4/17/2026· Shipped 4/20/2026
Summary
swamp-club currently has no mechanism for notifying a user when they are mentioned (e.g. @username) in an issue body or comment. Mentions are effectively silent — the mentioned operative has no way of knowing they were tagged unless they happen to revisit the issue.
Desired behavior
When an operative is mentioned in an issue (body or comment), they should receive a notification. The delivery channel should be:
- Email, if we have a verified email address for the operative, or
- In-app inbox notification inside swamp-club as the fallback (and ideally always, regardless of email)
Ideally both channels are supported and user-configurable, with the in-app inbox as the always-on baseline and email opt-in/opt-out per user.
Scope suggestions
- Parse
@usernamementions from issue body and comment markdown at write time - Resolve mentions to operatives (by username) and skip unknown handles
- Create an inbox notification record per mentioned operative with a link back to the issue/comment
- Send an email (via the existing Resend integration) when the mentioned operative has a verified email and hasn't disabled mention emails
- Add an "Inbox" / "Notifications" surface in the UI with unread counts and a way to mark as read
- Respect self-mentions (don't notify the author of the issue/comment when they mention themselves)
- De-duplicate: if the same operative is mentioned multiple times in one comment, send one notification
Out of scope (for a first cut)
- Mentions on non-issue surfaces (manual pages, extensions, etc.)
- Team/collective mentions (
@collective-name) - Push notifications / mobile
- Digest emails
Why this matters
Mentions are the primary way contributors pull each other into a conversation. Without notifications, @mention is a dead feature — users type it expecting the other person will see it, and they don't. This is a meaningful gap for any collaborative issue tracker.
Shipped
Click a lifecycle step above to view its details.
Sign in to post a ripple.