SlothFlow AI：少花工夫、整理更聰明、在本機運作

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

What I Built

My Downloads folder has a simple filing system: everything goes in, and eventually I stop looking.

I built SlothFlow AI to make that pile easier to deal with.

It's a privacy-first file organization assistant designed around local open-weight AI. It scans folders you explicitly approve, proposes categories and descriptive filenames, and lets you review changes before applying them.

SlothFlow includes:

• Organization suggestions: categories, proposed filenames, explanations, and confidence scores.
• Exact duplicate detection: SHA-256 comparisons, with reversible quarantine instead of automatic deletion.
• Lazy Mode: opt-in monitoring, scheduled active hours, and automation constrained by approved rules.
• Undo: a SQLite operation journal records where files came from and where they went.
• Daily digests: summaries of recorded activity, duplicate groups, and items awaiting review.
• A synthetic playground: try the workflow without handing over personal files.

It's for anyone who keeps postponing the small chore of sorting, naming, and checking files.

The sloth-inspired principle is simple: let software do the repetitive thinking, while keeping the person in control of filesystem changes.

Demo

Watch the recorded SlothFlow AI demo (MP4)

This is a captioned recording of the running local application using synthetic files. It shows rule-based fallback because Ollama was not installed on the recording machine; it does not demonstrate live model inference.

SlothFlow runs locally rather than as a public hosted file manager. Setup instructions are in the repository.

The included demo creates five synthetic files, including an exact duplicate pair. You can:

1. Create and scan the demo folder.
2. Review the proposed categories and names.
3. Approve a file organization operation.
4. Inspect duplicate groups.
5. Undo an operation.
6. Generate a daily digest.

The scan → review → organize → undo workflow has been exercised through the running dashboard.

Here's the welcome screen from the application:

Code

The source code, installation guide, tests, architecture notes, and privacy documentation are available on GitHub:

SlothFlow AI

Work less. Organize smarter. Stay local.

A privacy-first file organization assistant built around local open-weight AI for the DEV.to Hacktoberfest Open-Source AI Challenge, “Slow and Steady.” React + FastAPI + SQLite + Ollama. No API keys or cloud inference.

What works

• Local folder registration, bounded recursive scans, optional bounded document extraction.
• Ollama classification, explanations, confidence and descriptive filename suggestions. Clearly marked deterministic fallback when AI is unavailable.
• Review and batch approval, collision-safe organization, SHA-256 exact duplicate groups, quarantine and durable undo.
• Explicit opt-in folder monitoring, debounce and stability checks, pause/resume through Lazy Mode, hourly active windows and approved extension rules.
• Locally stored daily digests from journal data, actual storage totals and labeled time estimates.
• Nine responsive views, light/dark themes, original SVG sloth, synthetic resettable demo.
• Installable PWA with app-shell caching. No file contents or API responses cached by the service worker.

Recorded demo

Watch the local app walkthrough…

The application code and original sloth artwork use the MIT license. Model weights have their own licenses and are not bundled with the repository.

How I Built It

The frontend uses React, TypeScript, Vite, Tailwind CSS, and Lucide React. The backend uses FastAPI, Pydantic, SQLite, watchdog, and Ollama, with document extraction through PyMuPDF, python-docx, and Pillow.

The default model configuration is qwen3:4b, distributed through Ollama. The upstream Qwen3-4B model is released under Apache 2.0.

AI provides the category, descriptive filename, explanation, and confidence for each suggestion. Those decisions are validated with Pydantic and checked against the configured categories before entering the review workflow.

Text extraction is disabled by default. When enabled, extraction limits constrain how much content is read.

The processing flow is:

Approved folder → bounded scan → local inference → validated suggestion → review → journaled move

Automatic organization requires additional opt-ins: monitoring must be enabled, automatic renaming must be enabled, an extension rule must match, and the AI decision must meet the configured confidence threshold. Model confidence is self-reported, so it is a guardrail rather than a guarantee.

If inference is unavailable or returns invalid output, SlothFlow provides a clearly labeled deterministic fallback. It never presents extension-based rules as AI decisions.

Safety shaped the implementation:

• Proposed filenames are sanitized.
• Moves avoid overwriting existing files.
• Changed files trigger conflicts rather than silently proceeding.
• Undo checks destination contents and the original location.
• The backend rejects unauthorized paths, symlinks, and junctions.
• Ollama remote/cloud-backed models are refused before file information is submitted.

A useful lesson came from CI: one test assumed filesystem enumeration order. Linux exposed that assumption. The corrected test identifies files by path and exercises both forward and reversed scan order.

The latest local backend run reports 23 passed and 1 skipped, and the frontend production build passes. The skipped test requires Windows symlink privileges. Live Ollama generation remains unverified on the development machine; valid responses, failures, malformed output, and remote-model rejection are covered with mocked responses.

Why Does Open Innovation Matter?

File organization can involve invoices, personal notes, work documents, and other material that people may prefer to keep on their own devices.

Open-weight models make local inference a practical architectural choice. After installing dependencies and downloading model weights, SlothFlow is designed to operate offline without API keys or cloud inference.

That gives users control over:

• Where processing happens: file information can stay on their machine.
• Which model they use: the model is configurable rather than tied to one hosted service.
• When the tool works: runtime does not depend on an internet connection.
• How inference is paid for: there are no per-request inference charges.

Local inference still has costs: hardware, memory, storage, electricity, and setup time. It also needs careful engineering; running locally does not automatically make an application secure.

For SlothFlow, the value of openness is ownership. Users can inspect the code, change the rules, choose compatible local models, and understand how their files are handled.

There's more hardening ahead, including parser isolation, background scan jobs, and file-backup restoration. But the direction stays the same:

Less repetitive sorting. More control. One steady step toward a calmer folder.