catoptromancy 0.2.1

Mirror Google Drive folders to local directories with format conversion

Catoptromancy — divination by mirrors.

SOTA coding agents like Claude Code and Codex turn out to be very good everything agents. Indeed, Claude Cowork, Anthropic's all-purpose agent, is a close cousin of Claude Code and is built on the same stack (the anthropic agent SDK). And so agents (with or without coding) work best when situated in an actual folder of files. They like reading text files, searching Excel, and exploring folder structures. They have the best tools for exploring and understanding knowledge and context when it's organized in a file system.

Google Drive Folders, while extremely useful for collaboration, are not actually filesystems. Behind the scenes, you can't download a Google Doc into a real file. Even the Google Drive Mac Apps just syncs links to files, not the actual files themselves. This makes it surprisingly hard to point an agent at a Google Drive folder and get the results you expect.

To solve this problem, Catoptromancy mirrors Google Drive folders into a local workspace where AI agents can actually work and into formats they can actually use. cato currently converts Google Docs to Markdown, Sheets to Excel, and Slides to PowerPoint.

This local copy also acts as a sandbox. Agents can read, edit, and create freely without touching the original data. Nothing syncs back to Drive. This version supports pull-only mirroring, so remote changes come down locally, but there is no push command yet.

Installation

Install As A Tool

uv tool install catoptromancy

Install Into The Current Environment

uv pip install catoptromancy

Updating

If installed as a tool:

uv tool upgrade catoptromancy

If installed into a virtualenv:

uv pip install --upgrade catoptromancy

Authentication

OAuth credentials are bundled in the package — no Google Cloud setup required. Running cato init opens a browser for Google account authorization. Your refresh token is cached locally at ~/.config/catoptromancy/token.json.

In headless or sandboxed environments (e.g. Claude Code), the browser can't open automatically. In that case, cato prints an authorization URL — open it in any browser, authorize, then paste the redirect URL back into the terminal.

To use your own OAuth client instead, pass --credentials /path/to/credentials.json to cato init.

For service-account auth, pass --service-account /path/to/service-account.json to cato init instead of using OAuth.

Usage

Initialize A Workspace

cato init opens a browser for consent:

cato init <FOLDER_ID_OR_URL>

The folder reference can be either:

• A raw Google Drive folder ID
• A full Google Drive folder URL

The folder ID is the last part of a Drive folder URL:

https://drive.google.com/drive/folders/<THIS_PART>

Pull Files

cato pull

Force A Full Re-Download

cato pull --force

Check Status

cato status

Re-Authenticate

cato auth

Use cato auth --reset to delete the cached OAuth token and re-authorize from scratch.

Show Command Help

cato --help

Contributing

See CONTRIBUTING.md for development setup, testing, and release instructions.