SlothClerk: A Local AI Agent for Organizing Cluttered Folders

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

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:

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 down 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 , you can also view the direct session log at dev.to/agent_sessions/slothclerk... or inspect the workflow logs on GitHub).

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. 🦥💤