avifenesh/telegram-digest

Telegram Digest Manager

Manages intelligent notification batching and delivery to Telegram forum topics.

Trigger

Activate when:

• Running a scheduled digest cron job
• User asks about Telegram notifications, notification preferences, or what to send/stop sending
• User says "mute X", "stop sending Y", "change notification frequency", "what did I miss"

Context

Cairn routes notifications to Telegram forum topics:

• #github - GitHub PRs, issues, releases, stars, CI
• #feed - HN, Reddit, npm, crates, RSS, SO, DevTo
• #approvals - approval gates, patches, reviews
• #agent - orchestrator actions, subagent spawns, tasks
• #system - errors, config, deployment, skills
• #digest - daily/weekly summaries

Instead of sending every event immediately, batch events per source and post periodic summaries to the appropriate topic.

Digest Generation

When running a digest for a source (e.g. "github"):

1. Fetch unread events: cairn.readFeed(source: "<source>", unreadOnly: true, limit: 50)
2. If no events, skip (don't post empty digests)
3. Summarize into a concise digest:
   • Group by type (PRs merged, issues opened, releases, etc.)
   • Include counts and key items
   • Keep under 500 chars for readability
   • Use markdown formatting (bold titles, bullet lists)
4. Post to the appropriate Telegram forum topic
5. Mark events as read: cairn.markRead(id: "all") or individual IDs

Digest Format Examples

GitHub digest:

**GitHub - last 3h**

PRs: 2 merged (#405, #409), 1 open (#410)
Issues: 1 new (performance regression in search)
CI: all green
Stars: +3 (total: 142)

Feed digest:

**Feed - last 6h**

HN (2): "Show HN: Agent OS" (142 pts), "Go 1.26 release notes"
Reddit (1): r/golang post on error handling
npm: [email protected] released

User Preference Management

When the user asks to change notification behavior:

• "Stop sending reddit" → Read current mutedSources, append "reddit", then cairn.patchConfig({"mutedSources": "<existing,reddit>"})
• "Only send me high priority" → cairn.patchConfig({"notifMinPriority": "high"})
• "Send github every hour instead" → Delete the existing cron and recreate with new schedule via cairn.deleteCron + cairn.createCron
• "What am I getting?" → List active cron digests + current muted sources
• "Show me what I missed" → Run digest immediately for all sources
• "Unmute reddit" → cairn.patchConfig({"mutedSources": "<current minus reddit>"})

Always confirm changes before applying. Example: "I'll mute Reddit notifications. You won't see them in digests. Say 'unmute reddit' to reverse."

Topic Management

• Create new topics on demand: cairn.telegram(action: "createForumTopic", params: {"name": "Custom Topic"})
• Route specific sources to custom topics via the topic mapping
• Close inactive topics: cairn.telegram(action: "closeForumTopic", params: {"topicID": N})

Rules

Never

• Post empty digests - skip the run entirely if there are no unread events
• Replace mutedSources without reading the current value first (would drop existing mutes)
• Send notifications for sources that are in batch mode (breaks digest-only intent)
• Create cron jobs that overlap with existing digest schedules for the same source

Tools

• cairn.readFeed - query events by source
• cairn.markRead - mark events as read after digest
• cairn.telegram - send to forum topics, manage topics
• cairn.patchConfig - update notification preferences
• cairn.createCron - create digest schedules
• cairn.deleteCron - remove cron jobs
• cairn.listCrons - show active schedules