Angelic-Angel README

The project's README from github.com/sh1ma/Angelic-Angel. As one markdown file: README.md.

Angelic Angel

"Angelic Angel/Hello, Hoshi wo Kazoete" is a single by μ's released on July 1, 2015 from Lantis. The song is an insert song for the film Love Live! The School Idol Movie.

— Wikipedia

A CLI tool that receives Twitter/X notifications in real time via Mozilla's Web Push infrastructure. Stream tweets from users you follow and have tweet notifications enabled for.

日本語版 README

Overview

Angelic Angel emulates a browser's Web Push client to receive Twitter/X push notifications. It connects to Mozilla AutoPush via WebSocket, decrypts incoming notifications using ECE (Encrypted Content-Encoding), and forwards the decrypted payloads to a configured webhook endpoint.

You will receive notifications for tweets from users that you follow and have tweet notifications turned on for on Twitter/X.

How It Works

Twitter/X  ──push──▶  Mozilla AutoPush Server  ◀──WebSocket──  Angelic Angel  ──HTTP POST──▶  Webhook
  1. Angelic Angel registers as a Web Push subscriber with Mozilla's AutoPush server.
  2. The push subscription endpoint is registered with Twitter's notification settings API.
  3. When Twitter sends a push notification, it goes through Mozilla's AutoPush server — the same infrastructure used by Firefox.
  4. Angelic Angel receives and decrypts the notification via WebSocket, then forwards the payload to your webhook.

Important Notes

Requirements

Getting auth_token and ct0

  1. Open x.com in your web browser and log in.
  2. Open Developer Tools (F12) and go to the Application (or Storage) tab.
  3. Under Cookies → https://x.com, find the values for auth_token and ct0.

Installation

cargo install --path .

Usage

1. Initialize configuration

# Interactive mode
angelic-angel init

# Or with arguments
angelic-angel init --auth-token YOUR_AUTH_TOKEN --ct0 YOUR_CT0

This creates angelic-angel.toml with your Twitter credentials.

2. Register push subscription

angelic-angel register

This registers a new push subscription with Mozilla AutoPush and then registers the endpoint with Twitter's push notification API.

3. Start listening

WEBHOOK_ENDPOINT=https://your-webhook.example.com/endpoint angelic-angel listen

The WEBHOOK_ENDPOINT environment variable specifies where decrypted notification payloads are sent via HTTP POST.

Other commands

# Check current configuration and registration status
angelic-angel status

# Remove push subscription
angelic-angel unregister

Options

Flag Description
-c, --config <PATH> Configuration file path (default: angelic-angel.toml)
-v, --verbose Enable debug logging

Reconnection

Angelic Angel implements a Firefox-compatible reconnection strategy:

License

MIT

Angelic-Angel (sh1ma/Angelic-Angel)

Searching Database…

838 ·GitHub
Angelic-Angel
这是什么？Angelic Angel 是一个 Rust CLI 工具，通过模拟浏览器的 Web Push 客户端、连接 Mozilla 的 AutoPush 基础设施来接收 Twitter/X 的实时推送通知，并把解密后的通知负载转发给你自己控制的 webhook。
这是在抓取我的 Twitter 动态，还是别的方式？完全不涉及抓取。它使用标准的 W3C Push API 流程，与浏览器所用机制相同，通过 WebSocket 连接 Mozilla 的 AutoPush 服务器，只在注册推送订阅时调用一次 Twitter 的 API。
怎么让它跑起来？先运行 init 命令生成包含 Twitter 凭据的 angelic-angel.toml 配置文件；然后运行 register 向 Mozilla AutoPush 创建推送订阅并关联 Twitter 的通知 API；最后在设置 WEBHOOK_ENDPOINT 环境变量后运行 listen 命令，解密后的负载就会被 POST 到你指定的地址。
使用之前我需要准备什么？你需要 Rust(edition 2024)来构建它，还需要你的 Twitter/X authtoken 和 ct0 cookie——登录 x.com 后从浏览器开发者工具的 Application/Storage 标签页获取。
它能捕捉我想要的任何账号的推文吗？不能——你只会收到你在 Twitter/X 上已关注、且专门开启了推文通知的账号的通知，和真实推送通知的行为一样。
通知数据究竟来自哪里？所有通知数据都来自 Mozilla 的 Web Push 服务器(push.services.mozilla.com)，而非直接来自 Twitter;Twitter 的 API 只在初始订阅注册时被调用一次。
它如何处理 WebSocket 连接断开？它遵循与 Firefox 兼容的重连策略：从 5 秒开始的指数退避，每次翻倍直至 5 分钟上限；UAID 失效时自动重新注册；服务器发送退避关闭码(4774)时等待 30 分钟。
推文通知到达时究竟会发生什么？Angelic Angel 用 ECE（加密内容编码）解密收到的推送负载，并把解密后的数据通过 HTTP POST 发送到你配置的 webhook。
它为什么叫 'Angelic Angel'?这是在玩梗，致敬 μ's 2015 年的单曲《Angelic Angel/Hello, Hoshi wo Kazoete》，出自 Love Live! 剧场版——与工具的实际功能无关。
What are similar projects?tincan-cli, webhook, pdfcraft, chisel, curl, ngrok, apprise, smartdns
Which topics is it in?mozilla, webhook, twitter, firefox, webhooks, notifications, websocket, http, real-time, encryption, utility, networking
Creator
sh1ma
Size
<0.1 MB
Stars
838
Updated
CommitMar 05
Age
7mo
Commits · 90 Days