Google Docs

The Google Docs VFS exposes Docs documents as a virtual filesystem mounted at some prefix such as /gdocs/. For Google OAuth setup, see Google Workspace Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.gdocs import GDocsConfig, GDocsVFS

config = GDocsConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
vfs = GDocsVFS(config=config)
ws = Workspace({"/gdocs": vfs}, mode=MountMode.READ)

Field	Description
`timeout` 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` secret	OAuth access token, or a callable that returns one. Takes precedence over `client_id` and `refresh_token`.
`client_id`	Google OAuth client ID. Required with `refresh_token` when `access_token` is unset; mirage then mints and renews access tokens itself.
`client_secret` secret	Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
`refresh_token` secret	User’s OAuth refresh token. Required with `client_id` when `access_token` is unset.
`api_base`	One base URL that replaces every Google API host and the OAuth token endpoint, such as a test server. Unset uses Google’s hosts.

Fields marked secret are redacted in snapshots.

VFS.md

The VFS.md an agent reads with Google Docs mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`gdocs`, write

`/<path>` layout

/<path>
  owned/
    <date>_<title>__<doc-id>.gdoc.json
  shared/
    <date>_<title>__<doc-id>.gdoc.json

  Filename: <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json
    <YYYY-MM-DD>  modifiedTime, used for date-glob (e.g. 2026-05-*)
    <title>       sanitized: spaces->_, non-[A-Za-z0-9_.-]->_, <=100 chars
    <doc-id>      Google Docs document ID

  Buckets:
    owned/   docs you created
    shared/  docs shared with you by others
             - does NOT include docs you own and shared with others;
               those are still in owned/.

  gdoc.json structure (the Google Docs API documents.get response, read
  with includeTabsContent=true so every tab is present):
    {
      "documentId": "...",
      "title": "...",
      "tabs": [                          # one entry per top-level tab
        {
          "tabProperties": {
            "tabId": "t.0",              # names a tab for gws docs write
            "title": "Tab 1",
            "index": 0
          },
          "documentTab": {
            "body": {
              "content": [
                {                          # one element per block
                  "paragraph": {
                    "elements": [
                      { "textRun": { "content": "the actual text\n",
                                     "textStyle": {...} } }
                    ],
                    "paragraphStyle": {...}
                  }
                },
                { "table": {...} },
                { "sectionBreak": {...} }
              ]
            },
            "documentStyle": {...},
            "namedStyles": {...}
          },
          "childTabs": [ { ...same shape, nested to any depth... } ]
                                       # a NESTED tab additionally carries
                                       # parentTabId and nestingLevel; a
                                       # root tab carries neither
        }
      ],
      "revisionId": "..."
    }

  There is no top-level .body. A tab-aware response leaves the singleton
  fields (.body, .documentStyle, .namedStyles) empty and hangs every
  tab's content off .tabs[].documentTab instead. Tabs also nest, so text
  can sit at any depth under .childTabs; the recursive recipes below read
  a one-tab and a fifty-tab document alike.

  Useful jq paths:
    .title
    [.. | .tabProperties? // empty | .title]             # every tab name
    [.. | .textRun? // empty | .content] | add           # all text, any depth
    [.. | .tabProperties? // empty] | length             # tab count
    [.tabs[0].documentTab.body.content[]
      | .paragraph?.elements[]?.textRun.content] | add   # first tab only
    .revisionId

  The first block of a body is always a sectionBreak, which carries no
  .paragraph, so a path through .paragraph needs the `?` or it fails with
  "Cannot iterate over null".

  Delete, on a `write` path:
    rm /<path>/owned/<file>.gdoc.json      # permanent delete from Drive
    rm -f <path>                            # ignore if missing
    Only operates on .gdoc.json files; owned/ and shared/ themselves
    cannot be removed.

  Rename to a new title, on a `write` path:
    mv /<path>/owned/<date>_<old>__<id>.gdoc.json \
       /<path>/owned/<date>_<new>__<id>.gdoc.json
    Keep the folder, the date and the id, and spell the title the way
    the listing does (spaces->_); any other name is refused.

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 `mv`, `rm` and `unlink`. `grep -r` and `rg` with `-w` ask `gdocs` 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`, `rm -r`, `rmdir`, `truncate`, `sed -i`. Without `-w`, `grep -r` and `rg` read every 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.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `gdocs`, write |

## `/<path>` layout

```text
/<path>
  owned/
    <date>_<title>__<doc-id>.gdoc.json
  shared/
    <date>_<title>__<doc-id>.gdoc.json

  Filename: <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json
    <YYYY-MM-DD>  modifiedTime, used for date-glob (e.g. 2026-05-*)
    <title>       sanitized: spaces->_, non-[A-Za-z0-9_.-]->_, <=100 chars
    <doc-id>      Google Docs document ID

  Buckets:
    owned/   docs you created
    shared/  docs shared with you by others
             - does NOT include docs you own and shared with others;
               those are still in owned/.

  gdoc.json structure (the Google Docs API documents.get response, read
  with includeTabsContent=true so every tab is present):
    {
      "documentId": "...",
      "title": "...",
      "tabs": [                          # one entry per top-level tab
        {
          "tabProperties": {
            "tabId": "t.0",              # names a tab for gws docs write
            "title": "Tab 1",
            "index": 0
          },
          "documentTab": {
            "body": {
              "content": [
                {                          # one element per block
                  "paragraph": {
                    "elements": [
                      { "textRun": { "content": "the actual text\n",
                                     "textStyle": {...} } }
                    ],
                    "paragraphStyle": {...}
                  }
                },
                { "table": {...} },
                { "sectionBreak": {...} }
              ]
            },
            "documentStyle": {...},
            "namedStyles": {...}
          },
          "childTabs": [ { ...same shape, nested to any depth... } ]
                                       # a NESTED tab additionally carries
                                       # parentTabId and nestingLevel; a
                                       # root tab carries neither
        }
      ],
      "revisionId": "..."
    }

  There is no top-level .body. A tab-aware response leaves the singleton
  fields (.body, .documentStyle, .namedStyles) empty and hangs every
  tab's content off .tabs[].documentTab instead. Tabs also nest, so text
  can sit at any depth under .childTabs; the recursive recipes below read
  a one-tab and a fifty-tab document alike.

  Useful jq paths:
    .title
    [.. | .tabProperties? // empty | .title]             # every tab name
    [.. | .textRun? // empty | .content] | add           # all text, any depth
    [.. | .tabProperties? // empty] | length             # tab count
    [.tabs[0].documentTab.body.content[]
      | .paragraph?.elements[]?.textRun.content] | add   # first tab only
    .revisionId

  The first block of a body is always a sectionBreak, which carries no
  .paragraph, so a path through .paragraph needs the `?` or it fails with
  "Cannot iterate over null".

  Delete, on a `write` path:
    rm /<path>/owned/<file>.gdoc.json      # permanent delete from Drive
    rm -f <path>                            # ignore if missing
    Only operates on .gdoc.json files; owned/ and shared/ themselves
    cannot be removed.

  Rename to a new title, on a `write` path:
    mv /<path>/owned/<date>_<old>__<id>.gdoc.json \
       /<path>/owned/<date>_<new>__<id>.gdoc.json
    Keep the folder, the date and the id, and spell the title the way
    the listing does (spaces->_); any other name is refused.
```

## 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 `mv`, `rm` and `unlink`. `grep -r` and `rg` with `-w` ask `gdocs` 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`, `rm -r`, `rmdir`, `truncate`, `sed -i`. Without `-w`, `grep -r` and `rg` read every 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.

/gdocs/
  owned/
    <YYYY-MM-DD>_<sanitized-title>__<doc-id>.gdoc.json
    ...
  shared/
    <YYYY-MM-DD>_<sanitized-title>__<doc-id>.gdoc.json
    ...

Example:

/gdocs/
  owned/
    2026-04-04_Project_Plan__1AbCdEf.gdoc.json
    2026-04-10_Meeting_Notes__2BcDeFg.gdoc.json
  shared/
    2026-04-03_Design_Notes__9XyZ.gdoc.json

Documents are split into owned (documents you created) and shared (documents shared with you). The filename shape is:

<YYYY-MM-DD>_<sanitized-title>__<document-id>.gdoc.json

If the modified date is unavailable, the date prefix is omitted. Reading a document file returns the full Google Docs API JSON for that document.

Shared Drives

The listing covers every corpus the account can reach, so a document that lives in a Shared Drive appears here too. A Shared Drive document has no owner (the drive owns it), so it lands under shared, which is what that directory means. This matches the gdrive mount, where Shared Drives are top-level directories: without it the same account would see a document under one Google mount and not the other, with no error explaining the difference. Drive answers an all-corpora search best-effort. When it reports that it skipped a corpus, the short listing is still returned but is not cached as the directory, so the next ls re-lists instead of serving the gap until the cache expires.

Cache

The Google Docs VFS uses IndexCacheStore. Index entries store document IDs and metadata. File bytes go through the workspace file cache; a rendered read through FUSE, ws.vfs, a < file redirect or a cross-mount cp, sed or diff is not cached.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.commands.cli.builtin.gws import GWS
from mirage.vfs.gdocs import GDocsConfig, GDocsVFS

load_dotenv(".env.development")

config = GDocsConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
vfs = GDocsVFS(config=config)


async def main():
    ws = Workspace({"/gdocs": vfs}, mode=MountMode.READ)
    ws.register_cli("gws", GWS, config)

    # List structure
    r = await ws.shell("ls /gdocs/")
    print(await r.stdout_str())

    # List owned documents
    r = await ws.shell("ls /gdocs/owned/")
    print(await r.stdout_str())

    # Read a document
    r = await ws.shell(
        "cat /gdocs/owned/2026-04-04_Project_Plan__1AbCdEf.gdoc.json")
    print(await r.stdout_str())

    # Extract title with jq
    r = await ws.shell(
        'jq ".title"'
        " /gdocs/owned/2026-04-04_Project_Plan__1AbCdEf.gdoc.json")
    print(await r.stdout_str())

    # Search across all documents
    r = await ws.shell('rg "quarterly" /gdocs/owned/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.shell("tree -L 1 /gdocs/")
    print(await r.stdout_str())

    # Create a new document
    r = await ws.shell(
        'gws docs documents create --json \'{"title":"MIRAGE Example Doc"}\'')
    print(await r.stdout_str())

    # Append text to a document
    r = await ws.shell(
        'gws docs write --document 1AbCdEf --text "Appended via MIRAGE."')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

See examples/python/vfs/gdocs/gdocs.py for the full working example.

Shell Commands

Standard commands available on the mounted Google Docs tree:

Command	Notes
`ls`	List owned/shared documents
`cat`	Read document JSON
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search
`jq`	Query JSON fields
`wc`	Line/word/byte counts
`stat`	File metadata
`find`	Recursive search
`tree`	Directory tree view
`basename` / `dirname` / `realpath`	Path utilities
`nl`	Number lines
`mv`	Retitle a document (`MountMode.WRITE`)
`rm`	Delete a document (`MountMode.WRITE`)

Integration

What Google Docs answers through its own API, so fewer files are read. Integration explains each command.

Command	On Google Docs
`grep -r`, `rg`	Drive full-text search, for whole words. It can miss words only in non-text values (fonts, links and ids) or split by styling.

grep -rw and rg -w read only the documents Drive full-text search names; every one is read when the search fails or finds nothing. A word the rendered JSON may hold whatever the text says is never asked: one with a digit, a property name or enum value of the Docs API (paragraph, NORMAL_TEXT), or a word every rendering carries (https, arial). walk_limit: -1 in the mount’s "@all" command limit reads every file instead, since Drive indexes a write some time after it lands and searches the file’s text, so one whose JSON holds the word only in another value (a font, a link or image address, a tab title or an id), or only as part of a word styling splits into text runs (snow bold in snowman), can be left out. Acting on documents (appending text, raw API calls) goes through the gws CLI when installed.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Shared Drives

Cache

Example

Shell Commands

Integration

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Shared Drives

​Cache

​Example

​Shell Commands

​Integration

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Shared Drives

Cache

Example

Shell Commands

Integration