> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Calendar in Python

> Virtualize Google Calendar calendars and events from Python.

`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](https://docs.mirage.strukto.ai/home/setup/google.md).

## Install

```bash theme={null}
pip install mirage-ai
```

## Configure

```python theme={null}
import os

from mirage import MountMode, Workspace
from mirage.vfs.gcal import GCalConfig, GCalVFS

config = GCalConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
ws = Workspace({"/gcal": GCalVFS(config)}, mode=MountMode.READ)

result = await ws.shell("ls /gcal && grep -lw standup /gcal/primary/2026-11-*/*.gcal.json")
print(await result.stdout_str())
await ws.close()
```

`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

**start\_time** `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.

**end\_time** `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.

**timeout** `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.

**access\_token** `str | callable`

OAuth access token, or a callable that returns one. Takes precedence over `client_id` and `refresh_token`.

**client\_id** `str`

Google OAuth client ID. Required with `refresh_token` when `access_token` is unset; mirage then mints and renews access tokens itself.

**client\_secret** `str`

Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.

**refresh\_token** `str`

User's OAuth refresh token. Required with `client_id` when `access_token` is unset.

**api\_base** `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.

**time\_zone** `str`

IANA time zone the mount buckets every calendar's days in. Unset uses the primary calendar's zone.

**bucket\_days** `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>`).

**min\_access\_role** `str`

List only calendars where the account has at least this access role: `freeBusyReader`, `reader`, `writer` or `owner`. Unset lists every calendar.

**today** `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

```text theme={null}
/gcal/
  primary/
    calendar.json
    2026-11-16/
      7kq2m9__0900-0930_Team_Standup.gcal.json
  Engineering__team@group.calendar.google.com/
    2026-11-16/
      ...
```

* 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`](https://docs.mirage.strukto.ai/python/cli/gws) 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](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `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](https://docs.mirage.strukto.ai/home/limits.md#command-output) turns the search
  off and reads every file.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.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.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `gcal`, `<mode>` |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   primary/
>     calendar.json
>     2026-08-11/
>       <eventId>__0900-1030_Team_Standup.gcal.json
>   Engineering__team@group.calendar.google.com/
>     2026-08-11/
>       ...
> ```
>
> * 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 VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest), and `rm` and `unlink`. `grep -r` and `rg` with `-w` ask `gcal` which files may match. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Not supported: `>`, `>>`, `tee`, `tee -a`, `touch` of a new file, `cp`, `cp -r`, `mkdir`, `mv`, `rm -r`, `rmdir`, `truncate`, `sed -i`. Without `-w`, `grep -r` and `rg` read every file. `gcal` answers only for `*/*/*.gcal.json`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `gcal`, `<mode>` |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   primary/
>     calendar.json
>     2026-08-11/
>       <eventId>__0900-1030_Team_Standup.gcal.json
>   Engineering__team@group.calendar.google.com/
>     2026-08-11/
>       ...
> ```
>
> - 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 VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest), and `rm` and `unlink`. `grep -r` and `rg` with `-w` ask `gcal` which files may match. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Not supported: `>`, `>>`, `tee`, `tee -a`, `touch` of a new file, `cp`, `cp -r`, `mkdir`, `mv`, `rm -r`, `rmdir`, `truncate`, `sed -i`. Without `-w`, `grep -r` and `rg` read every file. `gcal` answers only for `*/*/*.gcal.json`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.