Bluebird tracks users on X (formerly Twitter) and sends post notifications to Discord.
- Monitor any public user on X — no login required (thanks to dylanpdx/BetterTwitFix).
- Get structured alerts with rich Discord Components.
- Fine-tune alerts using filters like keywords or media-only.
- Deploy effortlessly with Docker or run locally with Python.
Rename config.example.toml to config.toml and set your instance configuration(s).
Next, edit and run this example compose.yaml with docker compose up.
services: bluebird: container_name: bluebird image: ethanchrisp/bluebird:latest environment: LOG_LEVEL: INFO LOG_DISCORD_WEBHOOK_URL: https://discord.com/api/webhooks/YYYYYYYY/YYYYYYYY LOG_DISCORD_WEBHOOK_LEVEL: WARNING volumes: - /local/path/to/config.toml:/bluebird/config.toml:ro restart: unless-stoppedNote
Python 3.13 or later required.
-
Install dependencies.
uv sync
-
Rename
.env.exampleto.envand configure your environment. -
Rename
config.example.tomltoconfig.tomland set your instance configuration(s). -
Run Bluebird
uv run bluebird.py
Each instance within config.toml can be configured to filter posts from sending notifications.
| Key | Description | Type | Required | Example |
|---|---|---|---|---|
usernames | X usernames to track. | Array of Strings | Yes | ["RockstarGames", "CallofDuty", "Mxtive"] |
discord_webhook_url | Discord Webhook URL to send post notifications to. | String | Yes | https://discord.com/api/webhook/XXXXXXXX/XXXXXXXX |
require_media | Set to true to only notify of posts with media. | Boolean | No | true |
require_keyword | Only notify of the post if one of these words are found. | Array of Strings | No | ["trailer", "new", "announcement", "delay"] |
exclude_reply | Set to true to skip posts that are replies. | Boolean | No | true |
exclude_repost | Set to true to skip posts that are reposts. | Boolean | No | true |
exclude_keyword | Skip the post if at least one of these words are found. | Array of Strings | No | ["store", "price", "shop", "bundle"] |
cooldown | Amount of time (in seconds) to wait between checking for new posts. | Integer | No | 900 |