Birthday Reminder

A GitHub Actions cron job that sends you a daily SMS when friends and family have birthdays coming up. Reads from your Apple Contacts, keeps all personal data private, and texts you via Twilio.

What it does

• Every day at 8am PT: Texts you if anyone has a birthday today or tomorrow
• Every Sunday: Also includes a full week-ahead preview

Example SMS:

🎂 Today: Jane Doe (turns 30)
📅 Tomorrow: John Smith

How it works

Your contacts never touch GitHub. Instead:

1. You export your contacts locally and run a parser to generate birthdays.json
2. You paste the contents of that file into a GitHub Actions secret
3. GitHub Actions runs the cron job daily, injecting the secret at runtime

Setup

1. Prerequisites

• Node.js 20+
• A Twilio account with a phone number (free trial works)
• A Mac with Apple Contacts

2. Clone and install

git clone https://github.com/your-username/birthday-reminder.git
cd birthday-reminder
npm install

3. Export your contacts

1. Open Contacts on your Mac
2. Select all: Cmd+A
3. File → Export → Export vCard...
4. Save as contacts.vcf inside the data/ folder

4. Parse your contacts

npm run parse

This generates data/birthdays.json. Both files are gitignored — they never leave your machine.

Review the output to make sure names and dates look correct.

5. Add GitHub Actions secrets

In your GitHub repo, go to Settings → Secrets and variables → Actions and add:

Secret	Value
BIRTHDAYS_JSON	Full contents of data/birthdays.json
TWILIO_ACCOUNT_SID	From your Twilio console
TWILIO_AUTH_TOKEN	From your Twilio console
TWILIO_FROM_NUMBER	Your Twilio phone number (e.g. +11234567890)
MY_PHONE_NUMBER	Your personal number to receive texts (e.g. +11234567890)

6. Push and test

git push

Then go to Actions → Birthday Check → Run workflow to trigger a manual test run and confirm you receive an SMS.

Updating your contacts

When your contacts change, re-export and re-parse locally, then update the BIRTHDAYS_JSON secret with the new file contents.

Privacy

Nothing personal is committed to this repo. The data/ folder is gitignored entirely. The GitHub Actions workflow only contains secret names — the values are encrypted by GitHub and injected at runtime.