DEV Community

Aishik Yadav
Aishik Yadav

Posted on

dumper: A Local AI File Organizer That Rewards Your Laziness

#devchallenge #hf26challenge #opensource #ai

Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady Submission 🦥

This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 3 — Slow and Steady.

The Lazy Inspiration: The "Downloads" Graveyard

We all have that one folder. The Downloads folder, the desktop cluttered with Screenshot 2026-10-21.png, assignment_final_v2_really_final.pdf, receipt_182749.pdf, or notes_october.txt.

Every few weeks, we promise ourselves: "Today I'm going to sort this out."
Then we look at 300 unnamed files, realize sorting them by hand will take an hour, and close the folder.

In honor of International Sloth Day and this week’s "Slow and Steady" Hacktoberfest theme, I decided to channel my inner sloth: build something that does the tedious work so I don't have to.

Meet dumper — a background daemon and CLI that watches a drop folder, reads your files locally with an open-source LLM, deduces what each file actually is, renames it into human-readable kebab-case, and files it into tidy category folders.

Zero manual tagging. Zero manual renaming. Just drop and forget.

What I Built

dumper is an autonomous, local-first file organizer built with TypeScript, Node.js, and Ollama.

Instead of writing brittle regex rules or mapping extensions to hardcoded folders (which groups an invoice and an ebook into the same folder just because both are .pdf), dumper actually inspects what is inside the file:

  1. Text & Code (.txt, .md, .ts, .py, .json, etc.): Streams the first 2,500 characters.
  2. PDF Documents (.pdf): Extracts textual content from pages via pdf-parse.
  3. Images & Media (.png, .jpg, .mp4): Extracts metadata, dimensions, and filename semantics.

Then, it queries a locally hosted open-source model (such as gemma2:2b or llama3.2) running on your own machine. The model classifies the content into custom categories (like finance/invoices, college/assignments, development/scripts, notes) and invents a clean, descriptive slug.

Example in Action:

Original Dropped File Local AI Understanding Renamed & Moved Destination
Scan_0042.pdf "Utility electricity bill for Sept 2026" Organized/Finance/bills/september-2026-electric-bill.pdf
Screenshot 2026-10-21.png "Figma mockup of login screen" Organized/Design/mockups/dark-mode-login-mockup.png
hw3_final.py "Graph BFS traversal algorithm assignment" Organized/College/algorithms/graph-bfs-traversal-hw3.py
receipt_78291.pdf "Cloud server invoice from AWS" Organized/Finance/invoices/aws-cloud-invoice-oct26.pdf

Architecture & How It Works

Here is the pipeline that runs every time a file is dropped into your dump folder:

[ File Dropped into ~/Dump ]
             │
             ▼
    ┌─────────────────┐
    │   watcher.ts    │  ◄── Chokidar detects write & waits for completion (1.5s debounce)
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │  extractor.ts   │  ◄── Reads head content, parses PDF text, or inspects media
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │   analyzer.ts   │  ◄── Injects user categories into prompt -> calls Ollama JSON API
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │  organizer.ts   │  ◄── Resolves cross-disk moves, slugifies names & handles duplicates
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │ ui.ts / logger  │  ◄── Renders visual terminal card & records history to ~/.dumper/history.json
    └─────────────────┘
Enter fullscreen mode Exit fullscreen mode

The AI Prompting Mechanism

In src/analyzer.ts, dumper sends a structured request to Ollama with format: "json". It passes the user's configured category definitions directly in the prompt:

{
  "category": "finance",
  "subcategory": "invoices",
  "newFilename": "aws-cloud-hosting-invoice",
  "confidence": "high",
  "reasoning": "Document contains itemized cloud infrastructure charges from Amazon Web Services."
}
Enter fullscreen mode Exit fullscreen mode

If the model is uncertain or the file type is unsupported, dumper gracefully isolates it in an uncategorized/ bucket without interrupting the file watch loop.

Why Open-Source AI Matters Here

File organization is inherently personal and sensitive. Your dump folder contains:

  • Bank statements and tax forms
  • Medical records and prescriptions
  • Proprietary source code and API keys
  • Personal photos and journal notes

Sending every dropped file to a closed cloud API like OpenAI or Claude creates three huge problems:

  1. Privacy & Security: Cloud providers log API calls and prompts. Feeding them personal invoices or private code is an unnecessary security risk.
  2. Cost: Running a cloud LLM on every single file you download or screenshot quickly turns into a recurring bill.
  3. Reliability & Offline Capability: If you're on a plane or have no internet connection, your file organizer shouldn't stop working.

With open models through Ollama (like Google's Gemma 2 or Meta's Llama 3.2), 100% of the inference happens locally in RAM and GPU. Not a single byte of your files ever leaves your computer.

The Lazy Payoff

How much effort does dumper actually save?

  • Manual sorting: Finding a downloaded file, opening it to remember what it was, creating a subfolder, renaming it, and moving it takes ~20 to 45 seconds per file.
  • With dumper: 0 seconds. You download or save files to your ~/Dump directory as usual, and dumper silently organizes them in the background while you grab a coffee or relax.

Over a semester or a few months of development work, that translates to hours of tedious folder maintenance eliminated entirely.

Quickstart: Try It Yourself

1. Prerequisites

Ensure Ollama is installed and running with your choice of model:

# Recommended lightweight model (ideal for Best Use of Gemma):
ollama pull gemma2:2b

# Or Llama 3.2:
ollama pull llama3.2
Enter fullscreen mode Exit fullscreen mode

2. Install & Run 

git clone https://github.com/sleepyaishik69/dumper.git
cd dumper
npm install
npm run build

# Run interactive setup wizard
node dist/index.js init

# Start in dry-run mode to see what it would do without moving files:
node dist/index.js start --dry-run

# Or run the live daemon:
node dist/index.js start
Enter fullscreen mode Exit fullscreen mode

3. Check Stats & History 

# View recent file moves
node dist/index.js history

# View classification analytics
node dist/index.js stats
Enter fullscreen mode Exit fullscreen mode

Prize Category

This project is entered into:

  • Best Use of Gemma ($200 featured category): dumper is built from the ground up to pair with gemma2:2b, giving ultra-fast (~300ms) local JSON classification on modest laptop hardware without heating up your machine.

Related Community Reading

Top comments (0)