# Xcode Disk Cleanup

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-avdlee-xcode-disk-cleanup-agent-skill-xcode-disk-cleanup`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AvdLee](https://agentstack.voostack.com/s/avdlee)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AvdLee](https://github.com/AvdLee)
- **Source:** https://github.com/AvdLee/Xcode-Disk-Cleanup-Agent-Skill/tree/main/xcode-disk-cleanup

## Install

```sh
agentstack add skill-avdlee-xcode-disk-cleanup-agent-skill-xcode-disk-cleanup
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
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:

```bash
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:

```text
--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](https://github.com/AvdLee)
- **Source:** [AvdLee/Xcode-Disk-Cleanup-Agent-Skill](https://github.com/AvdLee/Xcode-Disk-Cleanup-Agent-Skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-avdlee-xcode-disk-cleanup-agent-skill-xcode-disk-cleanup
- Seller: https://agentstack.voostack.com/s/avdlee
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.