{"slug": "folderpilot-a-local-ai-folder-organizer-that-is-built-never-to-delete-a-file", "title": "FolderPilot: A Local AI Folder Organizer That Is Built Never to Delete a File", "summary": "A developer built FolderPilot, a local web app that scans folders, reads file contents, and proposes a cleaner structure as an interactive color-coded map that users review and approve before any changes are made. The tool runs entirely on 127.0.0.1 using an open-weight model served by Ollama, and its file operations module exposes only mkdir, move, and rename, making deletion impossible by design. It uses a four-tier classification pipeline that starts with cheap extension and filename rules, then SHA-256 duplicate detection, keyword prototypes, and finally a local LLM, keeping it usable on an 8 GB laptop with no GPU.", "body_md": "*This is a submission for the [Hacktoberfest Weekend Challenge: Build for a Friend](https://dev.to/challenges/hacktoberfest-weekend-2026-10-01)*\n\nFolderPilot is a local web app that scans any folder, reads what is inside the files, and proposes a cleaner structure. It shows the result as an interactive, color-coded map. You review the plan, edit it, and approve it. Nothing changes on disk until you do.\n\nI built it for a friend whose folders hold exactly the kind of files you do not want to upload anywhere: ID scans, marksheets, resumes, offer letters, and assignments, all mixed together with installers and screenshots. Cloud organizers want those documents on someone else's server. Cleanup scripts delete things. I wanted a tool that does neither.\n\nThree rules shaped the whole project:\n\n`127.0.0.1` with an open-weight model served by Ollama.\n\nThe video walks through scanning a real folder, exploring the treemap and sunburst views, reviewing the before and after plan, applying it, and rolling it back. It also shows the folder chat refusing a request to delete files.\n\n**Organize anything. Delete nothing.**\n\nPrivacy-first, local folder organizer with interactive visual analytics,\n\nappend-only rollback journaling, and on-device AI.\n\n[Overview](https://github.com/TejasRawool186/FolderPilot#why-this-exists) · [How it works](https://github.com/TejasRawool186/FolderPilot#how-it-works) · [Features](https://github.com/TejasRawool186/FolderPilot#features) · [Safety model](https://github.com/TejasRawool186/FolderPilot#safety-model) · [Quick start](https://github.com/TejasRawool186/FolderPilot#quick-start)\n\nPersonal directories such as Downloads, Desktop, and work folders routinely accumulate sensitive files—including tax returns, identity cards, college transcripts, and resumes. Most of these files remain disorganized because manual sorting is slow and tedious.\n\nTypical cloud organizers require uploading private documents to external servers. Other utility scripts use aggressive delete operations that risk permanent data loss.\n\nFolderPilot runs entirely on local hardware, inspects documents privately on `127.0.0.1`, and guarantees that no file can ever be deleted.\n\nRunning open-weight language models locally on consumer hardware changes the economics and security of desktop file management:\n\n| Dimension | Local Open-Source AI (FolderPilot) | Cloud AI APIs | \n|---|---|---|\n| **Privacy** | Local-only. File contents, extracted text, and metadata never |  | \n\nThe repository has a FastAPI backend, a Next.js frontend, a pytest suite for the safety guarantees, and docs covering the architecture, the AI integration, and the API.\n\nA Downloads folder is where files go to pile up. After a year it holds duplicate resumes (`resume_final`, `resume_final2`), screenshots named `IMG_2938.png`, installers you already ran, and a few documents you would be uncomfortable seeing leaked.\n\nExisting options each fail in a different way:\n\nMake the AI the last resort, and make the file system layer safe by construction.\n\nMost files do not need a language model. An extension, a hash, or a keyword count settles them. So FolderPilot runs cheap checks first and only sends the genuinely ambiguous files to a small local model. That keeps it usable on a laptop with 8 GB of RAM and no GPU, which is the machine I developed it on.\n\nOn the safety side, I did not add a \"confirm delete\" dialog. I removed deletion from the program. The file operations module only exposes `mkdir`, `move`, and `rename`.\n\nThe scanner walks the chosen folder and streams progress to the UI. Each file then goes through four tiers, stopping at the first one that is confident.\n\n``` php\nflowchart TD\n    A[\"Select any folder\"] --> B[\"Background scan\"]\n    B --> C[\"Tier 1: extension and filename rules\"]\n    C --> D[\"Tier 2: SHA-256 duplicate detection\"]\n    D --> E[\"Tier 3: keyword prototypes on extracted text\"]\n    E --> F[\"Tier 4: local LLM, JSON schema output\"]\n    F --> G[\"Draft plan, unapproved\"]\n    G --> H[\"User reviews, edits, approves\"]\n    H --> I[\"Journal entry written\"]\n    I --> J[\"mkdir / move / rename\"]\n    J --> K[\"Undo: single op, batch, or full workspace\"]\n```\n\n| Tier | Mechanism | Handles | \n|---|---|---|\n| 1. Rules | Extension taxonomy and filename regex | Code, archives, media, installers, screenshots | \n| 2. Hashes | Lazy SHA-256 on files with equal sizes | Exact duplicates and repeated downloads | \n| 3. Prototypes | Keyword frequency in the first ~500 extracted tokens | Assignments, invoices, offer letters | \n| 4. Local LLM | Ollama with constrained JSON output | Ambiguous PDFs and poorly named files | \n\nEvery file gets a category and a reason, so the review screen can show why it was placed where it was.\n\n| Layer | Technology | Why | \n|---|---|---|\n| Frontend | Next.js 16, React 19, Tailwind, D3.js | D3 gives full control over the treemap, sunburst, and tree comparison | \n| Backend | Python 3.11, FastAPI | Async routes and server-sent events for live scan progress | \n| Storage | SQLite in WAL mode | File index, plans, and the journal in one local file | \n| Extraction | PyMuPDF, python-docx, python-pptx | Reads text from PDFs, Word, and PowerPoint files | \n| Local AI | Ollama with Gemma 3 1B (default), Qwen 2.5 1.5B | Small enough for CPU-only machines | \n\nThe frontend never talks to anything but the local backend, which binds to `127.0.0.1`.\n\nThe interface has these views:\n\nThe default model is Gemma 3 1B (`gemma3:1b`, Q4_K_M, roughly 1.2 GB of RAM), served through Ollama. Qwen 2.5 1.5B is supported as an alternative. The model can be switched from the navigation bar at runtime, through the `POST /api/ai/model` endpoint, or with the `FOLDERPILOT_OLLAMA_LLM_MODEL` environment variable.\n\nThe model does two jobs:\n\nWhy open weights mattered here:\n\n|  | Local open model | Cloud API | \n|---|---|---|\n| Privacy | File text and metadata stay on the machine | Excerpts of private documents leave the machine | \n| Cost | No per-file cost | Metered by volume | \n| Offline | Works once weights are cached | Needs a connection | \n| Model choice | Swap models in one setting | Tied to one provider | \n\nThe tradeoff is accuracy. A 1B model will misclassify some ambiguous files, especially ones with little extractable text. That is why low-confidence files are surfaced in a review queue and why nothing is applied without approval. A user's manual category overrides are stored in local SQLite to guide later scans.\n\n**Example 1: classification**\n\nA file named `assignment_final.pdf` sits next to `assignment.pdf`. The extension alone says \"document\". Tier 2 notices the sizes differ, so they are not exact duplicates. Tier 3 reads the first page, finds terms common to coursework, and places both under a college category. The plan shows the reason on the card, and the user can drag them elsewhere if it is wrong.\n\n**Example 2: a destructive request**\n\nIn the folder chat, I typed a request to delete all the duplicate files. The chat router intercepts deletion and removal requests before they reach the model. The reply explains that FolderPilot never deletes, and offers to move the duplicates into a `_Review_Later/` folder instead. A test (`test_chat_delete_refusal`) covers this behavior.\n\n**Example 3: undo**\n\nAfter applying a plan, the Journal view lists every operation. One click on a single operation restores that file. One click on the batch restores everything the plan touched. Because the journal entry is written before each operation, an interrupted run leaves a consistent record.\n\nMost organizers confirm before they delete. This one cannot delete.\n\n`safe_ops.py` has no delete, unlink, remove, or truncate path. `test_no_delete_functions_exist` checks that this stays true.`Document (1).pdf`.` C:\\Windows` and `C:\\Program Files`, and has tests for path traversal and symlink escapes.\nI started by writing a requirements document before any code, because the safety rules had to be requirements and not afterthoughts. The repo's `docs/` folder keeps that specification along with architecture notes and a development log.\n\nThe backend came first: scanner, safe file operations, journal, and undo. I built the visual layer after that, once the plan and journal data was reliable. The default model started as Qwen 2.5 1.5B and moved to Gemma 3 1B after I tuned for memory use and speed on an 8 GB machine, with Qwen kept as a switchable option.\n\nThe tests were written around the guarantees, not the features. If a safety claim appears in the README, there is a named test behind it.\n\nRequirements: Python 3.11+, Node.js 20+, and Ollama.\n\n```\nollama pull gemma3:1b\ncd backend && python -m pip install -r requirements.txt\npython -m uvicorn app.main:app --host 127.0.0.1 --port 8000\n```\n\nIn a second terminal:\n\n```\ncd frontend && npm install && npm run dev -- -p 3000\n```\n\nThen open `http://127.0.0.1:3000`. On Windows, `run.bat` starts both.\n\nI wanted a tool I would be comfortable pointing at a folder full of someone's private documents. Keeping the model local made the privacy story simple, and removing deletion from the code made the safety story simple. A small open model turned out to be enough once it was the last step in the pipeline instead of the first.", "url": "https://wpnews.pro/news/folderpilot-a-local-ai-folder-organizer-that-is-built-never-to-delete-a-file", "canonical_source": "https://dev.to/tejasrawool186/folderpilot-a-local-ai-folder-organizer-that-is-built-never-to-delete-a-file-180m", "published_at": "2026-10-04 17:34:47+00:00", "updated_at": "2026-10-04 17:42:28.425778+00:00", "lang": "en", "topics": ["ai-tools", "ai-products", "large-language-models", "ai-infrastructure"], "entities": ["FolderPilot", "Ollama", "FastAPI", "Next.js", "TejasRawool186", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/folderpilot-a-local-ai-folder-organizer-that-is-built-never-to-delete-a-file", "markdown": "https://wpnews.pro/news/folderpilot-a-local-ai-folder-organizer-that-is-built-never-to-delete-a-file.md", "text": "https://wpnews.pro/news/folderpilot-a-local-ai-folder-organizer-that-is-built-never-to-delete-a-file.txt", "jsonld": "https://wpnews.pro/news/folderpilot-a-local-ai-folder-organizer-that-is-built-never-to-delete-a-file.jsonld"}}