Sift ⚡

Safety-First Local File Organizer & Automation Engine
Clean up messy directories instantly with 1-click transaction undo. Hazel & organize-cli alternative for terminal lovers.

Sift automatically categorizes, moves, compresses, and cleans up your files based on customizable YAML rules and curated community recipes. Built in Rust with zero-overhead file scanning and guaranteed 1-click rollback safety.

---

📊 Benchmark Comparison & Environment

Empirical benchmark measured on a directory containing 23,656 real files (PDFs, images, and text documents):

Metric	Sift (Rust Native)	organize-cli (Python)	Advantage
Total CPU Execution Time	0.06 s (60 ms)	1.84 s	~30x Faster
Peak Memory Footprint (RAM)	22.0 MB	54.2 MB	~2.5x Less RAM
1-Click Transaction Undo	Native (sift undo)	None / Manual	Zero Data Loss
Real-Time TUI Dashboard	Native (sift watch)	None	Live Visual Log

🔬 Test Environment & Methodology

• Hardware & OS: Apple Silicon (M-series) / macOS / APFS Local SSD
• Dataset: 23,656 generated files (.pdf, .png, .log) under a single target directory
• Measurement Tools: /usr/bin/time -l for CPU time and peak resident set size (peak memory footprint)
• Execution Command: ./target/release/sift <target_dir> -x vs organize run
• Build Mode: Release profile (cargo build --release)

---

🔥 Key Features

• 🛡️ Safety-First Architecture: Every single action is logged. Undo any operation with 1-click rollback (sift undo).
• 🔍 Risk-Free Dry-Run: Simulate file organization before making any disk modifications.
• 📊 Real-Time TUI Dashboard: Monitor live directory activity with a modern terminal dashboard (sift watch).
• 🤖 Native macOS Launchd Daemon: Run hands-free continuous file organization in the background (sift daemon start).
• 📦 Curated Recipe Ecosystem: Pre-built rules for Downloads auto-trash, Screenshots sorting, and Tax Receipts (sift recipe list).
• 🏷️ macOS Finder Color Tags: Filter files by Finder tags and automatically apply or remove color tags (add_tags).
• ⏱️ Time-Based Auto-Archiving: Auto-trash or ZIP compress files modified/created/accessed before N days.
• 🔔 Native macOS Desktop Notifications: Receive Hazel-style background alert banners when files are organized.
• ⚙️ IDE-Ready YAML Schema: Ships with full JSON Schema support for auto-completion and validation in VS Code and Neovim.

---

⚡ Quick Start

📦 Installation

One-Line Shell Installer (macOS & Linux)

curl -fsSL https://raw.githubusercontent.com/taevel02/Sift/refs/heads/main/install.sh | sh

Cargo Install

cargo install --path .

---

🚀 Common Commands

1. Initialize Configuration

Generate global configuration in ~/.config/sift/config.yaml:

sift init

2. Validate Configuration

Ensure rules and regular expressions are syntax and semantic valid:

sift check

3. Recipe Management Ecosystem

Discover, view, enable, and disable pre-built modular recipes:

# List all available curated recipes and their status
sift recipe list

# Enable a curated recipe (e.g., downloads-auto-trash)
sift recipe enable downloads-auto-trash

# Check active enabled recipes
sift recipe status

# Disable a recipe when no longer needed
sift recipe disable downloads-auto-trash

4. Dry-Run Simulation

See exactly what files would be moved without touching your disk:

sift ~/Downloads

5. Execute File Organization

Run organization and record transaction history:

sift ~/Downloads -x

6. Instant 1-Click Rollback

Made a mistake? Undo the most recent transaction instantly:

sift undo

7. Real-Time Terminal Dashboard (TUI)

Launch the live terminal monitoring dashboard:

# Live simulation mode
sift watch ~/Downloads

# Live execution mode (with Hazel desktop notifications)
sift watch ~/Downloads -x

TUI Keybindings: q / Esc to quit, c to clear logs, u to undo last transaction.

8. Native macOS Background Daemon

Keep your Downloads folder clean automatically 24/7 in the background:

# Start background launchd daemon
sift daemon start

# Check daemon status
sift daemon status

# Stop background daemon
sift daemon stop

---

📜 Real-World Configuration (config.yaml)

# yaml-language-server: $schema=https://raw.githubusercontent.com/taevel02/Sift/refs/heads/main/schema.json
version: "1"
notify: true

rules:
  - name: "1. Auto-Trash Old Downloads"
    source_dir: "~/Downloads"
    filters:
      modified_before_days: 7
    action: "trash"

  - name: "2. Organize Desktop Screenshots"
    source_dir: "~/Desktop"
    filters:
      regex: "^(Screen Shot|Screenshot).*"
    target_dir: "~/Pictures/Screenshots/{year}/{month}"

  - name: "3. Tag & Organize PDF Tax Receipts"
    source_dir: "~/Downloads"
    filters:
      extensions: ["pdf"]
      regex: "(?i).*(tax|receipt|invoice|영수증).*"
    target_dir: "~/Documents/Receipts/{year}"
    add_tags: ["Green"]

---

🤝 Contributing Community Recipes

Have a great file organization workflow? Share it with the community by contributing a new recipe!

1. Create a .yaml file inside the recipes/ directory (e.g., recipes/my-custom-cleaner.yaml).
2. Include the standard $schema header, version, name, description, and rules:

   # yaml-language-server: $schema=https://raw.githubusercontent.com/taevel02/Sift/refs/heads/main/schema.json
   version: "1"
   name: "my-custom-cleaner"
   description: "Automatically cleans up temporary build artifacts"
   enabled: true
   
   rules:
     - name: "Clean Build Artifacts"
       source_dir: "~/Downloads"
       filters:
         extensions: ["tmp", "log"]
       action: "trash"

3. Test your recipe syntax with sift check.
4. Open a Pull Request on GitHub.

---

🛡️ Safety & Collision Policy

When a target destination already contains a file with the same name, Sift automatically applies a non-destructive auto-rename policy (document_1.pdf, document_2.pdf) to protect your data from being overwritten.

---

💻 Tech Stack & Dependencies

• Core Engine: Rust (2024 Edition)
• TUI Dashboard: ratatui + crossterm
• File System Monitoring: notify
• CLI Parsing: clap
• OS Trash Support: trash
• Notifications: notify-rust / macOS UserNotifications API

---

📄 License & Project Links

• License: Distributed under the MIT License.
• Contribution Guidelines: Check out CONTRIBUTING.md to get started.
• Code of Conduct: Review our community CODE_OF_CONDUCT.md.
• IDE JSON Schema: Explore schema.json for YAML validation.
• Agent & Architecture Guide: Read AGENTS.md for internal engine specs.

---

📈 Star History