📁 files-organizer

Point files-organizer at a folder full of loose files. It reads each one, extracts metadata, and uses a small local LLM (Qwen2.5, via llama.cpp) to infer a clean, human-readable title, tags and file name. It generates thumbnails, builds a searchable SQLite catalog, and can either move & rename everything into tidy category folders — fully reversible — or just analyze in place without touching a single file.

No cloud. No API keys. No telemetry. Your files never leave your machine.

Example — IMG_2024_final (2).pdf → Nota Fiscal 004512 - Padaria Aurora.pdf (category: documentos)

flowchart TD
    IN["📁 Folder (inbox)"] --> SC["Scan<br/>sha256 + file type"]
    SC --> EX["Extract<br/>text · EXIF · metadata"]
    EX --> LLM["🧠 Local LLM (Qwen2.5)<br/>title · summary · tags · name"]
    LLM --> TH["🖼️ Thumbnail"]
    LLM --> MODE{"Mode"}
    MODE -->|"Organize"| ORG["Move + rename<br/>Category/Readable name"]
    MODE -->|"Analyze"| ANA["Catalog only<br/>nothing is moved"]
    ORG --> DB[("SQLite<br/>catalog + FTS5")]
    ANA --> DB
    TH --> DB
    ORG --> UND["_DEPARA.csv + Undo"]
    ANA --> REP["_ANALISE.csv"]
    DB --> EXP["🔎 Explorer<br/>search · grid · move/rename"]

1. Scan — walks the folder, computes a sha256 (dedup) and detects the real type by magic bytes.
2. Extract — pulls text from PDF/DOCX/TXT/MD, EXIF/size from images, and generic filesystem metadata.
3. Enrich (LLM) — the local model returns strict JSON: title, summary, category, tags, suggested_name. Falls back to a heuristic when no model is present.
4. Organize or Analyze — either move+rename into Category/ folders, or just catalog in place.
5. Catalog — everything lands in a WAL-mode SQLite database with full-text search (FTS5) and thumbnails.

• Organize — moves each file to Organized/<Category>/<readable name>.<ext>. The destination is cleaned into a timestamped _backup_…/ first (never deleted), and every action is reversible.
• Analyze only — reads and catalogs a folder in place (metadata, LLM title/tags, thumbnails, SQLite) and writes an _ANALISE.csv with suggestions. Nothing is moved or renamed. You can later open that folder in the Explorer and move/rename items one by one if you want.

Grab a build from Releases:

• files-organizer-<version>.zip — portable bundle (most reliable). See INSTALL.md.
• .exe (Windows) · .AppImage / .deb (Linux) — native installers, built by CI when available.

Then download the model once (auto-detected in models/):

bash models/download-model.sh                                   # Linux/macOS
powershell -ExecutionPolicy Bypass -File models\download-model.ps1   # Windows

Requirements: Python 3.10+ and Node.js 18+.

# Linux/macOS
bash scripts/setup.sh            # venv + deps + renderer build
bash scripts/install-linux.sh    # desktop shortcut (optional)
./run-app.sh

# Windows (PowerShell)
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1
powershell -ExecutionPolicy Bypass -File scripts\install-windows.ps1
.\run-app.bat

The UI is Electron; the heavy lifting is a persistent Python worker they talk to over stdio. The SQLite catalog is the shared state — Python writes it, the renderer reads it directly for a snappy UI.

flowchart LR
    subgraph UI["Electron · UI"]
        REN["Renderer (React)"]
        PRE["preload"]
        MN["main"]
        REN <--> PRE <--> MN
    end
    subgraph PY["Python · worker"]
        WK["worker (stdio)"]
        PIP["pipeline"]
        WK --> PIP
    end
    MN <-->|"newline-delimited JSON (stdio)"| WK
    PIP --> LC["llama.cpp<br/>Qwen2.5-0.5B"]
    PIP -->|"writes"| DB[("SQLite<br/>WAL · FTS5 · thumbs")]
    REN -.->|"reads (better-sqlite3)"| DB

backend/organizer/      # Python worker
  scan.py               # walk + sha256 + type detection
  extract/              # pdf, docx, txt, images (EXIF)
  llm.py                # llama.cpp wrapper + heuristic fallback
  organize.py           # move / rename / undo
  security.py           # safe archive inspection (no extraction)
  pipeline.py           # scan → extract → LLM → organize/analyze
  worker.py             # stdio JSON-RPC entrypoint
frontend/               # Electron + React + TypeScript
  electron/             # main · preload · worker bridge · sqlite reader
  src/                  # React UI (Organize / Explorer tabs)
scripts/                # setup, shortcut installers, icon/bg, release
models/                 # GGUF model (downloaded, not committed)

cd backend && python3 -m venv .venv && . .venv/bin/activate && pip install -e ".[dev]"
pytest                              # 26 backend tests (no model required)

cd ../frontend && npm install && npm run dev

PolyForm Noncommercial License 1.0.0 — free to download, use, study, modify and redistribute for non-commercial purposes. Commercial use is not permitted. See LICENSE.