GitHub - PiotrMackowski/auto-joiner: Automatically joins your Zoom meetings on macOS

3 min read Original article ↗

zoom-autojoiner

Automatically joins your Zoom meetings on macOS. Reads your local macOS Calendar (works with Google Calendar synced via System Settings > Internet Accounts), watches for upcoming meetings with Zoom links, and opens them at the right time.

No Google Cloud API keys needed. No browser extensions. Just a Python script and a menu bar app that starts on login and restarts on crash.

Install

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/PiotrMackowski/auto-joiner/main/setup.sh)"

On first run, macOS will ask you to grant Calendar access — say yes.

What it does

  • Lives in your menu bar with a live countdown to your next meeting
  • Polls your macOS Calendar every minute
  • When a meeting with a Zoom link is about to start, opens it via zoommtg:// deep link
  • Joins 1 minute early so you're always on time
  • Looks back 30 minutes for late invites — if someone sends an invite after the meeting started, it still joins
  • Skips meetings matching configurable keywords (e.g. "focus time", "lunch")
  • Won't interrupt an ongoing meeting — if you're already in a call, it waits
  • Tracks which meetings it already joined today so it doesn't rejoin
  • Sends a macOS notification before joining
  • Starts on login, restarts on crash (launchd)

Menu Bar

The menu bar shows a static icon — no distracting timers:

  • 📅 — you have upcoming meetings
  • 🔴 — a meeting is starting now
  • ☁️ — no upcoming meetings

Click the icon for:

  • Next meeting with countdown
  • Toggle auto-join on/off
  • Skip meetings individually
  • Upcoming meetings list with times
  • Refresh to re-poll your calendar
  • Edit Config to open config.yaml in your default text editor
  • Open Logs to view the log file

Usage

# See upcoming meetings
~/zoom-autojoiner/venv/bin/python3 ~/zoom-autojoiner/autojoiner.py check

# Join the next Zoom meeting right now
~/zoom-autojoiner/venv/bin/python3 ~/zoom-autojoiner/autojoiner.py join-next

# View logs
tail -f ~/.zoom-autojoiner/autojoiner.log

Config

Edit ~/zoom-autojoiner/config.yaml (or use Edit Config in the menu bar):

join_early_minutes: 1        # join 1 minute before start
poll_interval_minutes: 1     # how often to check calendar
lookahead_minutes: 30        # how far ahead to look
lookback_minutes: 30         # how far back to look (late invites)
skip_keywords:               # skip meetings with these words
  - "focus time"
  - "lunch"
  - "blocked"
  - "OOO"
notify_before_join: true     # macOS notification before joining
zoom_only: true              # only auto-join meetings with Zoom links
log_file: "~/.zoom-autojoiner/autojoiner.log"  # log file path

Uninstall

launchctl unload ~/Library/LaunchAgents/com.autojoiner.zoom.plist
rm ~/Library/LaunchAgents/com.autojoiner.zoom.plist
rm -rf ~/zoom-autojoiner ~/.zoom-autojoiner

Requirements

  • macOS (uses EventKit for calendar access)
  • Python 3.9+
  • Zoom desktop app installed
  • Calendar synced via System Settings > Internet Accounts

Limitations

  • macOS syncs calendars every 5–15 minutes (hardcoded by Apple, not configurable). If someone sends a last-minute invite, it may take up to 15 minutes before macOS pulls it down. The 30-minute lookback window compensates for this. You can force a sync in Calendar.app with Cmd+Shift+R.