Build Sweepy — A Local-First AI Downloads Organizer

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

#

What I Built

Sweepy is a local-first, privacy-respecting desktop file organizer that brings order to your most chaotic directories (like Downloads and Desktop) without manual sorting.

Instead of dragging files one-by-one into subfolders or inventing filenames, Sweepy scans your messy directory, passes lightweight metadata to a locally running open-weight AI model (Gemma 3 1B via Ollama), and proposes clean, structured folder paths (e.g. Documents/Invoices/, Images/2026-10/, Code/).

Who gets to be a little lazier because of it?

Developers, students, and power users who download dozens of invoices, PDFs, zip archives, scripts, and screenshots every day and dread the thought of spending their Sunday afternoon manually sorting files.

• Anyone who wants the convenience of automated organization without up sensitive financial receipts, resumes, or private photos to cloud AI APIs.

Core Philosophy: AI recommends; deterministic application code executes; the user stays in control.

#

Demo

Check out the full walkthrough video demonstrating folder scanning, local Gemma 3 inference, inline path editing, safe execution, and 1-click Undo:

Direct Video Link: https://youtu.be/A21HS3Ggo1Y

#

Code

Sweepy is a desktop-first file organization tool that helps you organize messy folders (such as Downloads) without manual sorting.

Sweepy scans a folder, passes file metadata to a local AI model (Gemma 3 1B running via Ollama), and proposes clean destination folders and filenames. You review, edit, and approve suggestions before anything is moved.

Core Principle: AI recommends; deterministic application code executes; the user stays in control.

Key Features #

Dashboard : Track scanned files, pending reviews, generated suggestions, and completed operations. Live connection indicators for backend and Ollama. #

Secure Folder Scanning : Fast directory enumeration with Windows native folder picker dialog and quick-folder shortcuts. Automatically ignores hidden files and system/application folders (.git ,node_modules ,.venv ). Never reads file contents. #

Local AI Inference : Powered by Ollama running Google'sgemma3:1b model. Categorizes files into structured folders (Documents/Invoices/ …

GitHub Repository: https://github.com/Ahzem/sweepy.git The codebase is organized as a clean monorepo:

apps/web : Next.js 16 (App Router), React 19, TypeScript, and Tailwind CSS. #

apps/api : Python 3.11+ FastAPI backend with Pydantic v2 schemas and atomic JSON operation logging. #

docs/architecture.md : Full system design, threat model, and Windows filesystem safety documentation. #

scripts/dev.ps1 : 1-click PowerShell launcher for Windows 11.

#

How I Built It

Sweepy is built specifically around local, open-weight AI inference:

**Local Model Ingestion (Ollama & Gemma 3 1B)** :
   - We utilize Google's open-weight **Gemma 3 1B** (`gemma3:1b` ) running through Ollama at`http://127.0.0.1:11434` .

• By structuring requests with Ollama's native JSON mode (format: "json" ), Gemma 3 reliably returns validated JSON schemas containing proposed filenames, subfolder destinations, category classifications, and reasoning summaries.
• Files are batched in micro-chunks (15 items per batch) to ensure lightning-fast generation without context bottlenecking.

Deterministic Safety Architecture :

• The AI only suggests paths; it never executes shell commands or touches the filesystem directly.

• All filesystem operations are handled by a dedicated Python backend with defense-in-depth safety: #

**Strict Path Confinement** : Enforces`target.resolve().relative_to(root.resolve())` to prevent directory traversal sequences (`../` ) or symlink escapes.
    - 

Collision Prevention : If a destination file already exists, Sweepy automatically appends a safe counter suffix (e.g.invoice (1).pdf ) rather than overwriting. - Zero Deletions : The codebase contains zero file deletion calls—files are only moved or renamed. - Rule-Based Fallback : If Ollama is offline or busy, Sweepy automatically switches to deterministic keyword and extension rules so organization never fails. 3. Atomic 1-Click Undo :

• Completed moves are logged in an atomic local ledger (~/.sweepy/operations_log.json ).
• If you ever change your mind, clicking Undo Move checks destination validity and reverses the move back to the exact original location.

#

Why Does Open Innovation Matter?

Open innovation—specifically open-weight foundation models and local inference—is what makes an application like Sweepy viable:

Absolute Data Sovereignty : Nobody wants their bank statements, contracts, or tax documents sent over the wire to a closed, third-party LLM cloud. By using open-weight Gemma 3 running locally on127.0.0.1 , user data never leaves the computer. 2. Zero Recurring Costs & Zero Rate Limits : Closed APIs charge per token, require credit cards, and throttle users. Open-weight models run infinitely on consumer hardware for free. 3. True Offline Utility : Sweepy works on an airplane or without an internet connection. 4. Accessible Performance : A 1-billion parameter model like Gemma 3 1B runs smoothly on everyday laptops while possessing more than enough reasoning power to categorize documents and identify timestamps.

#

My Agent Session

Sweepy was built and pair-programmed end-to-end using Google Antigravity IDE.

The agent collaborated on:

• Architecting the pnpm monorepo layout separating Next.js and FastAPI.
• Writing the path traversal security checks and Windows reserved device name safeguards (CON ,PRN ,AUX ,NUL ).
• Developing an automated 21-test pytest suite with a full end-to-end lifecycle test verifying simulated download file moves and byte-level Undo integrity.
• Designing the desktop-first UI with inline destination editing and interactive review tables.

#

The Lazy Payoff

The "Before" Experience

Opening Downloads, finding 140 miscellaneous files from the past month, scrolling endlessly to locate that one ticket or receipt, and spending 25 minutes manually creating folders like Invoices, Photos, and Zips.

The "After" Experience with Sweepy

1. Launch Sweepy and click Downloads .
2. Click Scan Folder (takes 200 milliseconds).
3. Gemma 3 1B groups everything into neat categories (Documents/Invoices/ ,Images/2026-10/ ,Installers/ ,Development/ ).
4. Click Review & Apply (takes 2 seconds).

Time saved: Over 20 minutes per cleanup session. It turns one of computing's most tedious chores into a single click, letting you be as lazy as possible while keeping your machine spotless.

#

Prize Categories

Primary Track: Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady #

Category: Open-Weight Models & Local AI Utility

source & further reading

dev.to — original article Strip the tool arguments your LLM made up, before the tool runs Experiments in Software Factories #1: Production app in 40 minutes Three ways my startup file went stale, and a check that may say "I could not measure"