Install

Clean-macOS install for other devs. Assumes you have admin on the machine and command-line comfort. About 10 minutes end-to-end, most of which is granting permissions.

1 · Prerequisites

Four things have to be on the machine before anything else:

2 · Clone

cd ~/Documents/development      # or anywhere; this is a personal location
git clone git@github.com:doublej/reminders-beads-bridge.git
cd reminders-beads-bridge

3 · Install Python deps

uv sync

This creates .venv/ and installs the two PyObjC frameworks (EventKit, Cocoa) plus dev tools. Takes ~30s on a warm cache.

4 · Run doctor

uv run rbridge doctor

Three things get checked:

• bd on PATH — fails with a path hint if not. Skip-able if you don't use the beads lane.
• Reminders permission — fails the first time. macOS will pop a permission dialog the moment EventKit asks for the store. Grant it; doctor turns green on the next run.
• Registry reachable — checks ~/.beads-kanban-projects.json. Missing is fine; it just means no projects to sync yet.

5 · Grant permissions

If doctor flagged Reminders permission, the dialog has already fired once. macOS sometimes loses the request — open it manually:

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"

Find uv (or your shell process) in the list and toggle it on. Also check Privacy & Security → Automation → your terminal app should have a checkbox for Reminders.

6 · One-shot sync

uv run rbridge sync

Prints the number of visible projects reconciled. If you have a ~/.beads-kanban-projects.json, you should see new Beads: <project> lists appear in Reminders.app within a second. If you don't have one yet, this just creates the four control lists (! Beads: Readme, Beads: Projects, Beads: Settings, Beads: Activity) and exits clean.

7 · Install the launchd agent

The repo ships a plist template under launchd/. Two paths inside it are absolute — you need to adjust them to your machine before loading.

# Copy + edit
cp launchd/com.jurrejan.reminders-bridge.plist ~/Library/LaunchAgents/com.<you>.reminders-bridge.plist
$EDITOR ~/Library/LaunchAgents/com.<you>.reminders-bridge.plist

Replace inside the copied plist:

• /Users/jurrejan → your $HOME.
• /Users/jurrejan/Documents/development/python/reminders-bridge → wherever you cloned the repo.
• com.jurrejan.reminders-bridge → com.<you>.reminders-bridge in the Label key (must match the plist filename).
• /opt/homebrew/bin/uv → output of which uv on your machine (Intel Macs and non-Homebrew uv installs differ).

Then load:

launchctl load ~/Library/LaunchAgents/com.<you>.reminders-bridge.plist

8 · Verify

tail -f ~/Library/Logs/reminders-bridge.log

You should see a sync cycle line every 5 seconds. Open Reminders.app — the ! Beads: Readme list sorts to the top.

Updating

cd ~/Documents/development/reminders-beads-bridge
git pull
uv sync
launchctl unload ~/Library/LaunchAgents/com.<you>.reminders-bridge.plist
launchctl load   ~/Library/LaunchAgents/com.<you>.reminders-bridge.plist

Uninstalling

launchctl unload ~/Library/LaunchAgents/com.<you>.reminders-bridge.plist
rm ~/Library/LaunchAgents/com.<you>.reminders-bridge.plist
rm -rf ~/.claude/reminders-bridge-state.json \
       ~/.claude/reminders-bridge-sessions.json \
       ~/.claude/reminders-bridge-captures.json \
       ~/.claude/voice-mailboxes/
# Lists in Reminders.app stay — delete them by hand if you want them gone.

Optional: install rbridge as a global CLI

If you want to invoke rbridge from anywhere (handy for rbridge mailbox open from inside a Claude Code session in a different repo):

uv tool install /Users/<you>/Documents/development/reminders-beads-bridge

Re-run with --force --reinstall after pulling updates.

Troubleshooting

Once it's running, head to voice mailboxes or sessions for the lanes that don't need any beads setup.