Skip to content

EthanC/Bluebird

Repository files navigation

Bluebird

GitHub Workflow Status Docker Pulls Docker Image Size (tag)

Bluebird monitors users on X and reports new posts via Discord.

Setup

Although not required, a Discord Webhook is recommended for notifications.

An X account is required. It is recommended to use a throwaway account due to use of the internal API.

Environment Variables:

  • LOG_LEVEL: Loguru severity level to write to the console.
  • LOG_DISCORD_WEBHOOK_URL: Discord Webhook URL to receive log events.
  • LOG_DISCORD_WEBHOOK_LEVEL: Minimum Loguru severity level to forward to Discord.
  • USERS_ALL: Comma-separated list of X usernames to monitor for all posts.
  • USERS_TOP: Comma-separated list of X usernames to monitor for top-level posts only.
  • USERS_MEDIA: Comma-separated list of X usernames to monitor for media posts only.
  • COOLDOWN_MIN_TIME: Minimum randomized cooldown time between checking for new posts (default is 60).
  • COOLDOWN_MAX_TIME: Maximum randomized cooldown time between checking for new posts (default is 300).
  • X_CSRF_TOKEN: CSRF Token obtained via request inspection on X.
  • X_AUTH_TOKEN: Cookie Auth Token obtained via request inspection on X.
  • X_BEARER_TOKEN: Authentication Bearer Token obtained via request inspection on X.
  • DISCORD_WEBHOOK_URL: Discord Webhook URL to receive new post notifications.

Docker (Recommended)

Modify the following compose.yaml example file, then run 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
      USERS_ALL: Mxtive,spectatorindex,Breaking911
      USERS_TOP: X,XData
      USERS_MEDIA: archillect
      COOLDOWN_MIN_TIME: 60
      COOLDOWN_MAX_TIME: 300
      X_CSRF_TOKEN: XXXXXXXX
      X_AUTH_TOKEN: XXXXXXXX
      X_BEARER_TOKEN: XXXXXXXX
      DISCORD_WEBHOOK_URL: https://discord.com/api/webhooks/XXXXXXXX/XXXXXXXX
    restart: unless-stopped

Standalone

Bluebird is built for Python 3.12 or greater.

  1. Install required dependencies using uv: uv sync
  2. Rename .env.example to .env, then provide the environment variables.
  3. Start Bluebird: python bluebird.py