Agentic File Organizer

A Python-based file organizer that asks for a folder path at startup, uses an LLM to decide a category and descriptive name for each file, and only moves files (never deletes).

It now supports richer file inspection tools:

• Text/code preview for common source and text formats
• PDF extraction
• DOCX/XLSX/PPTX extraction
• OCR for images (via docTR)
• VLM image understanding via Ollama (for image-only files)

Setup

From source

1. Create and activate a virtual environment.
2. Install dependencies:
   • pip install -e .
3. Install and run Ollama locally.
4. Run organize-files init --pull-models
5. OCR uses docTR; model weights are downloaded on first OCR run.
6. Copy .env.example to .env only if you want to override defaults while developing from source.

End-user install flow

1. Install Python
2. Install pipx
3. Install Ollama from https://ollama.com/download
4. Install the app:
   • pipx install agentic-file-organizer
5. Complete guided setup:
   • organize-files init --pull-models

Useful .env options:

• OLLAMA_MODEL (text LLM)
• OLLAMA_VLM_MODEL (image model)
• ENABLE_OCR=true|false
• ENABLE_VLM=true|false
• MAX_PREVIEW_CHARS=1200

Run

• python -m agentic_file_organizer.main
• or organize-files

CLI commands

• Guided setup:
  • organize-files init
• Guided setup + pull models:
  • organize-files init --pull-models
• Interactive mode:
  • organize-files
• Non-interactive organize:
  • organize-files organize /path/to/folder --preferences "group by project" --yes
• Preview only (no changes):
  • organize-files organize /path/to/folder --dry-run
• Skip verification pass:
  • organize-files organize /path/to/folder --no-verify --yes
• Environment/model health check:
  • organize-files doctor
• Pull missing required models:
  • organize-files setup-models

Recommended release model

• Publish the package to PyPI
• Have users install with pipx
• Keep Ollama and local models separate from the Python package
• Use organize-files init and organize-files doctor for setup validation

Safety

• Operates only on files directly inside the folder you manually enter.
• Moves files into category folders under that same root folder.
• Never deletes files.
• Prevents moving outside the chosen root.