gitwtfhub

wtf is macsweep?

shubhamxranga/macsweep — explained in plain English

Analysis updated 2026-05-18

2PythonAudience · vibe coderComplexity · 2/5LicenseSetup · easy

TL;DR

A free, offline terminal tool that cleans junk, finds duplicates, and organizes files on a Mac.

Mindmap

mindmap
  root((repo))
    What it does
      Storage scanner
      Duplicate finder
      File organizer
      Cache cleaner
    Tech stack
      Python
      pytest
    Safety
      System folders blocked
      Trash staging
      Undo logging
    Use cases
      Free disk space
      Remove duplicates
      Sort messy folders
    Audience
      Mac users
      Developers

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Free up disk space by clearing developer caches like Homebrew, npm, and pip.

REASON 2

Find and safely remove duplicate files without permanently deleting anything.

REASON 3

Automatically sort a messy folder into categories like Images, Docs, and Code.

REASON 4

Replace a paid Mac cleaner subscription with a free offline terminal tool.

What's in the stack?

Pythonpytest

How it stacks up

shubhamxranga/macsweep0-bingwu-0/live-interpreter010zx00x1/faresnipe
Stars222
LanguagePythonPythonPython
Setup difficultyeasymoderateeasy
Complexity2/52/52/5
Audiencevibe codergeneralgeneral

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · easy Time to first run · 5min

Just a git clone, virtual environment, and pip install, no external services or accounts needed.

MIT licensed, free to use, modify, and distribute for any purpose including commercial use.

Wtf does this do

MacSweep is a terminal based storage manager for Mac computers that works entirely offline. It is built as a free, open source alternative to paid tools like CleanMyMac, Hazel, and Gemini 2, and the author is upfront that it sends no data anywhere: no cloud connection, no telemetry, and no subscription fees. The tool bundles four main jobs into one interface. A storage scanner walks through your folders to show which files and directories are taking up the most space, along with a breakdown by file type and a live disk usage bar. A duplicate finder looks for identical files using a two step process: it first groups files by size, then hashes just the first chunk of matching files, and only runs a full checksum on the files that still look identical, which keeps it fast on large drives. A smart organizer sorts files into categories like Images, Documents, Code, and Archives using rules you can edit in a configuration file, and it shows you the planned moves before anything happens. A cache and junk cleaner targets developer clutter specifically, such as Homebrew, npm, and pip caches, old Xcode build files, stray logs, and hidden .DS_Store files, and it asks for typed confirmation before deleting anything over one gigabyte. Safety is a clear focus. Core system folders like /System, /usr, /bin, and /Library are blocked from being touched at all. Deleted files are not removed permanently, they are moved to a trash folder inside the app's own data directory, and every move or delete is logged so it can be undone with a single keypress. To try it, you clone the repository, set up a Python virtual environment, install the requirements, and run the main script from a terminal. It is written in Python, has a test suite runnable with pytest, and is released under the MIT license, so it can be used and modified freely.

Yoink these prompts

Prompt 1
Set up MacSweep in a Python virtual environment and run its duplicate finder on my Downloads folder.
Prompt 2
Show me how to customize MacSweep's default_rules.yaml to sort files by project type.
Prompt 3
Explain how MacSweep's undo logging works so I can safely try its cache cleaner.
Prompt 4
Walk me through running MacSweep's test suite with pytest.

Frequently asked questions

wtf is macsweep?

A free, offline terminal tool that cleans junk, finds duplicates, and organizes files on a Mac.

What language is macsweep written in?

Mainly Python. The stack also includes Python, pytest.

What license does macsweep use?

MIT licensed, free to use, modify, and distribute for any purpose including commercial use.

How hard is macsweep to set up?

Setup difficulty is rated easy, with roughly 5min to a first successful run.

Who is macsweep for?

Mainly vibe coder.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.