FolderPilot: A Local AI Folder Organizer That Is Built Never to Delete a File

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

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

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

Three rules shaped the whole project:

127.0.0.1 with an open-weight model served by Ollama.

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

Organize anything. Delete nothing.

Privacy-first, local folder organizer with interactive visual analytics,

append-only rollback journaling, and on-device AI.

Overview · How it works · Features · Safety model · Quick start

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

Typical cloud organizers require up private documents to external servers. Other utility scripts use aggressive delete operations that risk permanent data loss.

FolderPilot runs entirely on local hardware, inspects documents privately on 127.0.0.1, and guarantees that no file can ever be deleted.

Running open-weight language models locally on consumer hardware changes the economics and security of desktop file management:

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

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

Existing options each fail in a different way:

Make the AI the last resort, and make the file system layer safe by construction.

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

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

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

flowchart TD
    A["Select any folder"] --> B["Background scan"]
    B --> C["Tier 1: extension and filename rules"]
    C --> D["Tier 2: SHA-256 duplicate detection"]
    D --> E["Tier 3: keyword prototypes on extracted text"]
    E --> F["Tier 4: local LLM, JSON schema output"]
    F --> G["Draft plan, unapproved"]
    G --> H["User reviews, edits, approves"]
    H --> I["Journal entry written"]
    I --> J["mkdir / move / rename"]
    J --> K["Undo: single op, batch, or full workspace"]

Every file gets a category and a reason, so the review screen can show why it was placed where it was.

The frontend never talks to anything but the local backend, which binds to 127.0.0.1.

The interface has these views:

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

The model does two jobs:

Why open weights mattered here:

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

Example 1: classification

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

Example 2: a destructive request

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

Example 3: undo

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

Most organizers confirm before they delete. This one cannot delete.

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

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

The tests were written around the guarantees, not the features. If a safety claim appears in the README, there is a named test behind it.

Requirements: Python 3.11+, Node.js 20+, and Ollama.

ollama pull gemma3:1b
cd backend && python -m pip install -r requirements.txt
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

In a second terminal:

cd frontend && npm install && npm run dev -- -p 3000

Then open http://127.0.0.1:3000. On Windows, run.bat starts both.

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