file-organizer

File Organizer

An LLM-powered file organizer that reads file contents, proposes a sensible folder structure with renamed files, and executes moves in chunks — with a mandatory user confirmation gate before any filesystem changes.

Overview

Inspired by LlamaFS but designed for Hermes: the script handles filesystem I/O (scan, read snippets, execute moves). The agent's own LLM does the reasoning by default. An optional propose subcommand can call a cheaper external LLM (deepseek, openrouter, ollama) for cost-conscious runs on large directories. Uses stdlib-only HTTP (urllib) — no requests/openai SDK needed.

When to Use

• User says "organize my Downloads" / "tidy my Desktop" / "clean up this folder"
• User has a messy directory and wants files sorted into categories
• User wants files renamed based on their content (not just moved)
• User wants to organize files on a local disk, network mount, or remote filesystem

Don't use for:

• Bulk file deletion (this skill only moves and renames, never deletes)
• Deduplication (use a dedicated dedup tool)
• File content search (use search_files instead)

Workflow

Step 1 — Scan

Run the scan script to get file metadata + content snippets:

python3 scripts/organize.py scan --path <directory> [--depth N] [--max-snippet-chars 500]

Output is a JSON array. Each file entry contains:

• path: full file path
• relative_path: path relative to scanned directory
• name: current filename
• size: bytes
• mtime: ISO timestamp
• type: text, image, audio, pdf, office, archive, other
• mime: detected MIME type
• snippet: first N chars of content (text/pdf) or metadata (image/audio)

Flags: --depth N (max directory depth), --max-snippet-chars N (per-file snippet limit, default 500), --include-hidden (include dotfiles, skipped by default).

Step 2 — Propose Organization (Agent LLM — Default)

Using the scan output, reason about:

• Natural categories based on file content and types
• A clean folder hierarchy (not too deep — 2-3 levels max)
• Descriptive filenames that reflect content (not IMG_3847.jpg → Hawaii-Beach-Sunset.jpg)
• Time-based grouping when appropriate (e.g., 2024-Taxes/, 2023-Receipts/)