# gdrive-org

**AI-Powered Digital Minimalist Google Drive CLI & MCP Server**

`gdrive-org` helps you declutter, organize, and regain control over your Google Drive. It features AI-assisted semantic deduplication, three-tier duplication removal, macOS Drive File Stream cache monitoring, config-driven folder cleaning, and a native **Model Context Protocol (MCP)** server for AI agents (Claude Desktop, Cursor, Antigravity, etc.).

---

## Features

- 🧹 **Clean Empty Folders**: Identify and prune empty folder hierarchies recursively.
- 📦 **Storage & Cache Analysis**: Inspect cloud quota usage and macOS local DriveFS cache footprint.
- 🔍 **File Audit**: Detect oversized items, root directory clutter, orphaned files, and shortcuts.
- 👯 **Byte-Exact Deduplication**: Safely identify duplicate files by MD5 hash and batch-trash duplicates while preserving the oldest original.
- 🧠 **Smart AI Deduplication**: Cluster semantically similar documents with Gemini AI and consolidate them into a Single Source of Truth doc.
- 📁 **Config-Driven Folder Cleaner**: Classify, flatten, and clean specific folders according to customized YAML rules.
- 🤖 **Native MCP Server**: Expose Drive management tools directly to LLMs and agentic IDEs via Model Context Protocol.
- 🍏 **macOS Sync Health**: Monitor local Google Drive for Desktop sync health and cache size.
- 🛡️ **Safe by Default**: All destructive operations default to dry-run mode, respect a 30-day Drive Trash recovery window, and support resuming interrupted batch jobs.

---

## Installation

### Standalone CLI (Recommended)

Using [`uv`](https://github.com/astral-sh/uv) or `pipx`:

```bash
uv tool install gdrive-org
# or
pipx install gdrive-org
```

Or run directly without permanent installation via `uvx`:

```bash
uvx gdrive-org --help
```

### From Source (Development)

```bash
git clone https://github.com/yourusername/google-drive-organization.git
cd google-drive-organization
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

---

## Configuration & Credentials

### 1. Google Drive API (OAuth 2.0)

1. Open the [Google Cloud Console](https://console.cloud.google.com).
2. Create a new project (e.g. `gdrive-org`).
3. Under **APIs & Services** > **Library**, enable the **Google Drive API**.
4. Under **APIs & Services** > **Credentials**, click **Create Credentials** > **OAuth client ID**.
5. Select **Desktop app** as the application type.
6. Download the resulting credentials JSON file.
7. Save it to `~/.config/gdrive-org/credentials.json` (or place it in your local directory as `credentials.json`):
   ```bash
   mkdir -p ~/.config/gdrive-org
   cp /path/to/downloaded-credentials.json ~/.config/gdrive-org/credentials.json
   ```

### 2. Gemini API Key (for Smart Dedupe & Cluster Merge)

1. Obtain an API key from [Google AI Studio](https://aistudio.google.com).
2. Add it to `~/.config/gdrive-org/.env`:
   ```env
   GOOGLE_API_KEY=your_gemini_api_key_here
   ```
   *(Alternatively, export `GOOGLE_API_KEY` in your shell environment).*

---

## CLI Usage

### Authentication
Test and authorize your Google Drive credentials (opens a browser window for first-time login):
```bash
gdrive-org auth
```

### Storage & Sync Audit
```bash
gdrive-org storage                     # View cloud quota and local cache footprint
gdrive-org audit --min-size 50         # List items >= 50MB and audit root clutter
gdrive-org sync-health                 # Check macOS Drive File Stream cache and health
gdrive-org explain-sync                # Guide for Stream vs Mirror sync modes
```

### Deduplication
Find exact byte-identical duplicates (dry-run):
```bash
gdrive-org dedupe
```
Execute deduplication (moves duplicates to Trash, keeps oldest original):
```bash
gdrive-org dedupe --no-dry-run
```
Exclude specific directories:
```bash
gdrive-org dedupe --exclude-folder "Archive" --exclude-folder "Backups"
```

### Smart AI Deduplication
Scan for semantic duplicates and manage proposed merge clusters:
```bash
gdrive-org smart-dedupe                # Cluster related docs and propose merges
gdrive-org merge approve <cluster-id>  # Finalize merged Google Doc & trash originals
gdrive-org merge reject <cluster-id>   # Discard proposed merge
```

### Folder Cleaning & Empty Folder Pruning
Remove empty directories:
```bash
gdrive-org clean-empty                 # Dry-run
gdrive-org clean-empty --no-dry-run    # Delete empty folders
```

Clean a specific folder using a custom YAML rule set:
```bash
gdrive-org clean-folder <folder-id> --config /path/to/rules.yaml
gdrive-org clean-folder <folder-id> --config /path/to/rules.yaml --no-dry-run
```

### Archiving & Recovery
Archive unorganized old root files to `Archive/<Year>`:
```bash
gdrive-org archive --months 6          # Dry-run files unaccessed for 6 months
gdrive-org archive --months 6 --no-dry-run
```
Resume interrupted batch operations:
```bash
gdrive-org resume
```

---

## Model Context Protocol (MCP) Integration

`gdrive-org` can run as an MCP server, allowing agents like **Claude Desktop**, **Cursor**, or **Antigravity** to safely analyze, deduplicate, and organize your Google Drive.

### Start the Server Directly
```bash
gdrive-org mcp
# or with uvx:
uvx gdrive-org mcp
```

### Client Configuration

Add `gdrive-org` to your MCP client config (e.g. `claude_desktop_config.json`, Antigravity `mcp_config.json`, or Cursor):

```json
{
  "mcpServers": {
    "gdrive-org": {
      "command": "uvx",
      "args": ["gdrive-org", "mcp"]
    }
  }
}
```

*(During local development before PyPI installation, point `command` to your local `.venv/bin/gdrive-org` and `args` to `["mcp"]`).*

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `show_storage` | Quota audit and macOS cache footprint |
| `show_audit` | Drive categories, root clutter, and orphaned files |
| `show_sync_health` | macOS DriveFS status and cache size |
| `explain_sync` | Streaming vs Mirroring guidance |
| `scan_exact_duplicates` | Find exact byte-identical duplicates (dry-run) |
| `execute_exact_dedupe` | Move duplicate files to Trash (keeps oldest) |
| `scan_semantic_duplicates` | AI cluster scan for near-duplicate documents |
| `stage_merge_cluster` | Consolidate cluster into a merged Google Doc |
| `approve_merge` / `reject_merge` | Finalize or discard staged merge drafts |
| `scan_empty_folders` / `execute_clean_empty` | Prune empty directory trees |
| `scan_archivable_files` / `execute_archive` | Organize old root files into year-based archives |
| `resume_failed_operation` | Recover from interrupted batch operations |

---

## Safety Guidelines

1. **Dry-Run by Default**: All bulk modifications and deletions run in dry-run mode until `--no-dry-run` or an explicit execute action is triggered.
2. **30-Day Trash Recovery**: Deletions move files to Google Drive's native Trash. Files can be restored within 30 days.
3. **Audit Trail**: Every destructive action is logged to enable state recovery and rollback analysis.
4. **Local Cache Safety**: Never manually delete files inside `~/Library/Application Support/Google/DriveFS`. Use `gdrive-org sync-health` and Google Drive preferences to clear streaming cache safely.

---

## License

MIT License — see [LICENSE](LICENSE) for details.