Free, open-source macOS cleaner. CleanMyMac alternative with zero telemetry. Native SwiftUI, scheduled auto-cleaning, Xcode/Homebrew/system cache cleanup. MIT licensed.
Swift cache-cleanercleanmymaccleanupdisk-cleanerdisk-spacehomebrewmac-utilitymacosmacos-appmacos-cleanermacosxnativeossosxprivacyswiftswiftuisystem-cleanerxcode-cleaner
import ArgumentParser
import Foundation
struct Clean: ParsableCommand {
static let configuration = CommandConfiguration(
abstract: "Scan and remove developer caches, system junk, AI-tool junk, and Trash.",
discussion: """
With no category, scans all of: dev, junk, ai, trash.
puremac clean Scan everything, review, confirm
puremac clean dev Package-manager & build-tool caches only
puremac clean junk User logs & Xcode-generated junk only
puremac clean ai AI-tool caches & logs only
puremac clean trash Empty user + mounted-volume Trash
Interactive review starts with every item unselected. Finishing the selector only opens an exact deletion review; a separate confirmation defaults to No. --plain uses a numbered selector with ranges, all, and none. --force removes the scanner's standard preselection without either prompt. --dry-run and --json never delete or open a selector.
"""
)
@Argument(help: "Category to clean: dev | junk | ai | trash. Omit to clean all.")
var category: String?
@Flag(name: .long, help: "Remove the scanner's standard preselection without review or confirmation.")
var force = false
@Flag(name: .customLong("dry-run"), help: "Scan and report only; never delete.")
var dryRun = false
@Flag(name: .long, help: "Emit machine-readable JSON and exit (never deletes).")
var json = false
@Flag(name: .long, help: "Use a numbered line-based selector instead of the fullscreen review.")
var plain = false
static let validIDs = ["dev", "junk", "ai", "trash"]
func validate() throws {
if let c = category, !Clean.validIDs.contains(c) {
throw ValidationError("Unknown category '\(c)'. Use one of: \(Clean.validIDs.joined(separator: ", ")).")
}
}
func run() throws {
let mode = CleanupCommandPolicy.mode(
force: force,
dryRun: dryRun,
json: json,
plain: plain
)
guard mode != .unavailable else {
throw ValidationError("Interactive review requires a terminal. Re-run with --force to remove the preselected items, or use --dry-run or --json for a read-only report.")
}
let ids = category.map { [$0] } ?? Clean.validIDs
let ignore = try IgnoreStore(fileURL: AppPaths.ignoreFile)
if !json {
Term.err(Term.dim("Scanning " + ids.map(Clean.title).joined(separator: ", ") + " …"))
}
let cats = ids.map { id in
CategoryScanner.scan(categoryID: id, title: Clean.title(id), ignore: ignore)
}.filter { !$0.groups.isEmpty }
if json {
print(try JSONReport.string(cats))
return
}
if cats.isEmpty {
print(Term.green("No cleanup candidates found in readable locations."))
return
}
if dryRun {
Render.scanResults(cats)
Render.selectionLine(cats)
let selected = cats.flatMap { $0.selectedItems }
let out = Cleaner.remove(selected, ignore: ignore, dryRun: true)
Render.cleanupSummary(out, dryRun: true)
return
}
let reviewed: [CategoryScan]
switch mode {
case .forced:
reviewed = cats
Render.scanResults(cats)
Render.selectionLine(cats)
case .fullscreen:
guard let selection = try InteractiveReview.select(cats, title: "Choose items to clean") else {
print(Term.dim("Cancelled. Nothing removed."))
return
}
reviewed = selection
case .plain:
guard let selection = try PlainSelectionReview.select(cats, title: "Choose items to clean") else {
print(Term.dim("Cancelled. Nothing removed."))
return
}
reviewed = selection
case .reportOnly, .unavailable:
return
}
let selected = reviewed.flatMap { $0.selectedItems }
if selected.isEmpty {
print(Term.dim("No items selected. Nothing removed."))
return
}
if mode != .forced {
Render.deletionReview(reviewed)
let total = ByteCount.human(selected.reduce(Int64(0)) { $0 + $1.sizeBytes })
guard Term.confirm("Remove \(selected.count) items (\(total))?", default: false) else {
print(Term.dim("Cancelled. Nothing removed."))
return
}
}
let out = Cleaner.remove(selected, ignore: ignore, dryRun: false)
Render.cleanupSummary(out, dryRun: false)
if out.hadFailures { throw ExitCode.failure }
}
static func title(_ id: String) -> String {
Catalog.categoryTitles.first { $0.id == id }?.title ?? id.capitalized
}
}
enum CleanupCommandMode: Equatable {
case reportOnly
case forced
case fullscreen
case plain
case unavailable
}
enum CleanupCommandPolicy {
static func mode(
force: Bool,
dryRun: Bool,
json: Bool,
plain: Bool,
terminalSupported: Bool = TerminalSession.isSupported,
inputIsTTY: Bool = isatty(fileno(stdin)) == 1 && isatty(fileno(stdout)) == 1
) -> CleanupCommandMode {
if dryRun || json { return .reportOnly }
if force { return .forced }
guard inputIsTTY else { return .unavailable }
return plain || !terminalSupported ? .plain : .fullscreen
}
}
enum PlainSelectionReview {
static func select(_ categories: [CategoryScan], title: String) throws -> [CategoryScan]? {
print("")
print(Term.bold(Term.sanitize(title)))
print(Term.dim("All items start unselected. Enter numbers, ranges, all, none, or q to cancel."))
var number = 1
for category in categories {
print("")
print(" " + Term.cyan(Term.sanitize(category.title)))
for group in category.groups {
for item in group.items {
print(" \(number). \(Render.sizeCol(item.sizeBytes)) \(Render.pad(Term.sanitize(group.tool), 20)) \(Term.sanitize(item.path))")
number += 1
}
}
}
while true {
print("\nSelect items: ", terminator: "")
guard let line = readLine() else { return nil }
let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)
if ["q", "quit", "cancel"].contains(trimmed.lowercased()) { return nil }
do {
let indices = try parseSelection(trimmed, itemCount: number - 1)
return applyingSelection(indices, to: categories)
} catch {
Term.err(Term.red(Term.sanitize(error.localizedDescription)))
}
}
}
static func parseSelection(_ input: String, itemCount: Int) throws -> Set<Int> {
let trimmed = input.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
if trimmed.isEmpty || trimmed == "none" { return [] }
if trimmed == "all" { return itemCount > 0 ? Set(1...itemCount) : [] }
let parts = trimmed.replacingOccurrences(of: ",", with: " ")
.split(whereSeparator: { $0.isWhitespace })
var selected = Set<Int>()
for partValue in parts {
let part = String(partValue)
if part.contains("-") {
let bounds = part.split(separator: "-", omittingEmptySubsequences: false)
guard bounds.count == 2,
let lower = Int(bounds[0]),
let upper = Int(bounds[1]),
lower <= upper,
lower >= 1,
upper <= itemCount
else { throw ValidationError("Invalid selection '\(part)'.") }
selected.formUnion(lower...upper)
} else {
guard let index = Int(part), index >= 1, index <= itemCount else {
throw ValidationError("Invalid selection '\(part)'.")
}
selected.insert(index)
}
}
return selected
}
static func applyingSelection(_ selected: Set<Int>, to categories: [CategoryScan]) -> [CategoryScan] {
var result = categories
var number = 1
for categoryIndex in result.indices {
for groupIndex in result[categoryIndex].groups.indices {
for itemIndex in result[categoryIndex].groups[groupIndex].items.indices {
result[categoryIndex].groups[groupIndex].items[itemIndex].selected = selected.contains(number)
number += 1
}
}
}
return result
}
}
enum JSONReport {
static func string(_ cats: [CategoryScan]) throws -> String {
struct Out: Encodable {
struct Cat: Encodable { let id, title: String; let totalBytes, selectedBytes: Int64; let groups: [ToolGroup] }
let totalBytes: Int64
let categories: [Cat]
}
let out = Out(
totalBytes: cats.reduce(0) { $0 + $1.allBytes },
categories: cats.map { Out.Cat(id: $0.id, title: $0.title, totalBytes: $0.allBytes, selectedBytes: $0.totalBytes, groups: $0.groups) }
)
let enc = JSONEncoder()
enc.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]
enc.dateEncodingStrategy = .iso8601
return String(decoding: try enc.encode(out), as: UTF8.self)
}
}