SlothClerk: A Local AI Agent for Organizing Cluttered Folders

A developer built SlothClerk, an offline background agent that organizes cluttered folders by renaming and sorting files into categorized directories using local open-weight models served through Ollama (llama3.2:3b, mistral, or qwen2.5:3b). The tool offers a dry-run mode that previews proposed renames and categories with confidence scores before any files are moved, plus a web dashboard and a terminal CLI with a morning briefing command. It is described as zero-telemetry and fully local, so no files are sent to cloud servers.

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 Every developer's desktop and Downloads folder eventually turns into a chaotic swamp of forgotten files: 📄 IMG 9421 screenshot receipt.png 📄 statement final v2 3 .pdf 📄 chaotic meeting notes.md 📄 unorganized dataset.csv 📄 untidy tax document.pdf We always tell ourselves: "I'll sit down and clean this up on Sunday." But Sunday comes, and instead of spending 45 minutes manually opening PDFs, squinting at receipts, renaming them, and clicking into nested directories, we'd rather take a nap. In honor of International Sloth Day and this week's "Slow and Steady" theme, I built SlothClerk : a zero-telemetry, 100% offline background agent powered by local open-weight models via Ollama , natively supporting llama3.2:3b , mistral , or qwen2.5:3b . .---. / \ / | | | | | | / \ | | | | | \ --.| | | | | | | / \/ | | | \ - / --. \ |/ \| | ' \| | | |/ \ ' | | ||||| /\ / / | | | | | | | \ /\ | / | | | ''''' \ /| |\ / \ | | | |\ / |\ | | The AI file butler that does the chores while you snooze. /Documents/Invoices/2026-10-invoice-internet-provider.pdf without typing a single character. SlothClerk provides both a cozy, dark earthy Web Dashboard and a one-liner rich terminal CLI : 84a98c , earthy clay d4a373 , deep forest slate 141a18 , and cream f4ede2 . For power users who prefer the command line: Preview what SlothClerk wants to do without moving a single byte: python -m slothclerk tidy --dry-run SlothClerk Organization Plan DRY-RUN ┌────────────────┬─────────────────┬────────────────┬───────┬─────────────────┐ │ Original File │ Clean Filename │ Category │ Conf. │ Sloth Summary │ ├────────────────┼─────────────────┼────────────────┼───────┼─────────────────┤ │ 2026 internet… │ 2026-10-invoic… │ Documents/Inv… │ 78% │ Slowly dragged │ │ │ │ │ │ this invoice │ │ │ │ │ │ into the folder │ │ │ │ │ │ while eyeing a │ │ │ │ │ │ hammock. │ │ chaotic meeti… │ 2026-10-notes-… │ Personal/Notes │ 78% │ Carefully │ │ │ │ │ │ folded these │ │ │ │ │ │ scattered notes.│ │ untidy tax do… │ 2026-10-tax-do… │ Documents/Tax… │ 78% │ Gently slipped │ │ │ │ │ │ this tax doc │ │ │ │ │ │ under leaves. │ └────────────────┴─────────────────┴────────────────┴───────┴─────────────────┘ i Dry-run mode completed. No files were moved or altered. To apply these changes, run: python -m slothclerk tidy --execute And your personalized morning digest: python -m slothclerk briefing ┌────────────────────────── Sloth Morning Briefing ───────────────────────────┐ │ Morning Report: 6 Chores Finished Before You Woke Up │ │ │ │ While you were resting, 6 wandering files were slowly escorted into │ │ Documents/Invoices, Documents/Receipts, and Personal/Notes. │ │ Your desktop is tidy, no cloud servers were bothered, and your only │ │ remaining obligation is a warm cup of coffee. │ │ │ │ Mood: Horizontal and Victorious 🦥 | Date: Thursday, October 22, 2026 │ └─────────────────────────────────────────────────────────────────────────────┘ The full source code is licensed under MIT and open-sourced on GitHub: "The AI file butler that does the chores while you snooze." SlothClerk is a zero-telemetry, 100% offline background file organizer powered by local open-weight models via Ollama , natively supporting llama3.2:3b , mistral:latest , or qwen2.5:3b . Modern digital work leaves desktops and download folders buried in messy names like IMG 9421 screenshot receipt.png , statement final v2 3 .pdf , or unorganized dataset.csv . Manual cleanup is tedious, while sending personal tax forms, invoices, and contracts to cloud AI APIs compromises privacy and racks up subscription costs. SlothClerk solves this the sloth way: 2026-10-invoice-internet-provider.pdf . slothclerk/extractor.py : Multi-format text and metadata extractor PDF, CSV, JSON, Markdown, EXIF . slothclerk/agent.py : Structured JSON prompt engine for local Ollama open-weight models, featuring lazy sloth persona synthesis and offline heuristics. slothclerk/organizer.py : Atomic rename/move engine with automatic collision resolution file 1.pdf and zero deletions. slothclerk/watcher.py : Background folder observer "Nap Mode" with write-debounce powered by watchdog . slothclerk/server.py : FastAPI server with clean lifespan event handling and dynamic model switching. slothclerk/cli.py : Cross-platform CLI with Rich tables, ANSI banners, and instant undo triggers. web/ : Modern single-page dashboard with Tailwind CSS and Lucide icons. tests/ : 14 automated unit and integration tests passing cleanly. SlothClerk is built from the ground up around open-weight models, local inference, and open-source tooling : flowchart TD subgraph Input "📥 Cluttered Space" Inbox "Watched Folder e.g. ~/Downloads, sample clutter " MessyFiles "Messy PDFs, Receipts, Screenshots, Data, Notes" Inbox -- MessyFiles end subgraph Core "🦥 SlothClerk Core Engine" Extractor "Extractor Engine pypdf, Pillow, csv, utf-8 " PromptEngine "Structured Prompt & JSON Schema Validator" Ollama "Local Ollama Daemon llama3.2:3b / mistral / qwen2.5 " Fallback "Offline Heuristic Engine zero-network backup " Organizer "Safety Organizer & Collision Resolver" Ledger "SQLite Undo Ledger .sloth ledger.db " MessyFiles -- Extractor Extractor -- PromptEngine PromptEngine -- |HTTP :11434| Ollama PromptEngine -.- |If Ollama offline| Fallback Ollama -- Organizer Fallback -- Organizer Organizer <-- Ledger end subgraph Output "📁 Organized Sanctuary & Dashboards" Dest "Destinations /Documents/Invoices, /Media, /Archives, etc. " WebUI "Web Dashboard Nap Mode, Diff Visualizer, Undo " CLI "Rich Terminal CLI Dry-Run / Tidy / Undo / Briefing " Organizer -- Dest Organizer -- WebUI Organizer -- CLI end SlothClerk runs natively against a local Ollama daemon http://localhost:11434 . It defaults to llama3.2:3b for lightning-fast execution on modest laptops, while supporting mistral:latest , qwen2.5:3b , and gemma2:2b . To make the AI 100% deterministic, SlothClerk enforces a strict JSON schema via Ollama's format="json" API: class TidyRecommendation BaseModel : original filename: str suggested filename: str category: str sloth summary: str confidence score: float reasoning: str Before calling the model, extractor.py reads file contents in-memory without altering disk state: pypdf . Pillow . AI should never touch your filesystem without a safety net: dest/invoice.pdf exists, SlothClerk auto-increments to invoice 1.pdf . .sloth ledger.db : batch id . Clicking python -m slothclerk undo restores files to their exact previous locations. Powered by Python's watchdog , Nap Mode runs in the background. It monitors the watched directory and uses write-completion debounce so partially downloaded files aren't moved before your browser finishes downloading them. If Ollama is not installed or the user is on an airplane with no GPU, SlothClerk automatically activates its built-in heuristic classifier. The entire UI, extraction pipeline, collision resolver, and undo ledger remain 100% functional. The files sitting in your Downloads folder are your most sensitive assets: W-2 tax statements, medical records, bank receipts, payroll stubs, and proprietary code . Sending those documents to third-party commercial cloud APIs means transmitting unencrypted personal data across external servers, creating privacy risks and telemetry exposure. With open-weight models running on local hardware, zero bytes of personal data ever leave your machine . Commercial AI APIs charge per token. A file butler sorting thousands of documents over months would rack up continuous bills. Running open-source models like llama3.2:3b locally costs $0.00 . Closed APIs can deprecate models, alter system prompts, or raise prices overnight. By building around open-weight models and standard Ollama interfaces, SlothClerk gives you full ownership: swap to a new model whenever you want, fine-tune your own weights, or run completely air-gapped forever. This project was conceived, designed, implemented, and verified using DevRelay and the Antigravity pair-programming agent environment. The full transcript—from scaffolding the FastAPI backend and designing the SQLite undo ledger to solving Windows console encoding quirks and writing 14 unit tests—was recorded during the build. You can inspect the entire interactive transcript on DEV: If the interactive embed is loading, you can also view the direct session log at dev.to/agent sessions/slothclerk... https://dev.to/agent sessions/slothclerk-building-a-zero-telemetry-local-ai-file-butler-with-ollama-cffpk1 or inspect the workflow logs on GitHub https://github.com/kishorekrrish3/SlothClerk . Let's do the math on laziness: ollama run gemma2:2b . Built with calm care for Hacktoberfest 2026. May your weekend be slow, your models open-source, and your chores handled while you nap. 🦥💤