organiseme

Look, I'm an ADHD founder who downloads way too many design references, research papers, invoices, and PDFs. My day-to-day is basically a constant stream of files, and honestly? I'm terrible at scanning, cleaning, and organizing this mess. So I built this thing to solve my own problem - it uses AI to automatically sort your files into a sensible folder structure so you don't have to think about it. If you're like me and your Downloads folder is a disaster zone, maybe this'll help you too.

What it does

You point it at a folder (like your Downloads or a messy inbox), and it:

1. Scans all the files in that folder
2. Uses Google's Gemini Flash Lite (latest) model to figure out what each file is (client work, invoices, design assets, screenshots, etc.)
3. Automatically moves them into organized folders based on what they are

The best part? Gemini Flash Lite is completely free to use from Google AI Studio - you can make single requests without any cost, which makes this tool perfect for organizing your files without worrying about API bills.

It's smart enough to understand context - if files are in the same subfolder, it knows they're probably related and should go together. It also preserves your folder structure when moving things around.

How it works

Here's the flow of what happens when you run organiseme:

flowchart TD
    Start[User runs organiseme] --> Scan[Scan folder for files<br/>up to 100 files]
    Scan --> Collect[Collect file metadata<br/>name, path, size, folder structure]
    Collect --> AI[Send to Google Gemini Flash Lite<br/>with folder context]
    AI --> Classify[AI classifies each file<br/>into category]
    Classify --> Move[Move files to organized<br/>folder structure]
    Move --> Done[Files organized!]
    
    style Start fill:#3b82f6,stroke:#1e40af,stroke-width:3px,color:#fff
    style Scan fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    style Collect fill:#06b6d4,stroke:#0891b2,stroke-width:2px,color:#fff
    style AI fill:#f59e0b,stroke:#d97706,stroke-width:3px,color:#fff
    style Classify fill:#a855f7,stroke:#9333ea,stroke-width:2px,color:#fff
    style Move fill:#10b981,stroke:#059669,stroke-width:2px,color:#fff
    style Done fill:#10b981,stroke:#059669,stroke-width:3px,color:#fff

Loading

The AI considers:

• File names and extensions
• Folder structure (files in same folder are related)
• File context to make smart decisions
• Preserves your subfolder organization when moving

Quick start

First, run the setup script to create your folder structure and configure your API key:

bash setup.sh

This will:

• Ask you where you want your organized files to live (defaults to ~/thisux)
• Create all the necessary folders for different file types
• Help you set up your Google Generative AI API key

Then install the dependencies:

bun install

How to use it

Once everything is set up, you can run it like this:

bun run index.ts

By default, it'll organize your Downloads folder. Or you can point it at a specific folder:

bun run index.ts /path/to/your/messy/folder

It will scan up to 100 files at a time, ask the AI to classify them, and then move them into the right places. You'll see output like:

[client_work] project-a/docs/file.txt & 1-work/clients/project-a/docs/file.txt
[finance_invoice] invoice-2024.pdf & 3-finance/2024/invoices/invoice-2024.pdf

What folders it creates

The tool organizes files into these categories:

• Client work → 1-work/clients/
• Product work (your own projects) → 1-work/products/
• Studio operations → 1-work/studio/
• Design assets (logos, UI refs, etc.) → 2-assets/refs/
• Screenshots → 0-inbox/screenshots/
• Invoices → 3-finance/YYYY/invoices/
• Expenses → 3-finance/YYYY/expenses/
• Archive → 9-archive/
• Trash → 9-archive/trash-review/ (review before deleting)

The setup script creates all these folders for you automatically.

Getting an API key

You'll need a Google Generative AI API key. The good news? It's completely free! We're using Gemini Flash Lite (latest), which you can use freely from Google AI Studio - no credit card required, just sign in with your Google account and grab an API key. The setup script will help you add it to a .env file, or you can set it manually:

export GOOGLE_GENERATIVE_AI_API_KEY=your-key-here

Customizing the base directory

If you want to use a different base directory than ~/thisux, you can set the THISUX_BASE environment variable:

export THISUX_BASE=/path/to/your/base

The setup script will ask you about this when you run it.

Notes

• It processes up to 100 files at a time to keep things manageable
• Files are moved, not copied, so make sure you have backups if you're nervous
• The AI is pretty good at understanding context, but it's not perfect - you might want to review the trash folder before deleting anything