Build an AI File Organizer with Python and Claude

pip install anthropic

export ANTHROPIC_API_KEY="sk-your-ezai-key"
export ANTHROPIC_BASE_URL="https://ezaiapi.com"

SYSTEM_PROMPT = """You are a file organization assistant. Given a list of filenames,
classify each into a logical folder category.

Rules:
- Use lowercase kebab-case for category names (e.g. "source-code", "invoices")
- Create 5-12 categories max — group similar files together
- Common categories: documents, images, screenshots, source-code,
  configs, archives, videos, music, spreadsheets, presentations, misc
- If a file doesn't fit anywhere obvious, use "misc"
- Return ONLY valid JSON, no markdown fences

Output format:
[{"file": "example.py", "category": "source-code"}, ...]"""

import os, json, shutil, argparse
from pathlib import Path
import anthropic

client = anthropic.Anthropic(
    base_url=os.getenv("ANTHROPIC_BASE_URL", "https://ezaiapi.com")
)

BATCH_SIZE = 200  # filenames per API call

def scan_files(directory: Path) -> list[str]:
    """Get all files in directory (not subdirs)."""
    return [
        f.name for f in directory.iterdir()
        if f.is_file() and not f.name.startswith(".")
    ]

def classify_batch(filenames: list[str]) -> list[dict]:
    """Send a batch of filenames to Claude for classification."""
    file_list = "\n".join(filenames)

    message = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=4096,
        system=SYSTEM_PROMPT,
        messages=[{
            "role": "user",
            "content": f"Classify these files:\n{file_list}"
        }]
    )

    raw = message.content[0].text.strip()
    return json.loads(raw)

def move_file(src: Path, dest_dir: Path, dry_run: bool) -> str:
    """Move file to destination, handling duplicates."""
    dest_dir.mkdir(parents=True, exist_ok=True)
    dest = dest_dir / src.name

    # Handle duplicate filenames
    if dest.exists():
        stem, suffix = src.stem, src.suffix
        counter = 1
        while dest.exists():
            dest = dest_dir / f"{stem}_{counter}{suffix}"
            counter += 1

    if dry_run:
        return f"[DRY RUN] {src.name} → {dest_dir.name}/"

    shutil.move(str(src), str(dest))
    return f"✓ {src.name} → {dest_dir.name}/"

def organize(directory: str, dry_run: bool = False):
    target = Path(directory).resolve()
    files = scan_files(target)

    if not files:
        print("No files found to organize.")
        return

    print(f"Found {len(files)} files. Classifying...")

    # Process in batches
    all_mappings = []
    for i in range(0, len(files), BATCH_SIZE):
        batch = files[i:i + BATCH_SIZE]
        print(f"  Batch {i // BATCH_SIZE + 1}: {len(batch)} files")
        mappings = classify_batch(batch)
        all_mappings.extend(mappings)

    # Move files
    categories = {}
    for item in all_mappings:
        src = target / item["file"]
        if not src.exists():
            continue
        cat = item["category"]
        dest_dir = target / cat
        result = move_file(src, dest_dir, dry_run)
        print(f"  {result}")
        categories[cat] = categories.get(cat, 0) + 1

    print(f"\nOrganized into {len(categories)} categories:")
    for cat, count in sorted(categories.items()):
        print(f"  📁 {cat}: {count} files")

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="AI-powered file organizer")
    parser.add_argument("directory", help="Path to organize")
    parser.add_argument("--dry-run", action="store_true",
                        help="Preview changes without moving files")
    args = parser.parse_args()
    organize(args.directory, args.dry_run)

python organize.py ~/Downloads --dry-run

# Output:
# Found 847 files. Classifying...
#   Batch 1: 200 files
#   Batch 2: 200 files
#   Batch 3: 200 files
#   Batch 4: 200 files
#   Batch 5: 47 files
#   [DRY RUN] invoice_2025_03.pdf → invoices/
#   [DRY RUN] IMG_4521.jpg → images/
#   [DRY RUN] main.py → source-code/
#   ...
# Organized into 9 categories:
#   📁 archives: 23 files
#   📁 documents: 156 files
#   📁 images: 312 files
#   📁 source-code: 89 files

TEXT_EXTENSIONS = {".txt", ".md", ".py", ".js", ".ts", ".json", ".csv", ".log"}

def get_file_context(filepath: Path) -> str:
    """Read first 500 bytes of text files for better classification."""
    if filepath.suffix.lower() not in TEXT_EXTENSIONS:
        return ""
    try:
        with open(filepath, "r", errors="ignore") as f:
            preview = f.read(500)
        return f" [preview: {preview[:200]}]"
    except:
        return ""

def classify_batch_with_context(directory: Path, filenames: list[str]) -> list[dict]:
    """Classify files with optional content previews."""
    entries = []
    for name in filenames:
        ctx = get_file_context(directory / name)
        entries.append(f"{name}{ctx}")

    message = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=4096,
        system=SYSTEM_PROMPT,
        messages=[{
            "role": "user",
            "content": "Classify these files:\n" + "\n".join(entries)
        }]
    )
    return json.loads(message.content[0].text.strip())