tidydisk: consolidate and organize a hoard of scattered files

Pull years of scattered files (old drives, phone backups, NAS dumps, recovery-tool output) into one organized, deduplicated library. Media lands in a Jellyfin/Plex-ready layout; an agent layer sorts whatever your rules can't, using a local model so filenames never leave your machine.

tidydisk fingerprints everything you point it at, drops exact duplicates and junk, and files what's left where it belongs. It moves and stages files, never deletes them.

Status: v0.1.0 (on PyPI: pip install tidydisk). The engine, the agent layer, content-derived organization, in-place library repair, the guided 2-pass web UI, opt-in enrichment connectors, and undo/dispose/doctor are all in. See docs/roadmap.md for what's deferred.

Quickstart

The 2-pass cleanup (the front door): Pass 1 analyzes everything read-only into one sealed proposal; Pass 2 is a single review-and-execute in a localhost web UI.

flowchart LR
    A[tidydisk pilot] -->|analyzes, read-only| B[sealed proposal.json]
    B --> C[tidydisk serve]
    C -->|review clusters, approve/reject| D{Execute}
    D -->|typed confirmation| E[library on disk]

$ tidydisk pilot                       # Pass 1: analyze everything -> proposal.json
$ tidydisk serve                       # Pass 2: review clusters -> approve -> Execute

Headless Pass 2: tidydisk pilot --execute --proposal <proposal.json> --approve-all.

Install from PyPI (zero runtime deps: stdlib only):

$ pip install tidydisk

Or the granular CLI:

$ tidydisk init                        # writes an annotated tidydisk.toml
$ tidydisk check                       # validates config + root reachability
$ tidydisk scan library                # fingerprint your library into the index
$ tidydisk scan old-drive              # fingerprint a source
$ tidydisk verdicts old-drive          # ORGANIZED / JUNK / UNIQUE / REVIEW
$ tidydisk plan organize old-drive     # uniques -> library
$ tidydisk apply ".tidydisk/plans/plan-organize-old-drive-ab12cd34.jsonl" --execute
$ tidydisk plan dedup old-drive        # duplicates + junk -> staging (same-drive, reversible)
$ tidydisk apply ".tidydisk/plans/plan-dedup-old-drive-9f00aa11.jsonl" --execute
$ tidydisk verify library
$ tidydisk plan reorganize --under Video/old-drive --exif   # repair flat dumps in place

Agent layer (local model via Ollama, or any OpenAI-compatible endpoint):

$ tidydisk agent triage old-drive     # LLM recommends dispositions for the REVIEW pile
$ tidydisk agent classify old-drive   # labels the tail your rules didn't cover
$ tidydisk agent eval                 # measures the configured chain on the golden sets

A fully-annotated example config is browsable at examples/tidydisk.toml.

One small kernel owns every filesystem mutation and there is no delete API anywhere in the codebase (AST-enforced in CI): staging is reversible, and disposal only ever happens through tidydisk dispose, gated behind a typed confirmation.

See docs/formats.md for the plan/summary JSON schemas and exit codes.

License

AGPL-3.0-or-later. See LICENSE.