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)

webhook
Searching Database…

839 ·GitHub
Angelic-Angel
What is this?Angelic Angel is a Rust CLI tool that receives real-time Twitter/X push notifications by emulating a browser's Web Push client, connecting to Mozilla's AutoPush infrastructure, and forwarding the decrypted notification payloads to a webhook you control.
Is this scraping my Twitter feed, or something else?No scraping is involved. It uses the standard W3C Push API flow, the same mechanism a browser uses, connecting via WebSocket to Mozilla's AutoPush server and only calling Twitter's API once to register the push subscription.
How do I get it running?First run the init command to create an angelic-angel.toml config file with your Twitter credentials, then run register to create a push subscription with Mozilla AutoPush and link it to Twitter's notification API, and finally run the listen command with a WEBHOOK_ENDPOINT environment variable so decrypted payloads get POSTed somewhere you choose.
What do I need before I can use it?You need Rust (edition 2024) to build it, plus your Twitter/X authtoken and ct0 cookies, which you grab from the Application/Storage tab of your browser's dev tools after logging into x.com.
Will this catch tweets from any account I want?No — you only get notifications for accounts you follow and have specifically turned on tweet notifications for on Twitter/X, same as a real push notification would behave.
Where does the notification data actually come from?All notification data comes from Mozilla's Web Push server (push.services.mozilla.com), not from Twitter directly; Twitter's API is only touched once, during initial subscription registration.
How does it handle dropped WebSocket connections?It follows a Firefox-compatible reconnection strategy: exponential backoff starting at 5 seconds and doubling up to a 5-minute cap, automatic re-registration if the UAID gets invalidated, and a 30-minute wait if the server sends a backoff close code (4774).
What exactly happens when a tweet notification arrives?Angelic Angel decrypts the incoming push payload using ECE (Encrypted Content-Encoding) and sends the decrypted data to your configured webhook as an HTTP POST.
Why is it called 'Angelic Angel'?It's a playful reference to 'Angelic Angel/Hello, Hoshi wo Kazoete', a 2015 single by μ's used in the Love Live! movie — unrelated to the tool's actual function.
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
839
Updated
CommitMar 05
Age
7mo
Commits · 90 Days