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

What I Built

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. 

Who gets to be lazier?

• Developers & Tech Workers: No more hunting for scripts, meeting notes, or raw datasets scattered across your home directory.
• Freelancers & Solopreneurs: Invoices and expense receipts get sorted into clean, dated folders (/Documents/Invoices/2026-10-invoice-internet-provider.pdf) without typing a single character.
• Anyone Who Loves Peace of Mind: You never have to manually organize a file again. You drop files in, go take a nap, and wake up to a pristine digital sanctuary and a witty Sloth Morning Briefing.

Demo

SlothClerk provides both a cozy, dark earthy Web Dashboard and a one-liner rich terminal CLI:

1. The Cozy Web Dashboard

• Warm Sloth Palette: Sage greens (#84a98c), earthy clay (#d4a373), deep forest slate (#141a18), and cream (#f4ede2).
• Dry-Run Review Deck: Inspect proposed rename/move diffs, confidence scores, and hilarious sloth rationales before approving.
• Before vs. After Visualizer: See loose chaotic files transformed into tidy semantic trees.
• Nap Mode Toggle: Turn on live folder monitoring with a gentle pulsating indicator.
• "Tidy Everything & Let Me Sleep" Button: One-click execution.

2. The Terminal CLI & Sloth Morning Briefing

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 │ └─────────────────────────────────────────────────────────────────────────────┘ 

Code

The full source code is licensed under MIT and open-sourced on GitHub:

Repository Architecture:

• 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.

How I Built It

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

1. Local Inference Core (Ollama + Open-Weight Models)

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 

2. Multi-Format Text & Metadata Inspection

Before calling the model, extractor.py reads file contents in-memory without altering disk state:

• PDFs: Extracts metadata (author, title) and text chunks using pypdf.
• Images: Inspects dimensions and camera/timestamp EXIF tags using Pillow.
• CSVs & JSON: Samples headers and data rows to discern analytics exports from configs.
• Code & Markdown: Reads docstrings, headers, and comments across multiple encodings.

3. Absolute Safety: Dry-Runs & SQLite Undo Ledger

AI should never touch your filesystem without a safety net:

• Dry-run by default: Every move is previewed with a confidence score and reasoning before execution.
• Collision Resolution: If dest/invoice.pdf exists, SlothClerk auto-increments to invoice_1.pdf.
• Zero Deletions: Files are only ever moved into organized category paths.
• SQLite Undo Ledger (.sloth_ledger.db): Every action is logged with an atomic batch_id. Clicking "Undo Last" or running python -m slothclerk undo restores files to their exact previous locations.

4. Background "Nap Mode"

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.

5. Resilient Offline Sloth Heuristics

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.

Why Does Open Innovation Matter?

1. Privacy for Confidential Documents

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.

2. $0 Monthly API Costs

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.

3. Model Agnosticism & Independence

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.

My Agent Session

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:

SlothClerk: Building a Zero-Telemetry Local AI File Butler with Ollama

You

You are an expert full-stack engineer and AI systems architect. I need you to generate a complete, production-ready, open-source project from scratch for the "Hacktoberfest Open-Source AI Challenge: Week 3 (Slow and Steady)".

🦥 Project Concept: SlothClerk

"The AI file butler that does the chores while you snooze."
SlothClerk is a zero-telemetry, 100% offline background agent powered by local open-weight models (via Ollama, supporting Llama 3.2, Mistral, or Qwen 2.5). It watches a target folder (like Downloads or a lazy drop-box), inspects messy files, reads documents/text/PDFs/images, infers meaningful semantic categories, renames files cleanly (e.g., 2026-10-invoice-internet-provider.pdf), safely moves them into organized destination folders, and generates an entertaining, ultra-concise "Sloth Morning Briefing" dashboard so users never have to manually clean their files again.

Core Requirements & Constraints

1. Strictly Open-Source AI Core:

   • Must run locally with zero paid API keys or cloud dependencies.
   • Integrates with local inference via Ollama (defaulting to llama3.2:3b for lightweight local inference, fallback to mistral or qwen2.5:3b).
   • Uses an open-source agent workflow pattern with structured JSON schema outputs for deterministic tool execution.

2. Safety & Laziness First:

   • Dry-run mode by default with a single-click "Approve & Execute" or "Auto-pilot" toggle.
   • Undo Ledger: Every move, rename, and categorization must be logged to an SQLite / JSON ledger (.sloth_history.json) with instant rollback capabilities.
   • Never deletes files—only organizes into configured categories (/Documents/Invoices, /Work/Projects, /Media/Wallpapers, /Archives, etc.).

3. Tech Stack:

   • Backend: Python 3.11+ using FastAPI + watchdog (for optional live folder monitoring) + pydantic + pypdf / pillow (for content extraction) + httpx (to query local Ollama /api/chat).
   • Frontend: Mod <truncated 1895 bytes> `: Returns the lazy sloth morning digest.

4. web/ Frontend Dashboard:

   • An aesthetically pleasing UI with dark/earthy warm sloth tones (sage green, soft brown, cream).
   • Card deck showing pending files, AI reasonings, and dry-run diffs.
   • One-click "Tidy Everything & Let Me Sleep" button.

5. pyproject.toml or requirements.txt & Setup Scripts:

   • Standard dependencies: fastapi, uvicorn, watchdog, httpx, pydantic, pypdf, python-multipart.
   • run.sh / run.bat scripts to verify Ollama status and boot the server in one command.

6. README.md:

   • Complete project overview, architecture diagram in ASCII/Mermaid, quickstart guide, supported models, and offline privacy breakdown.

7. DEV_POST.md (Hacktoberfest Week 3 Submission Template):

   • Provide a complete, fully formatted Markdown blog post ready to publish on DEV.to.
   • Title: SlothClerk: The Local Open-Weight Agent That Tidies Your Clutter While You Nap (Hacktoberfest 2026).
   • Include all prompt sections required by the challenge:
     • The Idea & The "Slow and Steady" Sloth Theme.
     • Why Open Innovation Matters: (Local-only zero-telemetry, keeps personal tax/medical docs off cloud LLM servers, $0 monthly API bill, model-agnostic).
     • How It Works & Open-Source AI Stack: Details on local Ollama, prompt engineering with structured output, and safety rollback mechanics.
     • Demo & Screenshots/Logs placeholder.
     • DevRelay session embed placeholder / GitHub Repo link.

Proceed to scaffold and write all files with clean, production-grade code.

Show more

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ }

Output

{ }

Agent

▸ tool {}

Input

{ Source：https://dev.to/kishore_p_e1fbd59e95a81f6/slothclerk-a-local-ai-agent-for-organizing-cluttered-folders-482n
My favorites

PreviousThe Agent Shrunk the Failing Case Until the Bug DisappearedNextYour mobile screenshots are probably lying about your layout

Related posts

What a forward deployed AI engineer actually does

Not a solutions engineer, not a researcher. A working definition of the forward deployed AI engineer role, drawn from do

0dev.to

How to Get Your First Freelance Client When You Have No Experience

A digital marketing learner from Kerala on the practical steps between “I have skills” and “someone is paying me.” Every

0dev.to

Best shadcn registries for ready-made blocks in 2026

Checked against official sites on November 2, 2026. You need a pricing section, a hero and a footer. The useful question

0dev.to

How we score an election forecast (and what the score does not measure)

How we score an election forecast (and what the score does not measure) TL;DR: We score the reasoning before the outcome

0dev.to

Handling Failures as Values in Agent-Generated Code

I am Jake Burwick, a high school student, and I built Vow, an open source programming language under the MIT license des

0dev.to

My Favourite Laptop

Article URL: https://blog.jsbarretto.com/post/laptop Comments URL: https://news.ycombinator.com/item?id=50339815 Points:

0Hacker News