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
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.
OAuth access token, or a function (sync or async) that returns one. Takes precedence over
clientId and refreshToken.Google OAuth client ID. Required with
refreshToken when accessToken is unset; mirage then mints and renews access tokens itself.Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
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.One base URL that replaces every Google API host and the OAuth token endpoint, such as a test server. Unset uses Google’s hosts.
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.
End of the mount’s time scope, exclusive, in the same format as
startTime, which it must follow. Unset leaves the end open.IANA time zone the mount buckets every calendar’s days in. Unset uses the primary calendar’s zone.
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>).List only calendars where the account has at least this access role:
freeBusyReader, reader, writer or owner. Unset lists every calendar.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.Authentication
Credentials come from the first of:accessToken, a token or a function, sync or async, that returns one.clientIdandrefreshToken, withclientSecretunless the client uses PKCE. Mirage trades the refresh token for access tokens on its own, or hands it torefreshFnwhen set, so the secret can stay on a backend.
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 reads0000-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.jsonholds the calendar’s access role and the zone its days are cut in.
Behavior
- Time range:
lsof a calendar lists days from all its history through 90 days ahead. A date glob such asls /gcal/primary/2027-03-*lists its own range, past that horizon.startTimeandendTime(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
timeZoneis set, so every calendar’s2026-11-16/covers the same hours. - Calendars listed:
minAccessRole(freeBusyReader,reader,writerorowner) 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
writemount,rmon an event file deletes the event for every attendee. Creating, editing and moving events go through thegws calendarCLI, which takes the calendar and event ids the tree shows. A written event must carry an explicit UTC offset or time zone.
Browser
The sameGCalVFS 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-tokenstands for a backend endpoint that returns an access token.- A PKCE OAuth client needs no secret:
clientIdandrefreshTokenalone mount it. refreshFnsends 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 -randrgwith-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: -1in 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.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- Calendars are
primaryand<Name>__<calendarId>;calendar.jsonholds the calendar’saccessRoleandbucketTimeZone, 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. catan event for the raw Calendar API JSON (attendees, description, location, start and end with offsets).- A listing runs through today +90 days unless
end_timeis set; a date glob such as2027-03-*reaches past that. - On a
writepath,rman event file deletes it for every attendee. Other changes go through thegws calendarCLI, with explicit offsets or atimeZone.
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.