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

bucketDays: 7 or 30 makes each folder 7 or 30 days, timeZone sets the zone days are cut in, and startTime and endTime limit the mount to a time range. A MountMode.WRITE mount also allows rm.

Fields

number
default:"DEFAULT_TIMEOUT"
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.
string | function
secret
OAuth access token, or a function (sync or async) that returns one. Takes precedence over clientId and refreshToken.
string
Google OAuth client ID. Required with refreshToken when accessToken is unset; mirage then mints and renews access tokens itself.
string
secret
Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
string
secret
User’s OAuth refresh token. Required with clientId when accessToken is unset.
function
secret
Function that exchanges the refresh token for { accessToken, expiresIn } instead of Google’s token endpoint, so the client secret can stay on a backend. Still needs clientId and refreshToken.
string
One base URL that replaces every Google API host and the OAuth token endpoint, such as a test server. Unset uses Google’s hosts.
string
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.
string
End of the mount’s time scope, exclusive, in the same format as startTime, which it must follow. Unset leaves the end open.
string
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>).
string
List only calendars where the account has at least this access role: freeBusyReader, reader, writer or owner. Unset lists every calendar.
string
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. accessToken, a token or a function, sync or async, that returns one.
  2. clientId and refreshToken, with clientSecret unless the client uses PKCE. Mirage trades the refresh token for access tokens on its own, or hands it to refreshFn when set, so the secret can stay on a backend.
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. startTime and endTime (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 timeZone is set, so every calendar’s 2026-11-16/ covers the same hours.
  • Calendars listed: minAccessRole (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.

Browser

The same GCalVFS comes from @struktoai/mirage-browser. In a page, an accessToken function fetches a fresh token from a backend, so the client secret never reaches the browser.
  • /api/google-token stands for a backend endpoint that returns an access token.
  • A PKCE OAuth client needs no secret: clientId and refreshToken alone mount it.
  • refreshFn sends each refresh to a backend instead of Google’s token endpoint.

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. walkLimit: -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.