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.

1. If builds are active, audit may continue, but defer all cleanup.
2. 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

1. What must be rebuilt, redownloaded, or permanently lost
2. 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 "" "" \
  --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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AvdLee
• Source: AvdLee/Xcode-Disk-Cleanup-Agent-Skill
• License: MIT

Install and usage instructions live in the source repository linked above.