birthday-boy/README.org

birthday-boy

• About
• Setup
  • Prerequisites
  • Configuration
• Usage
  • Using Nix
    • Build
    • Run
  • Development
• Features

A simple Matrix bot to send birthday reminder messages to chat rooms.

About

Birthday Boy is a Common Lisp application that:

• Connects to a Matrix homeserver
• Tracks birthdays from a YAML configuration file
• Sends customizable birthday announcement messages to a specified room

Setup

Prerequisites

• [Nix](https://nixos.org/download.html) package manager (optional, for development/building)

Configuration

Create a config.yml file with the following structure:

config:
  homeserver_url: "https://matrix.example.com"  # Your Matrix server URL
  bot_name: "birthdaybot"                       # Bot username
  bot_pw: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"    # Bot password
  bot_access_token: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"  # Bot access token
  room_id: "!AAAAAAAAAAAAAAAAAA:groupchattt.page"  # Target room ID
  bot_message_template:  # List of random message templates
    - "Hey hey hey, it's the birthday fairy, and I am pleased to announce that it is ~A's birthday today. Congratulations, I love you!"
    - "Whoa there partner, looking like it's ~A's birthday today. From yours truly, the ole Birthday Fairy of the west!"

birthdays:  # List of birthdays to track
  - person: joe
    month: 4
    day: 13
  - person: carl
    month: 7
    day: 12
  - person: noel
    month: 9
    day: 10

Usage

Using Nix

Build

nix build

Run

./result/bin/birthday-boy /path/to/config.yml

Development

The repository includes a development shell with all necessary dependencies:

nix develop

Inside the development shell, you can:

sbcl --load ./bot.lisp --eval '(birthday-boy:main*)'

Features

• Configurable messages with randomized templates
• Easy birthday management through YAML configuration
• Automated checking of birthdays against the current date
• Nix-based build and development environment
• Minimal dependencies