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

Stop deciding where your files belong. Tidy does it for you.

Fast, non-destructive file organizer and background watcher in Rust. Organizes your ~/Downloads folder by default, or point it to any folder you choose.

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
Quickstart Workflow

Essential Commands

Zero fluff • Complete CLI lifecycle in 6 steps
STEP 01CLI

Install & Approve Script

Install globally via npm (with script permission) or direct curl shell script.

npm (npm 10.9+):
$npm install -g --allow-scripts=@humayan-x/tidy @humayan-x/tidy
curl (direct binary):
$curl -fsSL https://raw.githubusercontent.com/humayan-x/tidy/main/install.sh | sh
STEP 02CLI

Dry-Run vs Real Run

Simulate first to see planned moves safely, then execute live on Downloads.

Preview Downloads (safe):
$tidy run --path ~/Downloads --dry-run
Real run on Downloads:
$tidy run --path ~/Downloads
STEP 03CLI

Target Specific Folder

Run on your current directory or point tidy to any arbitrary folder.

Current working directory:
$tidy run
Target custom folder:
$tidy run --path ~/Projects/Assets
STEP 04CLI

Configure Rules & Folders

Scaffold and edit the default TOML configuration to define custom rules.

Generate default config:
$tidy init
Config path:
$~/.config/tidy/config.toml
STEP 05CLI

Run in Background (Daemon)

Daemon defaults to watching ~/Downloads on boot; override with --path.

Watch ~/Downloads (default):
$tidy service enable
Watch custom folder:
$tidy service enable --path ~/Desktop
Check status & memory:
$tidy service status
Follow live logs:
$tidy service logs -f
STEP 06CLI

Instant Undo & Rollback

Revert any single or multi-run batch safely via embedded SQLite ledger.

Revert last operation:
$tidy undo
Revert last 3 batches:
$tidy undo --last 3
Preview undo rollback:
$tidy undo --dry-run
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