gcal-vcs 1.0.0

Git-like staging, diffing, and version control for Google Calendar

gcal-vcs

Git-style version control for Google Calendar. Scripts and AI agents are powerful, but giving them direct write access to your schedule is risky. gcal-vcs acts as a safety buffer: stage changes locally, preview the impact with a visual diff, and commit only when you're ready.

The 2-Line Integration

Designed for zero refactoring. You wrap your existing service, and the rest of your code remains identical.

Before

service = build("calendar", "v3", credentials=creds)

# this hits the Google API immediately + no undo
service.events().insert(calendarId="primary", body=event_data).execute()

After

from gcal_vcs import staged

# 1. wrap ur service
service = staged(build("calendar", "v3", credentials=creds))

# 2. use the exact same API (changes are now staged locally)
service.events().insert(calendarId="primary", body=event_data).execute()

service.preview()   # opens visual diff in browser
service.commit()    # applies all changes atomically

---

Agent-First Workflows

For headless environments or AI agents, gcal-vcs provides programmatic oversight without forcing a browser popup:

# Returns a URL to the diff UI instead of opening a browser
url = service.preview(blocking=False)

# Get a human-readable text summary for LLM validation
print(service.get_text_summary()) 

# Check changes programmatically
if service.status().total_changes < 10:
    service.commit()
else:
    service.rollback()

CLI & History

Manage your calendar state directly from the terminal.

gcal-vcs log              # list recent commits
gcal-vcs show <id>        # inspect a specific change set
gcal-vcs revert <id>      # undo any previous commit
gcal-vcs ui               # open the history browser

Example of CLI-revert

Installation

pip install gcal-vcs

Requirements

• Python 3.9+
• Google Calendar API credentials