catoptromancy 0.2.0

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

Install the latest version directly from Git:

uv tool install git+ssh://[e-mail]/terra-hq/catoptromancy.git

Install Into The Current Environment

Install the package into the current virtualenv:

uv pip install git+ssh://[e-mail]/terra-hq/catoptromancy.git

Updating

If installed as a tool:

uv tool upgrade catoptromancy

If installed into a virtualenv:

uv pip install --upgrade git+ssh://[e-mail]/terra-hq/catoptromancy.git

Development Setup

Clone the repo, then install the project and dev dependencies:

git clone [e-mail]:terra-hq/catoptromancy.git
cd catoptromancy
uv sync --extra dev

That creates or updates .venv/ with the package, pytest, ruff, and the other development dependencies.

Run the test suite with:

.venv/bin/pytest -q

Run the CLI from the project environment with:

.venv/bin/cato --help

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.

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

Show Command Help

cato --help

Packaging

Catoptromancy is packaged as a standard Python project. Build configuration lives in pyproject.toml and uses hatchling.

Build Distributable Artifacts

uv build

This creates:

• dist/*.whl
• dist/*.tar.gz

Verify A Built Wheel Locally

uv pip install dist/*.whl

Publish A Release

1. Bump the version in pyproject.toml.
2. Run uv build.
3. Publish the contents of dist/ to your package index.

Console Script

cato