xcode-disk-cleanup

Xcode Disk Cleanup

Safety contract

• Treat every cleanup request as permission to audit, not permission to delete.
• Never mutate storage before presenting exact candidate IDs, paths or simulator identifiers, measured sizes, risks, and regeneration costs.
• Ask the user to approve specific IDs. Broad replies such as “clean Xcode” or “delete everything” are not itemized approval.
• Default ordinary files and directories to Trash. Explain that space is not reclaimed until Trash is emptied, and request separate approval before doing so.
• Revalidate identity and running-process usage immediately before mutation.
• Never use wildcards, unbounded rm -rf, sudo, SIP changes, or manual deletion inside system-managed CoreSimulator and MobileAsset directories.
• Preserve archives and dSYMs unless the user proves the exact distributed build is backed up elsewhere and separately approves deletion.
• Never delete Package.resolved, signing assets, credentials, custom DocSets, the active Xcode, a running simulator, or an Xcode that uniquely provides a required SDK/toolchain.
• Report summed candidate sizes separately from actual APFS space recovered.

Read references/safety-model.md before applying cleanup.

Workflow

1. Preflight

1. Confirm the host is macOS and the bundled script is available.
2. Check for active Xcode, Simulator, xcodebuild, Swift build, test, archive, and package-resolution processes.
3. If builds are active, audit may continue, but defer all cleanup.
4. Determine optional source roots for project-local .build and .derived-data scanning. Do not crawl the whole home directory.

2. Run the read-only audit

python3 "${SKILL_DIR}/scripts/xcode_disk_cleanup.py" audit \
  --output-dir .xcode-disk-cleanup-audit \
  [--scan-root /path/to/projects]

Read both generated files:

• .xcode-disk-cleanup-audit/report.md
• .xcode-disk-cleanup-audit/audit.json

The script audits DerivedData, documentation caches, CocoaPods caches, simulator devices and runtimes (including stale superseded beta runtimes), orphan runtime volumes, simulator dyld caches, Xcode-managed components, Xcode installers, installed Xcodes, archives (including never-distributed orphans), DeviceSupport for every platform, diagnostic logs, XCTest device clones, legacy DocSets, and explicitly requested project roots.

Shared compiler caches (ModuleCache.noindex, precompiled SDK modules) and the global SwiftPM download cache are deliberately out of scope: they are always in use on an active development machine, and clearing them trades real build-time pain for little lasting space. Do not propose them.

3. Validate and enrich findings

Use the category router:

Finding	Reference
DerivedData, module caches, project .build, CocoaPods	references/generated-data.md
Simulator devices, runtimes, dyld caches, XCTest clones	references/simulators.md
Archives, dSYMs, DeviceSupport, logs, DocSets	references/release-artifacts.md
Xcode DMGs/XIPs and installed Xcodes	references/xcode-installations.md
Confirmation and deletion behavior	references/safety-model.md

Do not mechanically accept a scanner classification. Verify uncertain ownership, custom paths, backups, and toolchain requirements.

4. Present the proposal

Sort by recoverable GiB and show:

1. Candidate ID
2. Category and exact path/identifier
3. Recoverable GiB
4. Risk: regenerable, destructive, or preserve
5. Evidence — a short "why this is stale" phrase (age in days, superseded-by, missing workspace), not just a classification label
6. What must be rebuilt, redownloaded, or permanently lost
7. Proposed action

Keep the proposal scannable:

• Render folder candidates as clickable file:// links so the user can inspect them before approving.
• Hide individual items below roughly 0.5 GiB; the full itemized list stays in report.md for reference. Do not pad the proposal with a "small items" bucket — it adds questions, not signal.
• Group unavailable simulators into a table per runtime.
• Give every category its own subheading with its total size, even small ones like documentation caches or orphan archives. A category summarized in a trailing paragraph under another category's table gets overlooked, and overlooked items cannot be meaningfully approved.

Include:

• Total candidate GiB by risk
• Current free disk space
• A warning that APFS cloning and snapshots make candidate sizes non-additive
• A direct request for approval of exact IDs

5. Apply only approved IDs

Invoke apply only after the user explicitly approves the exact IDs shown in the current audit:

python3 "${SKILL_DIR}/scripts/xcode_disk_cleanup.py" apply \
  --audit-file .xcode-disk-cleanup-audit/audit.json \
  --ids "<approved-id-1>" "<approved-id-2>" \
  --confirm I_APPROVED_THE_SELECTED_ITEMS \
  --output .xcode-disk-cleanup-audit/cleanup-result.json

Simulator device and runtime deletions are irreversible and require a second approval plus:

--confirm-irreversible I_APPROVED_IRREVERSIBLE_SIMULATOR_DELETION

A stale runtime is only proposed when simctl reports it deletable, no installed Xcode SDK resolves to its build, and a newer runtime supersedes it on the same platform. This is the pattern behind leftover beta platforms in Xcode Settings → Components after installing a newer Xcode beta.

Do not pass either confirmation phrase unless the corresponding user approval is present in the conversation.

6. Verify

1. Re-run the audit.
2. Compare df free space before and after.
3. Distinguish “moved to Trash” from immediately reclaimed space.
4. Confirm protected and unapproved candidates remain.
5. Report successes, failures, and deferred items.

Xcode installer and application rules

• Search .xip, .dmg, and .zip installers through Spotlight and common download folders.
• Suggest an installer only when its parsed version matches an installed Xcode; otherwise report it as uncertain.
• An older Xcode may only be suggested, never automatically selected, when it is not active/running and a newer same-channel installation exists.
• Spotlight kMDItemLastUsedDate reflects LaunchServices opens, not command-line use. Combine it with xcode-select, DEVELOPER_DIR, running processes, .xcode-version, CI scripts, and unique SDK/toolchain evidence.
• Never infer that a stable Xcode supersedes a beta, or vice versa.

Output quality checklist

• Audit completed without mutation
• Every item has an exact size and stable ID
• Candidate and actual recovered space are separate
• Archives/dSYMs are preserve-by-default
• Active processes and selected Xcode are protected
• User approved exact IDs
• Irreversible operations received separate approval
• Post-cleanup audit confirms only approved items changed