Build Sweepy — A Local-First AI Downloads Organizer

A developer built Sweepy, a local-first desktop file organizer that uses Google's open-weight Gemma 3 1B model running via Ollama to propose structured folder paths for messy directories like Downloads and Desktop. The tool passes only file metadata to the local model, which returns validated JSON suggestions in batches of 15, while a separate Python FastAPI backend performs all filesystem moves with safety checks and one-click undo. The project is open source on GitHub as a Next.js and FastAPI monorepo.

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady https://dev.to/challenges/hacktoberfest-week3-2026-10-19 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 uploading 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 https://youtu.be/A21HS3Ggo1Y Code Sweepy — Local-First AI Downloads Organizer 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's gemma3:1b model. Categorizes files into structured folders Documents/Invoices/ … GitHub Repository: https://github.com/Ahzem/sweepy.git 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 : 1. 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. 2. 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: 1. 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 on 127.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