Folder Saga

AbleVLabs · organize · discover · reclaim your space

See where your disk actually went, then tidy the mess — sort a folder full of loose files into clean category folders and sweep duplicates and junk into a review vault, with a one-click undo that puts everything back exactly.

The easy way

Double-click FolderSaga.bat. A window opens. Press Choose folder, then pick a quest.

Look (read-only): Scan the realm for the report, Reclaim space to find duplicates and junk, Open the map for the clickable tree, Realm map to see your whole drive as a quest board. None of these change a single file.

Tidy (reversible): Preview tidy shows you exactly what will move and where, the chaos score before and after, and how much space you'll reclaim — without touching anything. Restore order then does it: loose files sorted into Images/, Documents/, Installers/ and so on, duplicates and junk moved (never deleted) into _SagaVault/. Changed your mind? Undo last tidy returns every file to precisely where it started.

The map opens in your browser as a tree: click a folder to open it and see the files nested inside, indented so you can see what lives within what. Each row has a bar showing its share, coloured by kind — video pink, images green, installers orange, code blue. There's a Treemap toggle up top if you ever want the rectangle view instead.

Realm mode — the game skin

Press Realm map and your drive becomes a quest board. Every folder is a region with a chaos rating (how much loose mess is sitting in it); your messiest folder is crowned the boss. Restoring a realm (a tidy) pays gold — the space you reclaim — and XP. You level up, keep a daily streak, and unlock achievements ("Dupe Slayer", "Gold Hoarder", "Keeper of the Drive"). Your level and streak ride in the app's header, saved between sessions in saga_save.json.

It's a skin, not a gimmick: every quest is carried out by the same reversible engine below, with the same preview-first, undo-anytime, never-delete safety. The fantasy is there to make a chore into something you'll actually come back to — which, for keeping a drive tidy, is the whole battle.

The command line, if you prefer it

python bowerbird.py scan D:\
python bowerbird.py scan . --files
python bowerbird.py map "C:\Users\me\Downloads"    # clickable tree
python bowerbird.py scan . --chart downloads.png   # static image

No dependencies for the report or the interactive tree. --chart (the static image) wants matplotlib and says so plainly if it isn't there.

The logo

Save the Folder Saga artwork as logo.png in this folder and the window picks it up automatically. Without it, the header just reads FOLDER SAGA in text — nothing breaks either way.

---

Trust, on purpose

Looking never changes anything. Scan, Reclaim and Map open nothing, write nothing, move nothing, delete nothing. There is a test — test_scan_writes_nothing — that snapshots a folder, scans it, and asserts not one byte, name or timestamp moved. A tool that reports on your files should be provably unable to change them.

Tidying moves files, but never loses one. The organize engine holds to three rules, and each is enforced by a test:

1. Nothing is ever deleted. Duplicates and junk are moved into a _SagaVault folder inside the target. You empty the vault yourself, when you're sure. Folder Saga's hands stay off the delete key.
2. Every move is logged and reversible. Each move is written to a transaction log as it happens, so Undo restores every file to its exact original place — and even a crash mid-tidy leaves a log that still rolls back cleanly.
3. It only touches loose files sitting directly in the folder you chose. It does not reach into your existing subfolders and rearrange them, and it never moves anything outside the target.

The load-bearing test, test_tidy_then_undo_restores_everything, tidies a messy folder, undoes it, and asserts the folder is byte-for-byte back to where it started. If that test ever fails, the tool isn't safe to ship — so it can't.

---

How it stays fast and light

A full drive can be millions of files, and holding an object for every one of them is how a disk tool runs a machine out of memory analysing the machine's memory. Folder Saga keeps the directory tree — far fewer folders than files — and for everything else keeps only aggregates: a total, a per-category tally, and a fixed-size heap of the biggest files. The interactive tree builds each folder's contents only when you expand it, so even a whole drive opens instantly.

Symlinks and Windows junctions are not followed. Following a link into a folder already counted double-counts the space, and a link that points at its own ancestor loops forever. They are skipped and tallied instead.

---

Tests

pip install pytest
pytest test_bowerbird.py test_organize.py test_realm.py -q

test_organize.py is the safety net for the parts that move files: round-trip undo, never-delete, name-collision survival, and "the subfolder you already had is never touched." test_realm.py keeps the game honest: the level bar never overflows, a streak survives an overnight gap of exactly one day, and surveying the drive reads without writing.

---

Where it's going

The plan, in order — the first four are built:

1. scan / map — where the space went ✓
2. dupes — identical files by content hash, not name ✓
3. junk — empty folders, temp files, half-finished downloads ✓
4. organise — preview a tidy-up, approve it, every move reversible ✓
5. the realm — the drive as a quest board: chaos scores, XP, levels, streaks, achievements, boss folders ✓
6. content-aware names — photos by date taken, PDFs by their real title
7. watch mode — teach a rule once, a folder stays tidy forever

Each built read-only or dry-run first, because the whole point of Folder Saga is that it is the file tool you can trust with the files.

---

© 2026 AbleVLabs — Carlos Abel Vivanco