DEV Community

Aayushi Shinde
Aayushi Shinde

Posted on

LazyDesk — Clean Files. Keep Your Brain. 🦥

#devchallenge #hf26challenge

Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady Submission 🦥

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

LazyDesk — Clean Files. Keep Your Brain. 🦥

"Stop sorting files one by one. Let your local AI prepare the plan while you stay in control."

What I Built

LazyDesk is an open-source, local-first file cleanup agent engineered to eliminate the manual chore of organizing messy directories like Downloads or Desktop without sending a single file name or document to cloud APIs.

Unlike basic file-organizer scripts that blindly sort strictly by .ext (dumping code snippets into documents or bank receipts into random pictures), and unlike unpredictable autonomous agent scripts that execute raw shell commands, LazyDesk is built on the "Slow and Steady" principle:

  1. Metadata-Only AI Planning: LazyDesk scans an approved directory, extracts file metadata (filename, byte size, extension), and streams this structure to a local open-weight model (Qwen2.5:3b-instruct or 1.5b-instruct via Ollama).
  2. Contextual Categorization: The model categorizes files into purpose-built buckets (Career and Resumes, Study Materials, Financial & Receipts, Source Code, Archives, Installers, Media) with confidence scores (0–100%), risk ratings, and plain-English rationales.
  3. Interactive Human-in-the-Loop Review: Users can inspect every proposed move in a React 19 dashboard, edit destination folders inline, filter by risk level, and uncheck files.
  4. Collision-Immune Execution & Dry-Run: Performs an in-memory dry-run before touching disk. LazyDesk refuses to overwrite existing files, skipping collisions automatically.
  5. Cryptographic Manifest & 1-Click Rollback: Every executed batch is saved into .lazydesk_manifest.json with SHA-256 hashes and timestamps. A single click on "Undo Batch" verifies the destination and restores every file to its exact origin.
  6. Bitwise Duplicate Detective: Uses chunked 64 KB SHA-256 streaming hashes (independent of filename) to group identical files and compute exact recoverable bytes without double-counting.

Who gets to be lazier?

  • Developers with hundreds of unzipped repos, Docker dumps, and .env configs.
  • Students drowning in lecture slides, syllabi, assignment PDFs, and problem sets.
  • Freelancers and creators sorting quarterly tax invoices, contracts, and video captures.

Demo

The repository includes complete step-by-step instructions to run LazyDesk locally with one-click PowerShell scripts, generate a 19-file synthetic test sandbox, and test the full scan, AI planning, dry-run simulation, and 1-click rollback cycle.

Code

LazyDesk is completely open-source under the Apache 2.0 license:

Key Architecture Modules:

  • backend/app/scanner.py: Root boundary containment engine. Validates paths using Path.resolve().relative_to(approved_root) and rejects path traversals (..), symlinks, and system directories (C:\Windows, C:\Program Files).
  • backend/app/ai_planner.py: Ollama client (http://127.0.0.1:11434) enforcing strict Pydantic v2 schemas (PlanRecommendation). Includes prompt injection sanitization and an offline deterministic keyword classifier fallback.
  • backend/app/duplicates.py: Memory-efficient 64 KB chunked SHA-256 bitwise hasher for duplicate detection across multi-gigabyte files without memory spikes.
  • backend/app/operations.py: Dry-run engine, atomic file relocation, collision avoidance, and manifest ledger with rollback verification.
  • backend/tests/: 19 automated Pytest unit and security tests covering boundary containment, duplicate math, dry-run simulation, and undo conflicts.

How I Built It

LazyDesk was built around an open-weight local stack optimized for everyday consumer laptops (tested on an 8 GB RAM laptop with an NVIDIA RTX 2050 4 GB GPU):

1. Local AI Engine (Ollama + Qwen2.5)

  • Model: Qwen2.5:3b-instruct (and Qwen2.5:1.5b-instruct for ultra-low memory setups).
  • Quantization: Q4_K_M (4-bit quantization). The 3B model requires only ~1.9 GB of disk storage and ~2.4 GB of VRAM, running at high token speeds on local hardware.
  • Structured Schema Enforcement: The prompt feeds an array of file metadata objects and forces a JSON array response conforming to PlanRecommendation(filename, suggested_folder, confidence, reason, risk_level).
  • Zero-Crash Fallback: If Ollama is offline or unpulled, LazyDesk's RuleBasedPlanner automatically handles classification using keyword heuristics (matching resume tokens, financial indicators, and code extensions) so the application remains 100% functional offline.

2. Defense-in-Depth Security

Because the agent handles real files, safety is enforced in code, never delegated to the LLM:

  • Prompt Injection Defense: Only filenames, sizes, and extensions are passed to the model. File contents are never read or passed into the prompt, preventing indirect prompt injection from malicious files.
  • Path Sanitization: Destination paths are validated through sanitize_relative_path(), stripping absolute prefixes, drive letters, and traversal tokens (..).
  • Collision Protection: Before moving file.pdf into Documents/file.pdf, the engine checks destination.exists(). If occupied, the operation is skipped and recorded as a collision.
  • Non-Destructive Guarantee: Duplicates are exposed with byte-level SHA-256 proof in the UI, but LazyDesk never deletes files automatically.

Why Does Open Innovation Matter?

Open innovation—specifically open-weight models and open-source inference engines—is the only reason LazyDesk can exist responsibly:

  1. Absolute Privacy for Sensitive Personal Data: A person's Downloads folder contains salary slips, tax returns, medical records, identity scans, and proprietary code. Piping those filenames and directory hierarchies to cloud APIs like OpenAI or Anthropic violates basic privacy hygiene. With open-weight Qwen2.5 running on Ollama, all inference happens strictly over 127.0.0.1.
  2. Zero Recurring Costs or API Keys: Closed APIs require credit cards, monthly subscriptions, token quotas, and active internet connections. Open-weight models are free to run forever, even when working completely offline on a plane or train.
  3. **Reproducible, Auditable Software

Top comments (1)

Collapse
 
dabhi_rohit_5ebdeb38bb301 profile image
Dabhi Rohit •

Hy how many Hackathon participate u?
I don't know about dev. I earliest joined it and builded first project using ai can u give more info about dev? Help me🙂