Local File Organizer

This software uses AI to organize your local files. It operates locally with Ollama. It does not need a cloud connection. You can also connect it to an OpenAI-compatible endpoint or Anthropic Claude.

Contents

• Features
• How It Works
• Interfaces
• Quick Start (Essentials)
• Documentation
• Optional Feature Packs
• Development
• Contributing
• Configuration
• License

Features

AI and Analysis

• AI-Powered Analysis: Uses Qwen 2.5 3B (text) and Qwen 2.5-VL 7B (vision) with Ollama, OpenAI-compatible endpoints, or Anthropic Claude (see analysis.inspect).
• Audio Transcription: Uses faster-whisper to convert local speech to text (requires optional [audio] extra; see audio.transcribe).
• Video Analysis: Finds scenes and gets keyframes from video files (requires optional [video] extra; see video.analyze).
• Intelligence: Learns patterns, tracks preferences, suggests actions, and adds tags automatically (see automation.suggestions and automation.tags).

Interfaces

• Terminal UI: Gives an 8-view Textual TUI (see interfaces.launch).
• Web UI: Browser interface powered by FastAPI and HTMX (see web-desktop surface status).
• Desktop App: Native OS window using pywebview (shares the web-desktop surface adapter in a single Python process).
• Full CLI: Includes commands to organize, set rules, suggest, find duplicates, run as a daemon, show analytics, update, and manage API keys (see cli surface status).
• Copilot Chat: Accepts natural language commands such as "organize ./Downloads" or "undo" (see copilot.chat).

Organization

• Product Capability Matrix: Built on 34 product capabilities across 6 official surfaces, with automated cross-surface parity enforcement (conformance-verified for organization.execute, organization.preview, organization.scan, and methodology.configure).
• Organization Rules: Sorts files automatically with conditions and previews (see automation.rules).
• PARA + Johnny Decimal: Supports canonical organization methodologies (see methodology.configure).
• Deduplication: Finds duplicate files with hash and semantic checks (requires optional [dedup] extra; see deduplication.manage).
• Undo/Redo: Keeps operation history so you can undo changes safely (see history.manage).
• Auto-Update: Manages application updates safely across platforms (see updates.manage).
• Cross-Platform: Operates on macOS, Windows, and Linux (see cli surface status).

How It Works

flowchart LR
    subgraph Source["Source Directory"]
        direction TB
        A[report.pdf]
        B[photo.jpg]
        C[meeting.mp3]
        D[clip.mp4]
    end

    subgraph AI["AI Analysis"]
        direction TB
        E[Content Extraction]
        F[AI Categorize]
    end

    subgraph Output["Organized Output"]
        direction TB
        G[Work/Reports/]
        H[Photos/Vacation/]
        I[Audio/Meetings/]
    end

    Source --> E --> F --> Output
    F -.-> |Learn Patterns| F

Loading

1. Scan — The software reads files from a source directory. It gets text, metadata, and visual content. It supports more than 80 formats.
2. Analyze — The software sends the content to an AI model. The model categorizes and names the files.
3. Organize — The software moves or copies files into folders. It uses the AI-generated names.
4. Learn — The software tracks your patterns and preferences to make better suggestions in the future.

Interfaces (Visuals)

Terminal UI

Web UI (Preview)

To start the FastAPI server and open the UI, type this command:

file-organizer serve --reload

Then, go to http://localhost:8000/ui/ in your browser.

Quick Start (Essentials)

With Ollama (local, default)

# Install from PyPI with pipx:
pipx install local-file-organizer
# or with pip:
pip install local-file-organizer

# 1) Set the default configuration
fo setup

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

# 3) Start the organization process
fo organize ~/Downloads ~/Organized

# 4) Undo the most recent organize run if necessary
fo undo

Use cloud providers instead of the default local flow

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

# OpenAI-compatible providers
export FO_PROVIDER=openai

# Anthropic Claude
export FO_PROVIDER=claude

Documentation

Essentials

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

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 installation commands:

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

From source (development): Download the repository and use an editable install (for example, pip install -e ".[all]").

Audio system dependencies

To get full audio format support, the [audio] pack uses FFmpeg (all platforms). It optionally uses CUDA + cuDNN (for NVIDIA GPU users).

FFmpeg — This is necessary for non-.wav formats (MP3, M4A, FLAC, OGG). It is optional if you only transcribe raw .wav files:

# macOS
brew install ffmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

# Windows (winget)
winget install ffmpeg

CUDA + cuDNN — This is optional. It makes transcription much faster.

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

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

Fallback behavior: If you do not have FFmpeg, the software only transcribes .wav files. It organizes other formats by filename and metadata, but it does not analyze their content. If you do not have CUDA, the transcription uses the CPU. This is slower but it operates correctly.

Read the Installation Guide to find troubleshooting steps and advanced configuration options.

Development

# Start tests
pytest

# Find errors with ruff
ruff check src/

(To see a full breakdown of the project structure, read CONTRIBUTING.md)

Contributing

Read CONTRIBUTING.md to learn about the development setup, coding standards, project structure, and how to submit your changes.

Configuration

The software stores configuration files in these locations:

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

Read the Configuration Guide for more data.

License

This project uses the MIT License.

---

Status: Stable | Version: 2.1.1 | Last Updated: 2026-07-20