consciousness/docs/notifications.md

Notification daemon

poc-daemon routes messages from communication modules and internal events through a hierarchical, activity-aware delivery system.

Architecture

  Communication modules              Hooks
  +-----------------+               +-------------+
  |  IRC (native)   |--+            |  poc-hook   |
  |  Telegram       |  |  mpsc      |  (all events|
  +-----------------+  +------+     +------+------+
                       |      |            |
                       v      |     capnp-rpc
                  +----------+             |
                  |  poc-daemon            |
                  |                        |
                  |  NotifyState <---------+
                  |    +-- type registry
                  |    +-- pending queue
                  |    +-- threshold lookup
                  |    +-- activity-aware delivery
                  |
                  |  idle::State
                  |    +-- presence detection
                  |    +-- sleep/wake/dream modes
                  |    +-- tmux prompt injection
                  +--------------------------

Notification types and urgency

Types are free-form hierarchical strings: irc.mention.nick, irc.channel.bcachefs, telegram.kent. Each has an urgency level:

Level	Name	Meaning
0	ambient	Include in idle context only
1	low	Deliver on next check
2	normal	Deliver on next user interaction
3	urgent	Interrupt immediately

Per-type thresholds walk up the hierarchy: irc.channel.bcachefs-ai -> irc.channel -> irc -> default. Effective thresholds adjust by activity state: raised when focused, lowered when idle, only urgent when sleeping.

Communication modules

IRC — native async TLS connection (tokio-rustls). Connects, joins channels, parses messages, generates notifications. Runtime commands: join, leave, send, status, log, nick. Per-channel logs at ~/.claude/irc/logs/.

Telegram — native async HTTP long-polling (reqwest). Downloads media (photos, voice, documents). Chat ID filtering for security. Runtime commands: send, status, log.

Both modules persist config changes to ~/.claude/daemon.toml — channel joins and nick changes survive restarts.

Commands

poc-daemon                         # Start daemon
poc-daemon status                  # State summary
poc-daemon irc status              # IRC module status
poc-daemon irc send TARGET MSG     # Send IRC message
poc-daemon irc join CHANNEL        # Join (persists to config)
poc-daemon irc leave CHANNEL       # Leave
poc-daemon irc log [N]             # Last N messages
poc-daemon telegram status         # Telegram module status
poc-daemon telegram send MSG       # Send Telegram message
poc-daemon telegram log [N]        # Last N messages
poc-daemon notify TYPE URG MSG     # Submit notification
poc-daemon notifications [URG]     # Get + drain pending
poc-daemon notify-types            # List all types
poc-daemon notify-threshold T L    # Set per-type threshold
poc-daemon sleep / wake / quiet    # Session management
poc-daemon stop                    # Shut down

Configuration

Config: ~/.claude/daemon.toml

[irc]
enabled = true
server = "irc.oftc.net"
port = 6697
tls = true
nick = "MyBot"
user = "bot"
realname = "My Bot"
channels = ["#mychannel"]

[telegram]
enabled = true
token = "bot-token-here"
chat_id = 123456789