local-file-organizer 2.0.0

AI-powered local file management with state-of-the-art models

File Organizer v2.0

AI-powered local file management. Local-first by default (Ollama, no cloud required) -- or connect any OpenAI-compatible endpoint or Anthropic Claude when you need it.

840 tests | 408 modules | 39 file types

Contents

• Features
• How It Works
• Quick Start
• Web UI
• Documentation
• Optional Feature Packs
• Project Structure
• Development
• Contributing
• Configuration
• License

Features

AI and Analysis

• AI-Powered Organization: Qwen 2.5 3B (text) + Qwen 2.5-VL 7B (vision) via Ollama — or any OpenAI-compatible endpoint (OpenAI, LM Studio, vLLM) — or Anthropic Claude
• Audio Transcription: Local speech-to-text with faster-whisper (GPU-accelerated)
• Video Analysis: Scene detection and keyframe extraction
• Intelligence: Pattern learning, preference tracking, smart suggestions, auto-tagging

Interfaces

• Terminal UI: 8-view Textual TUI (Files, Analytics, Audio, History, Copilot, and more)
• Web UI: Browser-based interface via FastAPI and HTMX
• Desktop App: Native OS window via pywebview — single Python process, no Electron, no Rust
• Full CLI: Organize, rules, suggest, dedupe, daemon, analytics, update, api-keys
• Copilot Chat: Natural-language assistant -- "organize ./Downloads", "find report.pdf", "undo"

Organization

• Organization Rules: Automated sorting with conditions, preview, and YAML persistence
• PARA + Johnny Decimal: Built-in organizational methodologies
• Deduplication: Hash and semantic duplicate detection
• Undo/Redo: Full operation history
• Auto-Update: Linux AppImage self-updates from GitHub Releases (verified downloads + rollback); macOS/Windows update via pip/pipx
• Cross-Platform: Runs on macOS, Windows, and Linux (verified in CI). Linux ships a standalone AppImage plus executables; install on macOS/Windows via pip/pipx

How It Works

 Source Directory          AI Analysis              Organized Output
┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐
│  ./Downloads │     │  Content         │     │  ./Organized     │
│              │     │  Extraction      │     │                  │
│  report.pdf  │────>│  (text, vision,  │────>│  Work/           │
│  photo.jpg   │     │   audio, video)  │     │    Reports/      │
│  meeting.mp3 │     │                  │     │  Photos/         │
│  clip.mp4    │     │  AI Categorize   │     │    Vacation/     │
│  notes.txt   │     │  (Ollama/OpenAI/ │     │  Audio/          │
│              │     │   Claude)        │     │    Meetings/     │
└──────────────┘     └──────────────────┘     └──────────────────┘
                              │
                     ┌────────┴────────┐
                     │  Learn & Adapt  │
                     │  (patterns,     │
                     │   preferences,  │
                     │   rules)        │
                     └─────────────────┘

1. Scan — Reads files from a source directory, extracting text, metadata, and visual content per file type (80+ formats supported)
2. Analyze — Sends extracted content to an AI model (Ollama, OpenAI, or Claude) for categorization and naming
3. Organize — Moves or copies files into a structured folder hierarchy with AI-generated names
4. Learn — Tracks your patterns and preferences over time for smarter future suggestions

Screenshots

Quick Start (Essentials)

With Ollama (local, default)

# Install from PyPI — pipx keeps it isolated and on your PATH:
pipx install local-file-organizer
# or: pip install local-file-organizer

# 1) Configure defaults
fo setup

# 2) Preview a folder before changing anything
fo preview ~/Downloads

# 3) Run organization
fo organize ~/Downloads ~/Organized

# 4) Roll back the most recent organize run if needed
fo undo

Prefer a browser?

file-organizer serve --reload

Then visit http://localhost:8000/ui/.

Need cloud providers instead of the default local flow?

Use the AI Provider Setup guide for OpenAI-compatible endpoints and Claude.

# OpenAI-compatible providers
export FO_PROVIDER=openai

# Anthropic Claude
export FO_PROVIDER=claude

Web UI

Start the FastAPI server and open the UI:

file-organizer serve --reload

Then visit http://localhost:8000/ui/ for the HTMX interface.

Documentation

Essentials

• Documentation Home
• Getting Started
• CLI Reference
• User Guide Workflow Map
• Web UI Quick Start
• Troubleshooting

Advanced / Admin / Developer

• Full CLI Reference
• Terminal UI Guide
• Desktop App Guide
• AI Provider Setup
• Audio & Video Processing Guide
• Configuration Guide
• API Reference
• File Format Reference
• Path Standardization & Migration
• Johnny Decimal User Guide
• Johnny Decimal Migration Guide

Optional Feature Packs

Canonical extras matrix:

• Dependencies & Optional Extras

Common installs:

pip install "local-file-organizer[parsers,web]"
pip install "local-file-organizer[cloud,claude]"
pip install "local-file-organizer[all]"

From source (development): clone the repo and use an editable install instead, e.g. pip install -e ".[all]".

Audio system dependencies

For full audio format support, the [audio] pack uses FFmpeg (all platforms) and optionally CUDA + cuDNN (NVIDIA GPU users).

FFmpeg — required for non-.wav formats (MP3, M4A, FLAC, OGG); optional if you only transcribe raw .wav:

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows (winget)
winget install ffmpeg

CUDA + cuDNN — optional, for significantly faster transcription (see faster-whisper benchmarks for hardware-specific numbers):

# Install CUDA Toolkit from https://developer.nvidia.com/cuda-downloads
# Install cuDNN from https://developer.nvidia.com/cudnn

# Verify the full transcription backend (not just PyTorch)
python3 -c "from faster_whisper import WhisperModel; print('faster-whisper OK')"
python3 -c "import torch; print('CUDA:', torch.cuda.is_available())"

Fallback behavior: without FFmpeg, only .wav files are transcribed; other formats are organized by filename/metadata but not content-analyzed. Without CUDA, transcription runs on CPU (slower but fully functional).

See the Installation Guide for troubleshooting and advanced configuration.

Project Structure

Click to expand

src/file_organizer/
├── api/              # FastAPI web backend
├── cli/              # CLI commands and entry points
├── client/           # HTTP client utilities
├── config/           # Configuration management
├── core/             # Organization engine and business logic
├── daemon/           # Background file watcher daemon
├── deploy/           # Deployment helpers
├── desktop/          # Native desktop app (pywebview)
├── events/           # Event system
├── history/          # Operation history and undo/redo
├── integrations/     # External service integrations
├── interfaces/       # Abstract interfaces and protocols
├── methodologies/    # PARA, Johnny Decimal implementations
├── models/           # Data models
├── optimization/     # Performance optimization
├── parallel/         # Parallel processing
├── pipeline/         # File processing pipeline
├── plugins/          # Plugin system (audio, video, archives, etc.)
├── review_regressions/ # Code quality detectors
├── services/         # Core services (analytics, dedup, text, etc.)
├── tui/              # Textual terminal UI (8 views)
├── undo/             # Undo/redo infrastructure
├── updater/          # Auto-update from GitHub Releases
├── utils/            # Shared utilities
├── watcher/          # File system watcher
└── web/              # HTMX web UI templates and assets

Development

# Run tests
pytest

# Lint
ruff check src/

Contributing

See CONTRIBUTING.md for development setup, coding standards, and how to submit changes.

Configuration

Configuration is stored in platform-appropriate locations using platformdirs:

• macOS: ~/Library/Application Support/file-organizer/
• Linux: ~/.config/file-organizer/ (or $XDG_CONFIG_HOME/file-organizer/)
• Windows: %APPDATA%/file-organizer/

See Configuration Guide for details.

License

This project is licensed under the MIT License.

---

Status: Stable | Version: 2.0.0 | Last Updated: 2026-07-05