Proactivity

Proactive agents in Snippbot act on their own initiative — surfacing timely insights, delivering digests, and taking autonomous actions without waiting for an explicit user prompt. Proactivity bridges scheduled automation and reactive chat-based interaction.

Tip

Configure insight generation, aggressiveness, delivery channels, and quiet hours on the Insights → Settings tab in the Snippbot UI. (Channel-adapter proactivity — letting agents message Slack/Telegram/etc. unprompted — is still configured per-platform under Settings → Channels; see Enabling proactive delivery below.)

How proactivity works

Proactivity is implemented through two complementary systems:

1. Scheduler — Jobs defined with cron, interval, or natural language schedules. When they fire, the agent executes its goal autonomously and delivers results to a channel.

2. Channel proactivity — The channel adapter system can be configured to allow agents to send messages to platforms (Slack, Telegram, Discord, etc.) without the user first sending a message.

Smart scheduling

The SmartScheduler learns from your activity patterns to suggest optimal times for proactive jobs:

User typically active: 09:00–12:00, 14:00–17:00 (Mon–Fri)
Suggested time for "daily digest": 08:55 (5 min before typical start)

The scheduler builds a UserActivityPattern from session timing data and uses it to propose schedules when you create a new job without specifying a time:

"Send me a morning briefing every weekday"
→ Suggested: weekdays at 08:55 (your typical start minus 5 min)

Quiet hours

Proactive messages respect quiet hours to avoid notifications outside work hours. Quiet hours are optional and configurable:

Setting	Default
Quiet hours start	22:00 (configurable)
Quiet hours end	08:00 (configurable)

Proactive jobs that fire during quiet hours are deferred — their result is queued and delivered when quiet hours end, not dropped.

Generation vs. delivery

Insight generation and delivery are controlled separately, so you can keep insights flowing to one place while silencing another — or stop everything with a single switch. All three controls live on the Insights → Settings tab.

Control	What it does
Generate insights (master switch)	The single on/off for the whole system. When off, the agent produces no insights and every control below is hidden. There is no longer a “Silent” level — this switch owns off.
Email me a digest	Batches insights to your inbox. Off = no emails; insights still appear in-app. AND-ed with the global email toggle, so both must be on for email to send.
Show in in-app tray	Insights appear on the Insights tab regardless of email delivery. Off = the tray shows an “In-app insights are turned off” empty state.

Aggressiveness levels

When generation is on, a 1–4 aggressiveness slider (“How aggressive?”) controls the cadence:

Level	Name	Behavior	Can interrupt
1	Minimal	Only critical alerts and reminders.	No
2	Moderate	Balanced suggestions and timely reminders.	No
3	Active	Regular insights and optimization suggestions.	Yes (high priority)
4	Proactive	Maximum engagement with learning and predictions.	Yes

Actual delivery volume is bounded further by Quiet Hours and the Advanced → Max Per Day cap. Configure the slider, quiet hours, and Max Per Day on the Insights → Settings tab in the Snippbot UI.

How insights reach you

Generation and delivery are decoupled. The heuristic engine produces candidate insights; the Unified Intent Dispatcher decides which of them actually reach your tray, when, and at what priority. The slider above controls dispatcher policy, not generation cadence.

InsightGenerator.generate_candidates()
        │
        ▼  emits one IntentEnvelope per candidate
IntentEnvelope(
   source = PROACTIVE,
   kind   = INSIGHT,
   urgency = candidate.urgency,         # 0.0 - 1.0
   proactive_value = candidate.value,
   can_interrupt = candidate.interrupt,
   payload = { insight_id, title, content, ... }
)
        │
        ▼
Tier 1: kind=INSIGHT → DeliverAsInsight(user_id, room_id?)
        │
        ▼
Tier 2: ProactivityManager.can_deliver_insight(...)
        │
        ├─ approved   ──► DeliverAsInsight passes through
        │                   │
        │                   ▼
        │                 InsightQueue.enqueue + SSE broadcast
        │                   │
        │                   ▼
        │                 Insight tray + (optional) push notification
        │
        ├─ quiet hours ──► ScheduleFor(next_window)
        │
        └─ daily cap   ──► Suppress(reason=daily_cap_exceeded)
                             │
                             ▼
                           Logged only — never reaches the tray

Tip

Want to see this in action? Run snippbot dispatcher tail --source proactive while a generation tick fires — you’ll see one decision-log entry per candidate insight, with the Tier 2 verdict (approved / deferred / suppressed) and the reason.

The dispatcher’s Tier 2 policy gate is what makes the proactivity level actually act on every insight. Without it, the slider would only affect generation cadence — every generated insight would always reach the tray.

See also: Unified Intent Dispatcher and the snippbot dispatcher CLI for inspection commands.

Enabling proactive delivery

Channel proactivity is disabled by default. Enable it per-platform in Settings → Channels in the Snippbot UI:

1. Open Settings → Channels and select the platform
2. Toggle Proactive Enabled to on
3. Set a Public URL (required for platforms that deliver webhooks) under channel settings

Note

For proactive outbound messages to work, the channel adapter must be running (snippbot channel start) and the platform must support bot-initiated messages (all supported platforms do).

Common proactive patterns

Morning briefing

Goal: Summarize overnight GitHub activity, new issues, and PRs for my repos
Schedule: weekdays at 08:00
Delivery: Slack #engineering

Price or metric alert

Goal: Check if BTC price has changed by more than 5% since yesterday
Schedule: every 1h
Condition: only run if change > 5%
Delivery: Telegram @me

Daily digest

Goal: Compile a summary of completed tasks, pending items, and calendar events
Schedule: weekdays at 17:30
Delivery: Email summary

Anomaly detection

Goal: Check error rate from the last hour in Datadog; alert if > 1%
Schedule: every 15m
Condition: only if error_rate > 0.01
Delivery: PagerDuty webhook

Proactivity vs. reactive chat

	Reactive	Proactive
Triggered by	User message	Schedule or event
Approval required	Only for elevated actions	Per permission tier
Delivery	Chat interface	Channel or webhook
History	In chat	In scheduler run history

Delivery limits

Proactive message delivery is governed by the aggressiveness level (see table above) together with the Advanced → Max Per Day cap. A lower level like Minimal surfaces only critical items, while Proactive allows the highest cadence; the Max Per Day setting puts a hard ceiling on either.

Messages that exceed the daily limit are queued, not dropped.

Disabling proactivity for an agent

Each agent can have proactivity disabled independently in its settings. Useful during development or testing:

• From the agent detail page → Settings → Proactivity: toggle Off

Related

• Run a Loop — autonomous, goal-seeking runs that iterate until a condition holds
• Schedule a Job — single-pass recurring work
• Intent Dispatcher — how proactive and autonomous signals are routed