sift

Sift through the mess.

A terminal file organizer built with TypeScript + Ink. Pick a folder, preview how files will be grouped, confirm, and watch it happen.

---

Install

From source (builds automatically, then makes sift available globally):

git clone https://github.com/Paranjayy/sift.git
cd sift
npm install
npm link

That's it — sift is now a global command.

Usage

sift [directory]        Organize a specific directory
sift --global           Batch organize configured folders
sift repos              List all git repos + backup status
sift repos --everywhere Deep-scan all of home
sift backup             Interactive — pick a scan scope, then choose repos
sift backup <name>      Back up one repo
sift backup --all       Back up every repo (also pushes existing remotes)
sift backup --nuke      Back up, then Trash the whole repo (full snapshot first)
sift backup --nuke-ignored  Back up, then Trash gitignored junk (node_modules etc.)
sift restore <name>     Restore a repo from its local backup bundle
sift disk [path]        Interactive size browser (Enter navigates subfolders,
                        press `d` to Trash, visual bars)
sift catalog [path]     Create recursive Markdown catalog/index of all files
                        (--out file.md, --depth N)
sift --undo             Restore the last organize
sift                    Interactive folder browser

repos/backup scan ~/Developer by default (--root <dir> to change, --everywhere to deep-scan all of home). sift backup interactively asks where to scan (Developer / Home / Everywhere / custom path) before showing the repo picker. Backups that can't reach GitHub (or when --local) go to ~/.config/sift/backups/.

Nuking is Trash-safe — nothing is deleted forever. --nuke snapshots the whole repo to a tar first, --nuke-ignored archives untracked+ignored files first, then both move things to ~/.Trash. --github/--local force the backup destination.

Messy repos are fully backed up — if a repo has uncommitted/staged/untracked changes, sift captures the working state safely using git stash to create a backup/auto-<ts> branch without touching your working tree. It pushes all branches + tags (with a fallback retry to --force-with-lease if needed) and uses mirror clones locally to preserve stashes.

Or run without installing:

npm run dev

Features

• Full folder browser — navigate the filesystem in the TUI (open/back/home/root, toggle hidden)
• Quick folder search — Ctrl+K/f fuzzy-jumps to any subfolder
• Opens where you are — starts in your current directory
• 4 grouping modes — flat, by extension, smart categories, custom rules
• Live preview — see before/after before any files move
• Safe by default — never moves without confirmation
• Undo — sift --undo restores the last organize
• Git repo inventory — sift repos shows every repo, its remote, and whether it's backed up
• Git backup — sift backup auto-creates private GitHub repos via gh, or bundles locally
• Disk size browser — sift disk launches an interactive TUI to drill down into folder sizes with visual bars, plus a d key to move folders instantly to ~/.Trash. Falls back to a clean static report if piped or non-TTY.
• Directory catalog maker — sift catalog generates a recursive, beautifully formatted Markdown snapshot (.md index) of any drive or directory, including sizes, entries, and filetype icons. Helpful for archiving offline/long-term projects.
• Batch mode — sift --global organizes Downloads, Desktop, Documents at once
• Screenshot detection — catches Screenshot * and SCR-* patterns
• Custom rules — define your own grouping in ~/.config/sift/config.yaml

Keyboard Shortcuts

Key	Action
j/k or ↑/↓	Navigate
Enter or →/l	Open folder
←/h/Backspace	Go up
o	Organize current folder
Ctrl+K or f	Quick folder search
~	Home
/	Filesystem root
t	Toggle hidden files
1/2/3	Switch mode
y	Confirm
b	Back
?	Help
q	Quit

Config

~/.config/sift/config.yaml

default_mode: smart
show_hidden: false
exclude:
  - ".DS_Store"
  - ".git"
  - "node_modules"
rules: []

Related

• Mole — Mac cleanup terminal utility
• Burrow — Open-source desktop utility
• Mouzi — Automatic Downloads organizer
• Hazel — macOS file management automation
• organize — Python file management tool

License

MIT