---
name: clean-machine-ios-artifacts
description: Audit and safely clean stale local development artifacts on macOS, especially Xcode DerivedData, iOS DeviceSupport, CoreSimulator devices, XCTestDevices, LayerCodexCI/LayerCodexCleanupCI artifacts, SwiftPM/Homebrew/tool caches, and large user folders. Use when Codex is asked to free disk space, inspect iOS/Xcode/Simulator storage, clean old unused artifacts, or repeat the cleanup workflow from this machine.
---

# Clean Machine iOS Artifacts

Use this skill to reclaim disk space without deleting active work. Prefer audit-first, then cleanup only after the user confirms scope unless the request explicitly authorizes deletion.

## Workflow

1. Run an audit:

```bash
bash ~/.codex/skills/clean-machine-ios-artifacts/scripts/audit-clean-ios-artifacts.sh audit
```

2. Explain the biggest candidates and classify them:

- Safe/regenerable: old Xcode `DerivedData`, stale `iOS DeviceSupport`, shutdown Simulator devices, old `XCTestDevices`, CI `deriveddata`, archived CI run logs, package/tool caches.
- Requires confirmation: media folders, Downloads, app removals, Docker data, active CI repos/state/config/secrets.
- Do not delete without explicit approval: running processes' state, secrets, config, active repos/worktrees, booted simulator devices, current-day XCTest device state.

3. If the user approves cleanup, run the script with the matching actions. Prefer `--dry-run` first if the exact scope is not obvious.

```bash
bash ~/.codex/skills/clean-machine-ios-artifacts/scripts/audit-clean-ios-artifacts.sh clean --dry-run --old-days 1
bash ~/.codex/skills/clean-machine-ios-artifacts/scripts/audit-clean-ios-artifacts.sh clean --old-days 1
```

4. Verify with `df -h /` and summarize before/after free space plus any remaining large candidates.

## Cleanup Policy

Default cleanup behavior in the bundled script:

- Delete `~/Library/Developer/Xcode/DerivedData` entries older than `--old-days`.
- Delete `~/Library/Developer/Xcode/iOS DeviceSupport/*`.
- Delete shutdown CoreSimulator devices, never booted devices.
- Delete `~/Library/Developer/XCTestDevices` entries older than `--old-days`.
- Delete Layer CI `deriveddata`, archived run logs, test-poc logs, and nightly-maintenance logs.
- Truncate `LayerCodexCleanupCI` launch logs only; keep active `LayerCodexCI` top-level logs.
- Keep Layer CI scripts, state, config, secrets, repos, and worktrees.

Use `--include-caches` only when the user asks for broader cache cleanup. It removes common regenerable caches such as SwiftPM, Homebrew, Periphery, Playwright, pip, VS Code updater cache, and Google cache.

## Guardrails

- Check active processes before deleting CI folders: `ps aux | grep -E 'LayerCodex|ci_agent|watchdog|testflight_deploy' | grep -v grep`.
- Keep running things. If `LayerCodexCI/ci_agent.py` is active, do not remove its config, state, secrets, scripts, repos, or top-level logs.
- Use `xcrun simctl list devices` to identify booted devices. Do not delete booted simulators.
- Treat `~/Library/Developer/XCTestDevices` current-day entries as active unless the user explicitly says to clear all test device state.
- Do not delete user media, documents, app bundles, Docker data, or project directories without explicit confirmation.