Metadata-Version: 2.4
Name: catoptromancy
Version: 0.2.1
Summary: Mirror Google Drive folders to local directories with format conversion
Project-URL: Homepage, https://github.com/terra-hq/catoptromancy
Project-URL: Repository, https://github.com/terra-hq/catoptromancy
Project-URL: Issues, https://github.com/terra-hq/catoptromancy/issues
Author: Nathaniel Kelner
License-Expression: MIT
License-File: LICENSE
Keywords: cli,google-drive,mirror,sync
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: google-api-python-client>=2.100
Requires-Dist: google-auth-oauthlib>=1.2
Requires-Dist: google-auth>=2.25
Requires-Dist: rich>=13.0
Requires-Dist: tenacity>=8.2
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: responses>=0.23; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

[![ascii-art-(3).jpg](https://i.postimg.cc/zffQBPSY/ascii-art-(3).jpg)](https://postimg.cc/QFRmYmyf)
# 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

```bash
uv tool install catoptromancy
```

### Install Into The Current Environment

```bash
uv pip install catoptromancy
```

### Updating

If installed as a tool:

```bash
uv tool upgrade catoptromancy
```

If installed into a virtualenv:

```bash
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:

```bash
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:

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

### Pull Files

```bash
cato pull
```

### Force A Full Re-Download

```bash
cato pull --force
```

### Check Status

```bash
cato status
```

### Re-Authenticate

```bash
cato auth
```

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

### Show Command Help

```bash
cato --help
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and release instructions.
