An intelligent, ADHD-friendly file organization system that learns from your behavior.

• Smart Staging — 7-day observation period before organizing files
• Confidence-Based Decisions — NEVER/MINIMAL/SMART/ALWAYS modes
• Adaptive Learning — Learns from your corrections
• Bulletproof Deduplication — 3-tier verification (size → MD5 → SHA256)
• Emergency Space Protection — Automatic disk monitoring + cloud offload
• Rollback System — Undo any organization action
• Google Drive Integration — Optional cloud storage support
• Plugin System — Extend with custom classifiers

• Python 3.10+
• macOS, Linux, or Windows
• (Optional) Google Drive for cloud offloading

1. Clone the repository:

   git clone https://github.com/thebearwithabite/ai-file-organizer.git
   cd ai-file-organizer

2. Create virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure:

   cp config.example.yaml config.yaml
   # Edit config.yaml with your paths

5. Run:

   python main.py

6. Open http://localhost:8000 in your browser

See config.example.yaml for all options. Key settings:

storage:
  root: ~/Documents/AI-Organized    # Where organized files go
  metadata: ~/.ai-file-organizer    # Database storage
  staging: ~/.ai-file-organizer/staging

monitor:
  paths:
    - ~/Downloads
    - ~/Desktop

Create custom classifiers in plugins/. See plugins/README.md for the API.

MIT License — see LICENSE file.

Built by @thebearwithabite

Distribution extraction by:

• 🫧 Cosmo (Claude Opus 4.5) — Oversight & Direction
• 🧠 Jeeves (Claude Opus 4.6) — Builder & Implementation
• 🤖 Claude (Anthropic) — Architectural Review

Human out of the loop, agents in the arena.