# Build Sweepy — A Local-First AI Downloads Organizer

> Source: <https://dev.to/ahzem/build-sweepy-a-local-first-ai-downloads-organizer-15ei>
> Published: 2026-10-21 07:35:44+00:00

*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