tidyv0.2.0
GitHub
tidy v0.2.0/Rust 1.75+

Fast, non-destructive file organizer & watcher in Rust

Organize cluttered folders into clean directory trees with collision safety and instant SQLite rollback.

Star on GitHubInstall CLI
$npx @humayan-x/tidy run --path ~/Downloads --dry-run
< 5 MB

Static binary

~3–5 MB

Idle RSS memory

SQLite Ledger

Instant batch undo

Non-Destructive

Zero overwrites

Interactive Sandbox

Organization & Rollback Demo

Non-destructive collision renaming • SQLite undo journal
tidy-simulator — ~/Downloads (Unsorted Flat)
State: Cluttered (8 files in root, unorganized)
Ledger: ~/.local/state/tidy/history.db
~/Downloads/invoice_2026_q1.pdf
Downloads (root)
1.4 MB Ready
~/Downloads/quarterly_report.xlsx
Downloads (root)
840 KB Ready
~/Downloads/screenshot_dashboard.png
Downloads (root)
2.1 MB Ready
~/Downloads/screenshot_dashboard.png
Downloads (root)
1.8 MBCollision
~/Downloads/release_v2.0.tar.gz
Downloads (root)
42.6 MB Ready
~/Downloads/large_dataset.zip.crdownload
Downloads (root)
1.2 GB (writing) Guard
~/Downloads/cluster_deploy.rs
Downloads (root)
14 KB Ready
~/Downloads/podcast_episode_42.mp3
Downloads (root)
68 MB Ready
Core Engine

Engineered for Safety & Speed

Rust 2021 • Zero dependencies • SQLite WAL
< 5 MB Static

Native Rust Binary

Compiled with LTO and zero runtime dependencies for sub-millisecond dispatch.

CLI:cargo build --release
Zero Overwrites

Non-Destructive Operations

Automatic incremental collision renaming (e.g. photo (1).jpg) and symlink barriers.

CLI:name (1).pdf
SQLite Ledger

Transactional Undo

Every file move is journaled into local history.db for immediate single or batch rollbacks.

CLI:tidy undo --last 3
MIME & Compound

70+ Formats Classifier

Native handling for compound archives (.tar.gz) and magic-byte MIME fallback.

CLI:compound .tar.gz
~3–5 MB RSS

Adaptive Kernel Watcher

inotify and FSEvents hooks with download guards that ignore in-progress files.

CLI:tidy watch --debounce 2000
systemd & launchd

Native OS Daemon

Manage persistent background watching via systemd --user (Linux) or launchd (macOS).

CLI:tidy service enable
Architecture

Execution Pipeline

8 verification gates prior to filesystem mutation
01Input

Event Trigger

inotify (Linux) / FSEvents (macOS) event or manual CLI trigger.

2000ms debounce
02Filter

Download Guard

Bypasses active browser downloads (.crdownload, .part, .aria2).

In-progress safety
03Lock

Stability Filter

Samples file size across intervals and queries advisory OS locks.

500ms write tick
04Parser

MIME Classifier

Matches compound extensions (.tar.gz) with magic-byte fallback.

70+ file formats
05Routing

Category Routing

Maps file to structured directory hierarchy (e.g. Documents/PDF).

Ext-nested folders
06Safety

Collision Handler

Appends incremental counter (file (1).ext) if name already exists.

Never overwrites
07I/O

Atomic Mover

Fast atomic rename with staged verify-unlink fallback across disks.

EXDEV cross-device
08Ledger

SQLite Journal

Commits batch transaction into history.db for immediate undo.

WAL mode commit
EXDEV Copy-Verify

Verifies size and checksum before deleting source across disk partitions.

Symlink Isolation

Never traverses directory symlinks targeting outside the watch root.

Atomic Ledger

Immediate WAL journal writes guarantee zero orphaned files during undo.

Benchmarks

Resource Footprint

Measured on Linux 6.8 x86_64, idle background watcher
Swipe horizontally to compare5 platforms
Metrictidy (Rust)Python (Watchdog)Node.js (Chokidar)Shell Script
Idle Memory (RSS)~3.5 MB~45–60 MB~65–90 MB~15 MB
Startup Latency< 2 ms140 ms220 ms12 ms
Binary Size / Runtime< 4.8 MB (Static)Python runtime (~80MB)Node runtime (~120MB)Bash + coreutils
Background CPU Idle< 0.05%~1.2%~1.6%~0.5%
Transactional UndoSQLite LedgerNoneNoneNone
Rules & TOML

Zero-Config Defaults, Fully Extensible

Overridable in ~/.config/tidy/config.toml
~/.config/tidy/config.toml
[settings]
# Default directory to watch when running 'tidy watch' without --path
# watch_dir = "/home/user/Downloads"

# Whether to ignore hidden files and directories (starting with '.')
ignore_hidden = true

# Debounce interval in milliseconds
debounce_ms = 2000

# Polling interval in milliseconds for write-completion stability
stability_tick_ms = 500

# Whether to scan or watch subdirectories recursively
recursive = false

# Whether to organize files into extension-based subfolders (e.g. Documents/PDF, Images/PNG)
nest_by_extension = true

# Download and temporary file guard patterns to ignore during watch/run
ignore_patterns = [
  "*.crdownload",
  "*.part",
  "*.download",
  "*.aria2",
  "*.tmp",
  "*.swp"
]

[categories.Documents]
destination = "Docs"
extensions = ["pdf", "docx", "xlsx", "pptx", "txt", "md", "csv"]

[categories.Archives]
destination = "Archives"
extensions = ["zip", "tar.gz", "tar.bz2", "tar.xz", "tar.zst", "7z", "rar"]
Generate scaffold: tidy initMagic-byte fallback via infer
Scaffold default configuration:
tidy init→ ~/.config/tidy/config.toml
Distribution

Installation & Commands

Linux (x86_64, aarch64) • macOS (Apple Silicon, Intel)
$curl -fsSL https://raw.githubusercontent.com/humayan-x/tidy/main/install.sh | sh

Fetches pre-compiled static binary for Linux (x86_64 / aarch64) or macOS (Apple Silicon / Intel).

CLI Commands

$ tidy run --dry-runPreview without moving
$ tidy watchStart kernel watcher
$ tidy undoRevert last batch
$ tidy undo --last 3Revert last 3 batches
$ tidy statusReport DB and rules

Background Service (systemd / launchd)

Enable & start on boot:$ tidy service enable
Check service status:$ tidy service status
Follow live daemon logs:$ tidy service logs -f
Stop & disable daemon:$ tidy service disable
Shell Completions
Bashtidy completions bash > ~/.local/share/bash-completion/completions/tidy
Zshtidy completions zsh > ~/.zsh/completion/_tidy
Fishtidy completions fish > ~/.config/fish/completions/tidy.fish