An open-source personal AI agent that lives on your server and talks to you via Telegram.
You talk to it in natural language. It monitors the internet, thinks about what matters to you, and pings you when something important happens — in both English and Chinese.
YOU (anywhere) YOUR SERVER (home/cloud)
┌──────────────┐ ┌──────────────────────────────┐
│ │ │ │
│ Telegram │◄──────────│ BuzzAgent Agent │
│ on phone │ │ │
│ │───────────►│ Watches 15+ sources │
│ /buzz ... │ │ Thinks (AI + algorithms) │
│ │ │ Learns from your clicks │
└──────────────┘ │ Reports what matters │
│ │
│ 120KB · 310 tests · $0 AI │
└──────────────────────────────┘
Talk to it like a person:
/buzz kubernetes → follows the topic everywhere
/buzz I want to follow cloud security → AI understands, subscribes
/buzz what's happening with OpenAI → searches, scores, reports back
/buzz stop following crypto → done
/buzz suggest something new → analyzes your patterns, suggests topics
/buzz 帮我关注AI安全新闻 → works in Chinese too
It does the rest:
- Monitors 15+ sources (Google News, HN, Reddit, 36kr, V2EX, RSS, FreshRSS)
- Scores every article against your interests using Claude AI
- Groups related articles into stories (not a flat list)
- Sends breaking alerts instantly, digests when enough accumulates
- Translates everything into both EN and CN in one message
- Learns what you actually click on, boosts similar topics over time
- Discovers new topics you might like, suggests them proactively
Algorithms handle 70% of the work. AI only judges what algorithms can't.
1,500 articles/day
│
├── 30% killed by Bloom filter ────────── zero tokens
├── 20% killed by SHA-256 hash ────────── zero tokens
├── 15% killed by SimHash ─────────────── zero tokens
├── 5% killed by regex pre-filter ────── zero tokens
│
└── 30% reach AI (Claude CLI) ─────────── batched, subscription-based, $0 extra
│
└── TF-IDF clusters stories ───── zero tokens
Zero API cost — uses your Claude Code subscription (Max/Pro). No per-token billing.
Fastest: Use the template
Then:
bun install
bun run setup # wizard configures Claude + Telegram + feeds
bun run devDocker:
git clone https://github.com/gynet/buzzagent.git && cd buzz-wire
cp feeds.example.json feeds.json
echo "CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-..." > .env
echo "TELEGRAM_BOT_TOKEN=..." >> .env
docker compose up -d
# Send the 6-digit pairing code shown in logs to your botFly.io (free):
fly launch --copy-config --no-deploy
fly secrets set CLAUDE_CODE_OAUTH_TOKEN=... TELEGRAM_BOT_TOKEN=...
fly volumes create buzz_wire_data --size 1
fly deploymacOS service (set and forget):
bun run install:service # auto-starts on login, restarts on crashTry in browser:
One command does everything — /buzz
No menu to memorize. Just describe what you want in English or Chinese.
| You say | It does | AI cost |
|---|---|---|
/buzz kubernetes |
Subscribes: interest + Google News + AI-picked Reddit subs | 1 call |
/buzz what's happening with OpenAI |
One-shot search, scores, reports | 0 (regex) |
/buzz stop following crypto |
Unsubscribes from topic + removes feeds | 0 (regex) |
/buzz suggest new topics |
AI analyzes patterns → suggestions | 1 call |
/buzz 我想关注零日漏洞 |
Works in Chinese | 1 call |
/buzz fetch |
Trigger news aggregation | 0 |
/buzz https://example.com/article |
AI-summarize any URL (bilingual) | 1 call |
/buzz trending |
Show what's hot (algorithmic) | 0 |
/buzz mute 30 |
Silence for 30 minutes | 0 |
/buzz show my feeds |
Current config | 0 |
/buzz filter exclude crypto |
Scoring rules | 0 |
/buzz status |
Stats, uptime, trends | 0 |
/buzz import https://freshrss.example.com/opml |
Import OPML feeds | 0 |
You can also drag-and-drop an .opml file into the chat to import.
What /buzz kubernetes creates:
✅ Interest "kubernetes" (boosts scoring across ALL feeds)
📰 gn-kubernetes (Google News, every 30m)
🤖 reddit-kubernetes (AI-discovered)
🤖 reddit-devops (AI-discovered)
🤖 reddit-k8s (AI-discovered)
Direct commands (power users)
All 20 handlers are still registered — /buzz routes to them internally.
Use directly if you prefer explicit control.
Subscribe: /subscribe /unsubscribe /search /discover /import
Config: /config /interests /filter /threshold /schedule
Notify: /mute /unmute /digest /trending /history
Tools: /summary /status /fetch /help
Sources → [Algorithms: zero tokens] → [AI: minimal tokens] → [You: Telegram]
Bloom filter (URL dedup) Score + classify
SHA-256 (title dedup) Summarize (notable only)
SimHash (near-duplicate) Translate EN↔CN
Regex (interest pre-filter) Discover Reddit subs
TF-IDF (cluster stories) Name story clusters
Click decay (learn prefs) Parse natural language
- Claude Code subscription (Max or Pro plan) →
claude setup-token→ OAuth token - Telegram bot → @BotFather → token + chat ID
- A machine — Mac, Linux, Docker, Fly.io, NAS, anything that runs Bun
The setup wizard (bun run setup) walks you through all of it.
Edit while running — changes picked up automatically.
Input limits: Interests, feed names, filter keywords, and search queries are capped at 100 characters to prevent garbage data.
| Variable | Description |
|---|---|
CLAUDE_CODE_OAUTH_TOKEN |
From claude setup-token |
TELEGRAM_BOT_TOKEN |
From @BotFather |
TELEGRAM_CHAT_ID |
Auto-paired: send the 6-digit code shown at startup to your bot |
CLAUDE_CLI_MODEL |
sonnet (default) / opus / haiku |
DIGEST_INTERVAL_HOURS |
Max hours between digests (default: 4) |
| Plugin | Sources | How |
|---|---|---|
rss |
Google News, HN, Ars, Lobsters, 36kr, sspai | RSS/Atom |
reddit |
Any subreddit | Reddit JSON |
v2ex |
V2EX hot topics | V2EX API |
rsshub |
Twitter/X, Weibo, Bilibili | RSSHub |
freshrss |
Any FreshRSS instance | Google Reader / Fever API |
opml |
Bulk import from any reader | OPML file or URL |
src/
├── index.ts Entry, health server, click tracking
├── config.ts Typed config, hot-reload, CRUD
├── db.ts SQLite, migrations, click tracking
├── events.ts Typed event bus
├── scheduler.ts Smart digest timing, circuit breaker
├── pipeline.ts 4-layer dedup → pre-filter → AI
├── sources/ RSS, Reddit, V2EX, RSSHub, FreshRSS, OPML
├── ai/
│ ├── intent.ts Natural language → structured action
│ ├── discover.ts Topic discovery engine
│ ├── prefilter.ts Regex + click-weight pre-filter
│ ├── classifier.ts Batch AI scoring
│ ├── summarizer.ts AI summaries
│ └── translator.ts EN↔CN translation
├── notify/
│ ├── listener.ts /buzz unified interface, event-driven
│ ├── telegram.ts Alerts, digests, mute, file upload
│ └── router.ts TF-IDF clustering, bilingual routing
└── util/
├── bloom.ts Bloom filter with rotation
├── tfidf.ts TF-IDF + cosine similarity
└── simhash.ts 64-bit SimHash
| Bundle | 120KB single file |
| Dependencies | 1 (fast-xml-parser) |
| Tests | 310 |
| Commands | 20 |
| Source plugins | 6 |
| AI token savings | ~70% (algorithmic pre-processing) |
Vibe-coded from a delivery room while my wife was in labor. Built entirely with Claude Code. Baby is healthy. Wife is not amused by the commit timestamps.
MIT
{ "interests": [ "cloud infrastructure and Azure", "AI/LLM developer tools", "TypeScript ecosystem", "云计算和基础设施" ], "rules": [ { "include": "major outage", "boost": 30 }, { "include": "new release", "importance": "breaking" }, { "exclude": "cryptocurrency" } ], "thresholds": { "breaking": 75, "notable": 40 }, "feeds": [ { "type": "rss", "name": "hacker-news", "url": "https://hnrss.org/frontpage?points=100", "intervalMinutes": 10 }, { "type": "rss", "name": "36kr", "url": "https://36kr.com/feed", "intervalMinutes": 15, "lang": "cn" } ] }