Zulip automation: messaging, stream monitoring, and notifications

[brando90]

Summary

Build a uutils/zulip_uu.py module for Zulip automation — send messages, monitor streams, and manage notifications programmatically.

Motivation

Automate communications on Zulip (used by some research communities, e.g., Lean prover community, ML research groups). Send experiment results, monitor discussions, etc.

Proposed Implementation

API

• Zulip REST API (official, excellent)
  • Very well-documented, stable, and automation-friendly
  • Auth: Bot email + API key (simple!)
  • Python SDK: pip install zulip
  • Docs: https://zulip.com/api/

Module structure

class ZulipClient:
    @classmethod
    def from_zuliprc(cls, zuliprc_file="~/keys/zuliprc") -> "ZulipClient"
    
    def send_message(self, stream, topic, content) -> dict
    def send_dm(self, user_email, content) -> dict
    def get_messages(self, stream=None, topic=None, limit=50) -> list[dict]
    def get_streams(self) -> list[dict]
    def upload_file(self, file_path) -> str  # returns URL for embedding
    def get_unread_count(self) -> dict

Use cases

1. Research updates: Post results to a Lean/ML stream
2. Monitoring: Check for unread messages / mentions
3. File sharing: Upload plots/papers and share links
4. Cross-posting: Mirror important messages between Slack and Zulip

🔐 Secrets & Security

• Zulip uses a ~/.zuliprc file — we store it at ~/keys/zuliprc instead
• Format:

  [api]
  email=your-bot@your-org.zulipchat.com
  key=YOUR_API_KEY
  site=https://your-org.zulipchat.com

• NEVER commit this file — .gitignore already covers credential patterns

🧑 Human Interaction Required

• One-time: Create a bot in Zulip: Settings → Your Bots → Add Bot (~2 min)
• One-time: Download the zuliprc file and save to ~/keys/zuliprc
• That's it — Zulip has the simplest setup of all these services

💻 Machine Uptime

• Sending messages: does NOT require machine to stay on (one-shot)
• Monitoring on a schedule: machine must be on at scheduled time
• Zulip also supports long-polling for real-time events (requires persistent process)

Tasks

• Implement zulip_uu.py wrapping the official zulip Python SDK
• Add send_message, send_dm, get_messages, upload_file
• Add unread count / mention checking
• Add zulip to pyproject.toml
• Write usage docs in module docstring
• Test with a real Zulip organization