{"slug": "slothclerk-a-local-ai-agent-for-organizing-cluttered-folders", "title": "SlothClerk: A Local AI Agent for Organizing Cluttered Folders", "summary": "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.", "body_md": "*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)*\n\nEvery developer's desktop and `Downloads` folder eventually turns into a chaotic swamp of forgotten files:\n\n```\n📄 IMG_9421_screenshot_receipt.png\n📄 statement_final_v2(3).pdf\n📄 chaotic_meeting_notes.md\n📄 unorganized_dataset.csv\n📄 untidy_tax_document.pdf\n```\n\nWe 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.\n\nIn 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`).\n\n```\n   .---.     _____ _       _   _     _____ _           _ \n  /     \\   /  ___| |     | | | |   /  __ \\ |         | |\n | () () |  \\ `--.| | ___ | |_| |__ | /  \\/ | ___ _ __| |\n  \\  -  /    `--. \\ |/ _ \\| __| '_ \\| |   | |/ _ \\ '__| |\n   |||||    /\\__/ / | (_) | |_| | | | \\__/\\ |  __/ |  |_|\n   '''''    \\____/|_|\\___/ \\__|_| |_|\\____/_|\\___|_|  (_)\n   The AI file butler that does the chores while you snooze.\n```\n\n`/Documents/Invoices/2026-10-invoice-internet-provider.pdf`) without typing a single character.\nSlothClerk provides both a **cozy, dark earthy Web Dashboard** and a **one-liner rich terminal CLI**:\n\n`#84a98c`), earthy clay (`#d4a373`), deep forest slate (`#141a18`), and cream (`#f4ede2`).\nFor power users who prefer the command line:\n\n```\n# Preview what SlothClerk wants to do without moving a single byte:\npython -m slothclerk tidy --dry-run\nSlothClerk Organization Plan (DRY-RUN)                     \n┌────────────────┬─────────────────┬────────────────┬───────┬─────────────────┐\n│ Original File  │ Clean Filename  │ Category       │ Conf. │ Sloth Summary   │\n├────────────────┼─────────────────┼────────────────┼───────┼─────────────────┤\n│ 2026_internet… │ 2026-10-invoic… │ Documents/Inv… │  78%  │ Slowly dragged  │\n│                │                 │                │       │ this invoice    │\n│                │                 │                │       │ into the folder │\n│                │                 │                │       │ while eyeing a  │\n│                │                 │                │       │ hammock.        │\n│ chaotic_meeti… │ 2026-10-notes-… │ Personal/Notes │  78%  │ Carefully       │\n│                │                 │                │       │ folded these    │\n│                │                 │                │       │ scattered notes.│\n│ untidy_tax_do… │ 2026-10-tax-do… │ Documents/Tax… │  78%  │ Gently slipped  │\n│                │                 │                │       │ this tax doc    │\n│                │                 │                │       │ under leaves.   │\n└────────────────┴─────────────────┴────────────────┴───────┴─────────────────┘\n\n[i] Dry-run mode completed. No files were moved or altered.\nTo apply these changes, run: python -m slothclerk tidy --execute\n```\n\nAnd your personalized morning digest:\n\n```\npython -m slothclerk briefing\n┌────────────────────────── Sloth Morning Briefing ───────────────────────────┐\n│ Morning Report: 6 Chores Finished Before You Woke Up                         │\n│                                                                             │\n│ While you were resting, 6 wandering files were slowly escorted into         │\n│ Documents/Invoices, Documents/Receipts, and Personal/Notes.                 │\n│ Your desktop is tidy, no cloud servers were bothered, and your only         │\n│ remaining obligation is a warm cup of coffee.                               │\n│                                                                             │\n│ Mood: Horizontal and Victorious 🦥 | Date: Thursday, October 22, 2026       │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\nThe full source code is licensed under **MIT** and open-sourced on GitHub:\n\n*\"The AI file butler that does the chores while you snooze.\"*\n\n**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`).\n\nModern 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.\n\n**SlothClerk solves this the sloth way:**\n\n`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.\nSlothClerk is built from the ground up around **open-weight models, local inference, and open-source tooling**:\n\n```\nflowchart TD\n    subgraph Input[\"📥 Cluttered Space\"]\n        Inbox[\"Watched Folder (e.g. ~/Downloads, sample_clutter)\"]\n        MessyFiles[\"Messy PDFs, Receipts, Screenshots, Data, Notes\"]\n        Inbox --> MessyFiles\n    end\n\n    subgraph Core[\"🦥 SlothClerk Core Engine\"]\n        Extractor[\"Extractor Engine (pypdf, Pillow, csv, utf-8)\"]\n        PromptEngine[\"Structured Prompt & JSON Schema Validator\"]\n        Ollama[\"Local Ollama Daemon (llama3.2:3b / mistral / qwen2.5)\"]\n        Fallback[\"Offline Heuristic Engine (zero-network backup)\"]\n        Organizer[\"Safety Organizer & Collision Resolver\"]\n        Ledger[(\"SQLite Undo Ledger (.sloth_ledger.db)\")]\n\n        MessyFiles --> Extractor\n        Extractor --> PromptEngine\n        PromptEngine -->|HTTP :11434| Ollama\n        PromptEngine -.->|If Ollama offline| Fallback\n        Ollama --> Organizer\n        Fallback --> Organizer\n        Organizer <--> Ledger\n    end\n\n    subgraph Output[\"📁 Organized Sanctuary & Dashboards\"]\n        Dest[\"Destinations (/Documents/Invoices, /Media, /Archives, etc.)\"]\n        WebUI[\"Web Dashboard (Nap Mode, Diff Visualizer, Undo)\"]\n        CLI[\"Rich Terminal CLI (Dry-Run / Tidy / Undo / Briefing)\"]\n\n        Organizer --> Dest\n        Organizer --> WebUI\n        Organizer --> CLI\n    end\n```\n\nSlothClerk 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`**.\n\nTo make the AI 100% deterministic, SlothClerk enforces a strict JSON schema via Ollama's `format=\"json\"` API:\n\n```\nclass TidyRecommendation(BaseModel):\n    original_filename: str\n    suggested_filename: str\n    category: str\n    sloth_summary: str\n    confidence_score: float\n    reasoning: str\n```\n\nBefore calling the model, `extractor.py` reads file contents in-memory without altering disk state:\n\n`pypdf`.` Pillow`.\nAI should never touch your filesystem without a safety net:\n\n`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.\nPowered 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.\n\nIf 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.\n\nThe files sitting in your `Downloads` folder are your most sensitive assets: **W-2 tax statements, medical records, bank receipts, payroll stubs, and proprietary code**.\n\nSending 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**.\n\nCommercial 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**.\n\nClosed 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.\n\nThis project was conceived, designed, implemented, and verified using **DevRelay** and the Antigravity pair-programming agent environment.\n\nThe 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.\n\nYou can inspect the entire interactive transcript on DEV:\n\n*(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)).*\n\nLet's do the math on laziness:\n\n`ollama run gemma2:2b`).\n*Built with calm care for Hacktoberfest 2026. May your weekend be slow, your models open-source, and your chores handled while you nap.* 🦥💤", "url": "https://wpnews.pro/news/slothclerk-a-local-ai-agent-for-organizing-cluttered-folders", "canonical_source": "https://dev.to/kishore_p_e1fbd59e95a81f6/slothclerk-a-local-ai-agent-for-organizing-cluttered-folders-482n", "published_at": "2026-10-22 18:28:02+00:00", "updated_at": "2026-10-22 18:41:25.067903+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "large-language-models", "developer-tools"], "entities": ["SlothClerk", "Ollama", "llama3.2:3b", "mistral", "qwen2.5:3b", "Hacktoberfest"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/slothclerk-a-local-ai-agent-for-organizing-cluttered-folders", "markdown": "https://wpnews.pro/news/slothclerk-a-local-ai-agent-for-organizing-cluttered-folders.md", "text": "https://wpnews.pro/news/slothclerk-a-local-ai-agent-for-organizing-cluttered-folders.txt", "jsonld": "https://wpnews.pro/news/slothclerk-a-local-ai-agent-for-organizing-cluttered-folders.jsonld"}}