Your files are
scattered.
This fixes that.
Consolidate Desktop, Downloads, and any other folders into one organized structure, with a full backup and one-command undo before a single file moves.
No bash experience required. Claude Code walks you through every step.
Two years of screenshots, installers, half-finished drafts: all on the Desktop or in Downloads. I'd spend five minutes hunting for files I knew I had. I wrote this to fix that, ran it on my own machine, and I haven't lost a file since.
No user quotes yet. This tool is new. If you try it and it works for you, open an issue and tell us what happened. The jobs product managers are most often hiring this for: cleaning up before a new role, before a team demo, or just reclaiming the mental overhead of a Desktop that long ago stopped being useful.
You're in control at every step
The tool runs in four phases. The first two are completely read-only. Nothing is written to disk until you give explicit approval. Twice.
read-only scan
read-only plan
writes scripts & backup
runs migration
Changed your mind? Before any file moves, two independent recovery paths are created: a reversal script that puts every file back, and a full .tar.gz backup. See Undo options ↓
Four phases, two permissions
Each phase builds on the last. You can stop at any point before Execute and nothing will have changed on your filesystem.
Writes four timestamped files to your output directory:
manifest.txt — full audit trail of every planned move
execute.sh — the migration script
reversal.sh — one-command undo
backup.tar.gz — complete backup of all source files
Set up in under 5 minutes
The only prerequisite is Bash 4+. macOS ships with Bash 3.2, which is
too old. When you use Claude Code, it detects this automatically and runs
brew install bash for you before doing anything else. No manual setup needed.
git clone https://github.com/gfreedman/file_folder_cleanup_util.git
Claude Code reads the built-in CLAUDE.md and knows exactly how to run each phase. No command memorization needed.
Just tell Claude which folders to pull from and where to move things. Plain language is fine.
Once when the scripts and backup are generated. Once when the migration runs. Nothing else is required of you.
You: Help me consolidate my Desktop and Downloads into Documents
Claude: Scanning ~/Desktop and ~/Downloads…
Found 239 files (1.4 GB) · 7 duplicates · 2 large files
Proposed structure for ~/Documents:
Media/Images · Media/Audio · Media/Video
Projects/ · Financial/ · Archives/
Claude: Does this look right? I'll generate the scripts next.
You: Yes, go ahead
Claude: ✓ Backup created: backup_2026-04-17.tar.gz
✓ Migration script ready ✓ Reversal script ready
✓ Dry run: 239 moves, 0 conflicts. Ready to execute?
You: Yes
Claude: ✓ Done. Desktop and Downloads are now empty.
To undo: bash ~/Documents/reversal_2026-04-17.sh
You can run each phase directly from the terminal. You'll need to install Bash 4+ first if you haven't already: brew install bash
$ bash src/analyze.sh ~/Desktop ~/Downloads
# Phase 2 — propose a structure (read-only)
$ bash src/propose.sh ~/Documents --template personal
# Phase 3 — generate scripts + backup (1st approval)
$ bash src/generate_plan.sh \
--sources ~/Desktop,~/Downloads \
--target ~/Documents \
--output ~/Documents
# Phase 4 — preview, then execute (2nd approval)
$ bash src/execute.sh execute_2026-04-17.sh --dry-run
$ bash src/execute.sh execute_2026-04-17.sh --execute
Changed your mind? Undo it.
Before any files move, Phase 3 creates two independent recovery paths. Use whichever is fastest for your situation.
The backup is created first. The .tar.gz archive exists before execute.sh touches a single file. Even if execution fails halfway through, your originals are safe.
Moves every file back to its exact original path. Generated automatically alongside the migration script.
Restoring 239 files…
✓ All files returned to original locations.
A complete .tar.gz snapshot of your source folders, made before anything moves. Restores everything including file metadata.
✓ Complete restore finished.
Choose a structure template
Pick a built-in template or define your own layout during the proposal phase. You can customize any template before committing.
├── Media/
│ ├── Images
│ ├── Audio
│ └── Video
├── Financial/
├── Projects/
└── Archives/
├── Clients/
├── Contracts/
├── Invoices/
├── Reports/
├── Marketing/
└── Archive/
├── Files/
├── Media/
└── Archive/
How duplicates and conflicts are handled
The tool never silently overwrites a file. Every conflict is resolved deterministically and logged in the manifest so you have a full record.
different content
_from_[source] suffix so you can compare and decide later.already exists
Environment variables
Set any of these before running a script to override the defaults. All are optional. The tool works out of the box without any configuration.
| Variable | Default | What it controls |
|---|---|---|
CLEANUP_LARGE_FILE_THRESHOLD |
104857600 |
Flag files larger than this many bytes (default: 100 MB) |
CLEANUP_DRY_RUN |
1 |
Set to 0 to skip the preview step and execute immediately |
CLEANUP_CREATE_BACKUP |
1 |
Set to 0 to skip backup creation (not recommended) |
CLEANUP_OUTPUT_DIR |
Current directory | Where to write the manifest, scripts, and backup archive |
Common questions
Will this delete any of my files?
No. The tool only moves files; it never deletes them. Before any move happens, a full .tar.gz backup of your source folders is created. If anything goes wrong, you have two ways back to exactly where you started: the reversal script and the backup archive.
Can I undo a reorganization after the fact?
Yes. Two recovery paths are generated automatically before any files move:
Reversal script: runs the migration in reverse, moving every file back to its original path:
bash ~/Documents/reversal_2026-04-17.sh
Backup archive: a complete .tar.gz snapshot. Use this for a full restore:
tar -xzf ~/Documents/backup_2026-04-17.tar.gz -C /
Both files are timestamped, so you can identify them even if you run the tool multiple times.
Do I need to use Claude Code, or can I run it standalone?
Both work. Claude Code is recommended because it walks you through the four phases conversationally and handles all command arguments for you. No bash knowledge needed. But every script can also be run directly from a terminal. See the standalone usage section above.
Do I need to install Bash 4+ myself?
Not if you're using Claude Code. It checks your Bash version before running anything and installs Bash 4+ via Homebrew automatically if needed. You just say yes when it asks.
Standalone users: run brew install bash once before the first phase. Takes about 30 seconds.
Why Bash 4 at all: macOS ships Bash 3.2 (circa 2007) because Apple can't redistribute newer GPL-licensed versions. The scripts use associative arrays (declare -A), which require Bash 4.
What happens to my symlinks?
Symlinks are skipped. All phases use find -type f, which matches only regular files. If you have important symlinks in your source directories, move them manually after the migration completes.
Does this work on Linux?
macOS only, currently. The scripts depend on BSD versions of stat, shasum, and find that ship with macOS. GNU coreutils on Linux use different flag syntax.
Do I need admin or sudo access?
No. The tool operates only within your home directory and uses only the permissions your user account already has. It never requests elevated privileges.
What if two folders have files with the same name?
Identical content (same SHA-256 hash): one copy is kept, the duplicate is logged in the manifest.
Same name, different content: both files are kept. The second gets a _from_[sourcefolder] suffix so you can compare them manually.
Destination already exists: the incoming file is skipped and flagged in the manifest for you to handle manually. Never silently overwritten.
What exactly gets written during the Generate phase?
Four timestamped files are written to your output directory (configurable via CLEANUP_OUTPUT_DIR):
manifest_YYYY-MM-DD.txt — every planned file move, in order
execute_YYYY-MM-DD.sh — the migration script
reversal_YYYY-MM-DD.sh — the undo script
backup_YYYY-MM-DD.tar.gz — a full backup of your source folders
Nothing outside this output directory is touched until you explicitly run the execute script.
I have thousands of files. Will this be slow?
The Analysis phase is the most time-intensive because it computes SHA-256 checksums for every file to detect true duplicates. For typical home directories (a few thousand files under a few gigabytes), this takes seconds to a minute. Very large libraries (tens of thousands of files, or multi-gigabyte raw photo collections) may take longer. Progress is shown as it runs.
Can I reorganize files already in my target folder?
Yes, but review the proposed structure carefully first. If you include the target folder as a source, the tool will analyze and move its existing contents too. The dry-run output in Phase 4 will show you every planned move before anything happens.
How do I report a bug or request a feature?
Open an issue on GitHub. Please include your macOS version, Bash version (bash --version), and the output from the failing script.
Known limitations
Symlinks are skipped. find -type f matches regular files only. Move symlinks manually after migration.
macOS only. Uses BSD stat, shasum, and find syntax. Not compatible with Linux GNU coreutils.
Bash 4+ required. Claude Code installs it automatically. Standalone users: brew install bash once.