Create polished App Store listing screenshots via agents or API. Add this to your Fastlane CI/CD.

https://tryaqua.app/

Xcode Junk Cleaner CLI

A command-line tool built natively in Swift to reclaim disk space by safely removing caches, build products, and support files generated by Xcode and related Apple developer tools.

The tool is designed to be both agent-friendly (for use by AI coding assistants and automation scripts) and human-friendly (for direct terminal usage).

How do I use this?

You don't need to manually clone or install this repository. As long as you have Swift installed (bundled with Xcode or command-line tools), you can run the utility directly from GitHub using the Swift Package Manager:

swift run --package https://github.com/vkalahas/xcode-junk-cleaner-cli xcode-junk-cleaner-cli [options]

For example, to run an interactive scan and clean:

swift run --package https://github.com/vkalahas/xcode-junk-cleaner-cli xcode-junk-cleaner-cli

Or to automatically clean all 100% safe files without prompts:

swift run --package https://github.com/vkalahas/xcode-junk-cleaner-cli xcode-junk-cleaner-cli --safe

Demo

Why a Native Swift Implementation?

Most Xcode cleaning utilities are simple shell scripts that run blind delete commands. Because this tool is written in native Swift using Apple's Foundation and AppKit libraries, it performs deep, context-aware analysis:

• Orphaned Derived Data Detection: Instead of deleting all build data, the tool reads the info.plist configuration inside each DerivedData subdirectory using PropertyListSerialization. It extracts the WorkspacePath to check if the source project still exists on your system. If the project was deleted or moved, its DerivedData is flagged as orphaned and safely removed.
• Apple Daemon Integration: Rather than manually purging database files under the hood (which can corrupt simulator state), the tool communicates directly with Apple's CoreSimulator daemon. It runs subprocess checks to find and delete only unavailable simulator configurations via xcrun simctl delete unavailable.
• Safe Simulator Reset: When cleaning all simulator devices, instead of executing raw file deletion that can leave simulator daemons in a corrupted state, the tool executes xcrun simctl erase all. This safely factory resets all simulators through CoreSimulator's official management interface, purging internal containers while preserving the simulator list.
• Granular Log Filtering: The tool parses the user's DiagnosticReports folder and cleans only logs matching developer binaries (such as Xcode, swift-frontend, Simulator, and lldb-rpc-server) while leaving system crash logs untouched.
• Active Process Checking: Using macOS AppKit and NSRunningApplication, the tool detects if Xcode or Simulator is active. It prevents lock conflicts or database corruption by warning the user and blocking deletion in automated environments unless bypassed.

Dependency Philosophy (Ultra-Lightweight)

This tool is designed to be as fast as possible to download, compile, and run on demand directly from GitHub. It has an ultra-lightweight dependency stack:

• Zero terminal rendering libraries: All visual rendering (including real-time spinners, dynamic loading progress bars, and table formatting) is implemented directly in native Swift using standard terminal ANSI codes.
• Single external dependency: The project depends solely on Apple's standard swift-argument-parser library for command-line options parsing.

This ensures that running swift run --package ... compiles in seconds and does not clutter your build caches with third-party frameworks.

Clean Options and Safety Groups

The tool divides directories into two categories to prevent unintended configuration or data loss.

Group A: 100% Safe (No configuration or history loss)

Caches, logs, and temporary files that Apple developer tools regenerate automatically on demand.

• Derived Data (Build intermediates and index databases)
• Orphaned Derived Data (Caches of deleted projects)
• Caches (Xcode caches, Interface Builder render caches, simulator temp logs, Transporter caches)
• SwiftUI Previews Cache (SwiftUI canvas preview cache and assets)
• SwiftUI Preview Simulators (Simulator devices created specifically for SwiftUI Previews)
• Clogs and logs (Transporter logs, CoreSimulator console logs, device diagnostic logs)
• Diagnostic Reports (Crash logs matching Xcode and compiler tools)
• Platform DeviceSupport (iOS, watchOS, tvOS, visionOS/xrOS debugging symbols)
• Legacy DocSets (Older downloaded documentation archives)

Group B: State Resets (Requires user caution)

Files that are safe to delete but will cause minor configuration resets or require re-downloading assets.

• Archives (Past app release builds; needed if you plan to symbolicate crash logs from older App Store versions)
• Simulator Devices (Deletes virtual device container folders, resetting settings and clearing simulator app databases)
• User Simulator Runtimes (Deletes downloaded OS runtime packages; you will need to re-download iOS or watchOS SDKs inside Xcode to test on these platforms again)
• CocoaPods Master Specs Repo (Deletes the local Spec git clone; CocoaPods will re-clone the repository on the next pod resolution)

Usage

Run the tool from the root directory using the Swift Package Manager.

Interactive Mode (Default)

Runs a full scan, outputs a formatted table of directory sizes, and guides you through each directory with individual prompt confirmations.

swift run xcode-junk-cleaner-cli

Options

• -s, --safe: Automatically clean only 100% safe directories (Group A) without prompts.
• -y, --yes: Automatically clean all directories (Group A and Group B) without prompts.
• -d, --dry-run: Scan files and output sizes, but do not delete any directories.
• --json: Output results in structured JSON format.
• -q, --quiet: Silence all standard logging output.
• -c, --category <id>: Target a specific category to scan or clean (comma-separated list of IDs, or repeat the option).
• -o, --older-than <days>: Filters directories, scanning and deleting only folders that have not been modified in the specified number of days.
• -t, --threshold <size>: Triggers a threshold warning and exits with exit code 3 if the total scanned junk exceeds the specified size limit (e.g. 5GB, 500MB).
• -f, --force: Bypasses the active Xcode process check.
• -h, --help: Show help information.

Example for automated safe cleaning:

swift run xcode-junk-cleaner-cli --safe

Example for a dry run preview:

swift run xcode-junk-cleaner-cli --dry-run

Agent and Automation Integration

The CLI is designed for integration into scripts and AI coding agents (such as Claude Code, Codex, or OpenClaw).

Automatic Non-Interactive Fallback

The tool automatically checks if standard input is a terminal (TTY). If standard input is redirected or piped, the tool disables interactive prompts. In this mode:

• The tool will only scan and output status unless --safe or --yes is explicitly provided.
• If deletions are requested without safe/yes flags, the tool exits with exit code 2.

Structured Outputs

Using the --json flag formats both scan results and deletion logs into pretty-printed JSON, silencing standard human-readable logging.

Example JSON scan command:

swift run xcode-junk-cleaner-cli --dry-run --json

Example JSON clean command targeting a specific folder:

swift run xcode-junk-cleaner-cli --safe --json -c spmCaches

Exit Codes

• 0: Success (action completed or system clean).
• 1: General error or invalid arguments.
• 2: Non-interactive safety violation (trying to delete without explicit automated flags).
• 3: Disk space threshold exceeded (the total scanned junk exceeds the specified --threshold limit).
• 4: Active Xcode process check failed (Xcode is running and --force was not provided).