SlothDesk — Local-First AI Downloads Organizer: Less sorting. More living.

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

🦥 What I Built

SlothDesk is a local-first, desktop-style dashboard that rewards laziness by safely organizing your cluttered Downloads folder with minimal user effort.

Tagline: Less sorting. More living.

Downloads folders are notorious black holes where productivity goes to die. Files of every kind—invoices, design assets, archives, code scripts, and firmware—pile up in an unmanageable mess.

Existing tools typically fall into two extremes:

1. Dumb regex scripts that break on edge cases and force rigid naming conventions.
2. Cloud AI utilities that upload your private documents and filenames to third-party APIs, charging recurring subscription fees.

SlothDesk charts a different path: Slow and Steady. It runs completely offline using Hugging Face smolagents and LM Studio (Qwen2.5-7B-Instruct), treating the language model as an untrusted reasoning engine rather than a reckless file manipulator.

Downloads/
├── Documents/
├── Images/
├── Videos/
├── Audio/
├── Archives/
├── Code/
└── Other/

🔒 The "Slow and Steady" Philosophy: Safety First

Many AI file organizers give the model direct write tools or shell access (CodeAgent, shutil.rmtree, os.rename). If the model hallucinates or encounters ambiguous context, files can be permanently destroyed.

In SlothDesk, filesystem mutation is architecturally separated from AI reasoning:

1. Zero Model Execution Privileges: The model has no write tools, cannot run shell commands, and does not execute dynamic Python scripts. It is given only 3 read-only metadata inspection tools:
   • get_file_metadata(filename)
   • get_allowed_categories()
   • validate_category(category)
2. Strict Scope Confinement: Operations are locked strictly inside the configured SLOTHDESK_ROOT. Any path containing .., absolute drive letters, or symbolic links is immediately rejected.
3. Deterministic Collision Protection: If a destination file already exists or another file in the plan shares the name, SlothDesk safely resolves it to {name}_{counter}{ext} (e.g. invoice_october_1.pdf). Existing files are never overwritten.
4. Cryptographic State Check: At scan time, SlothDesk computes the SHA-256 hash and byte size of every file. At execution time, it re-verifies these hashes. If a file was modified or deleted while waiting for approval, the move is skipped to eliminate race conditions.
5. Reversible Manifests: Every approved move generates an immutable JSON audit manifest, enabling one-click rollbacks at any time.

📸 Application Showcase & Screenshots

1. Dashboard Overview

Inspect loose files in the Downloads folder, track storage volume, and verify the local inference engine status at a glance.

2. Read-Only AI Organization Proposal

Clicking Scan & Propose Plan triggers smolagents via LM Studio. Every file receives a color-coded category badge, destination path preview, model rationale, and automatic collision resolution.

3. Explicit Approval Gate

Zero files are altered until the user explicitly reviews the plan summary and safety checklist, confirming the moves in a dedicated modal dialog.

4. Downloads Inventory & Cryptographic Hashes

Inspect all top-level files with real-time size metrics, extension detection, and SHA-256 verification hashes.

5. Execution History & One-Click Undo

Every move produces an immutable JSON audit manifest. Click Undo Operation to instantly restore files back to their exact original root locations.

🛠️ Tools & Technologies Used

• Python 3.11 & FastAPI: High-performance backend engine with Pydantic validation.
• Hugging Face smolagents (ToolCallingAgent): Narrowly scoped, typed tool calling.
• LM Studio: OpenAI-compatible local inference API running Qwen2.5-7B-Instruct (GGUF Q4_K_M) on consumer hardware (NVIDIA RTX 5050 Laptop GPU / 8 GB VRAM).
• React 19 & TypeScript: Responsive dashboard interface with nature-inspired forest green aesthetics (#0a130e) and soft lime accents (#84cc16).
• Vite 6: Client build tooling and reverse-proxy.
• lucide-react: Lightweight icon set.
• Podman: Rootless, containerized deployment workflow (infra/compose.yaml).
• pytest: 28 automated unit, API, agent, and security tests.

🧠 Transparent Offline Fallback

A key requirement of SlothDesk is honesty:

• When LM Studio is running, the dashboard displays Local AI: qwen2.5-7b-instruct with active tool reasoning.
• When LM Studio is offline, SlothDesk automatically engages its deterministic rule fallback engine.
• SlothDesk never falsely claims the AI model was used when the fallback was active.

This application was designed, implemented, and hardened pair-programming with Google Antigravity.

In accordance with DEV community guidelines, ai_disclosure_level: some_ai is declared for this submission.

Agent Workflow & Engineering Trajectory

• Architecture & Threat Modeling: Designed the two-phase execution lifecycle strictly separating untrusted LLM reasoning from filesystem mutations.
• Safety & Boundary Confinement: Built path canonicalization, symlink rejection, and deterministic collision policies (_1.ext) guaranteeing zero overwrites.
• Agent Integration: Harnessed smolagents.ToolCallingAgent over local LM Studio endpoints (Qwen2.5-7B-Instruct) with transparent offline fallback.
• Full-Stack Dashboard: Engineered a responsive React 19 + TypeScript interface with color-coded category badges and an unskippable approval modal gate.
• Automated Verification: Authored 28 unit, API, agent, and security tests (pytest) and validated the production build.

🔗 Repository & Code

• GitHub Repository: https://github.com/Ani0811/slothdesk
• License: MIT
• Architecture Deep-Dive: docs/ARCHITECTURE.md
• Security Testing Report: docs/SECURITY_TESTING.md
• Demo Walkthrough Script: docs/DEMO_SCRIPT.md