Thanks for your interest! ogmac is a small, focused tool — patches that keep it that way are most welcome.
Requires macOS 12+ and Python 3.11+ (brew install python@3.11).
git clone https://github.com/razbahri/ogmac.git
cd ogmac
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"The default test suite is hermetic — no network, no Keychain, no real EventKit:
pytest -qTwo integration tests are gated behind an env var because they hit real APIs:
OGMAC_LIVE=1 pytest tests/integration/test_google_live.py requires a Google OAuth refresh token in Keychain (ogmac login google) and a calendar named ogmac-test. test_graph_live.py requires read_method=microsoft_graph and a refresh token from ogmac login microsoft.
ruff check .
ruff format .
mypy src/ogmacCI runs ruff check and pytest on macOS for Python 3.11, 3.12, and 3.13.
src/ogmac/— package sourcecli.py— entry point and sync orchestrationoutlook.py— Microsoft Graph backendoutlook_eventkit.py— Apple Calendar / EventKit backendgoogle.py— Google Calendar API clientauth.py— Keychain token storage and OAuth flowsreconciler.py— pure diff logic between source and target eventsstate.py— local SQLite state (event map, run state)
tests/unit/— pure-logic teststests/e2e/— full-run tests with mocked external servicestests/integration/— opt-in tests against real APIspackaging/—install.shand the launchd plistscripts/probe_eventkit.py— dev helper to inspect EventKit calendar sourcesdocs/superpowers/specs/— design spec
- Pure functions over classes where reasonable; keep side effects at the edges (CLI, network, filesystem).
- The reconciler must stay pure — all I/O happens in
cli.py. - Add a unit test for any new branch in the diff/reconcile logic.
- Follow the existing logging idiom:
event.kind key1=val1 key2=val2.
- Fork and branch from
main. - Add tests for the change.
- Run
pytest,ruff check, andmypylocally. - Open a PR with a one-line summary and a short description of the why.
For larger changes, please open an issue first to align on direction.