Skip to main content
GCalVFS mounts every calendar an account can see: each calendar becomes a folder of days, and each event a .gcal.json file holding the Calendar API’s JSON. Set up the credentials as in Google Workspace setup.

Install

Configure

bucket_days=7 or 30 makes each folder 7 or 30 days, time_zone sets the zone days are cut in, and start_time and end_time limit the mount to a time range. A MountMode.WRITE mount also allows rm.

Fields

str
Start of the mount’s time scope, inclusive: an RFC 3339 timestamp with an explicit timezone and at most millisecond precision. Unset leaves the start open.
str
End of the mount’s time scope, exclusive, in the same format as start_time, which it must follow. Unset leaves the end open.
float
default:"30"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
str | callable
secret
OAuth access token, or a callable that returns one. Takes precedence over client_id and refresh_token.
str
Google OAuth client ID. Required with refresh_token when access_token is unset; mirage then mints and renews access tokens itself.
str
secret
Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
str
secret
User’s OAuth refresh token. Required with client_id when access_token is unset.
str
One base URL that replaces every Google API host and the OAuth token endpoint, such as a test server. Unset uses Google’s hosts.
str
IANA time zone the mount buckets every calendar’s days in. Unset uses the primary calendar’s zone.
1 | 7 | 30
default:"1"
Days each date directory under a calendar holds: 1 names it by its day, 7 and 30 by its first and last day (<first>--<last>).
str
List only calendars where the account has at least this access role: freeBusyReader, reader, writer or owner. Unset lists every calendar.
str
Day (YYYY-MM-DD) the default listing’s 90-day future horizon is measured from, for tests and snapshots. Unset uses the current date in the mount’s time zone.
Fields marked secret are redacted in snapshots.

Authentication

Credentials come from the first of:
  1. access_token, a token or a callable that returns one.
  2. client_id and refresh_token, with client_secret unless the client uses PKCE. Mirage trades the refresh token for access tokens on its own.
The mount needs the Google Calendar API with the https://www.googleapis.com/auth/calendar scope, or calendar.readonly for a read-only mount. rm needs the owner or writer role on the event’s calendar; otherwise it fails with Permission denied.

Layout

  • The primary calendar is primary; every other one ends in __<calendar-id>.
  • An event file is named <event-id>__<HHMM-HHMM>_<title>.gcal.json. The times are clamped to that day, so an event running through it reads 0000-2400, and an event over several days appears under each.
  • An event file holds the unmodified Calendar API payload: attendees, description, location, and start and end with their offsets.
  • calendar.json holds the calendar’s access role and the zone its days are cut in.

Behavior

  • Time range: ls of a calendar lists days from all its history through 90 days ahead. A date glob such as ls /gcal/primary/2027-03-* lists its own range, past that horizon. start_time and end_time (RFC 3339 with a timezone) limit every listing, path, glob and read; dates outside them are absent.
  • Days: a well-formed date inside the range is a folder even when it holds no events. One zone covers the whole mount, the primary calendar’s unless time_zone is set, so every calendar’s 2026-11-16/ covers the same hours.
  • Calendars listed: min_access_role (freeBusyReader, reader, writer or owner) hides calendars where the account has less access.
  • Free/busy calendars: Google returns no titles for a calendar shared as free/busy only, so its events read as busy.
  • Delete: on a write mount, rm on an event file deletes the event for every attendee. Creating, editing and moving events go through the gws calendar CLI, which takes the calendar and event ids the tree shows. A written event must carry an explicit UTC offset or time zone.

Integration

Google Calendar answers these commands through its own API, so fewer files are read. See Integration.
  • grep -r and rg with -w: Calendar’s event search names the event files to read, together with the text the listing keeps, so no match is missed. Every file is read when the search fails or finds nothing, and files other than events (calendar.json) are always read. walk_limit: -1 in the mount’s "@all" command limit turns the search off and reads every file.

VFS.md

The VFS.md an agent reads with Google Calendar mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemVFS Layout/<path>
  • Calendars are primary and <Name>__<calendarId>; calendar.json holds the calendar’s accessRole and bucketTimeZone, the zone every bucket is cut in.
  • A bucket is one local day. A file is <eventId>__<HHMM-HHMM>_<Title>.gcal.json, times clamped to the day; a multi-day event appears under each day.
  • cat an event for the raw Calendar API JSON (attendees, description, location, start and end with offsets).
  • A listing runs through today +90 days unless end_time is set; a date glob such as 2027-03-* reaches past that.
  • On a write path, rm an event file deletes it for every attendee. Other changes go through the gws calendar CLI, with explicit offsets or a timeZone.
Time scope: start_time=unbounded (inclusive), end_time=unbounded (exclusive); explicit paths and globs cannot escape it.Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.