desktop-organizer

What It Does

Watchdog daemon that runs in the background and watches ~/Desktop. Whenever a new file lands, it analyzes the contents with GPT-4o (vision for images and PDFs, GPT-4o-mini for metadata-only), suggests a PARA folder destination inside Google Drive, announces the suggestion via say, and pops a native macOS dialog asking Move or Skip. One file at a time, conversational, no auto-move surprises.

When To Use

• When the Desktop is becoming a swamp and you want the AI to nudge you on every new file before it disappears into clutter.
• As a continuous background service — runs all day, asks one question at a time as files appear.
• For one-off cleanup sweeps with --sweep to process the existing pile before going into watch mode.

How It Works

1. File lands on ~/Desktop.
2. 2-second settle check (waits for size to stabilize so it does not analyze a half-downloaded file).
3. AI analyzes contents — vision for images and PDFs, metadata only for everything else.
4. say announces the file and the suggested PARA destination.
5. macOS dialog pops with Move / Skip.
6. File moves to the picked PARA folder in Google Drive, or stays put.

Where It Lives

• Repo: ~/apps/desktop-organizer/
• OpenAI key: loaded from shared-secrets.env via config.py
• PARA root: ~/Library/CloudStorage/GoogleDrive-ojhurst@gmail.com/My Drive/

Architecture

File	Purpose
config.py	Paths, constants, env loader (OpenAI key)
analyzer.py	File analysis via OpenAI API (vision + text models)
organizer.py	Speech (say), macOS dialogs (osascript), file moving
watcher.py	Entry point, watchdog handler, queue-based main loop

Usage

source .venv/bin/activate
python3 watcher.py              # Watch mode — runs forever
python3 watcher.py --sweep      # Process existing files first, then watch
python3 watcher.py --dry-run    # Analyze only, do not move
python3 watcher.py --sweep --dry-run  # Analyze existing pile, no moves, exit

PARA Destinations

Folder	Use For
1 Projects/	Active projects with goal + deadline
2 Areas/	Ongoing responsibilities
3 Resources/	Reference material by topic
4 Archive/	Completed / inactive

Dependencies

Python 3, watchdog, openai, plus the macOS built-ins say, osascript, sips, and qlmanage.

Known Gaps / Quirks

• macOS only — relies on say and osascript for the announce + prompt loop.
• Costs OpenAI tokens per file. Vision calls on PDFs and images are not free; metadata-only calls are nearly free.
• Suggestion quality is whatever GPT-4o produces. The dialog always lets you Skip, so a bad suggestion costs one click, not a misfiled file.