[!CAUTION]
Derived permanently deletes selected developer data instead of moving it to the Trash. Review the cleanup plan before confirming deletion.
Overview
Derived finds and removes storage created by Xcode, Simulator, and XCTest. It reports verified reclaimable space, keeps APFS clone sizes separate, and protects active or high-risk targets.
Use Derived through the macOS app, the CLI, or the local server. All three interfaces use the same scanner, path validation, and cleanup workflow. Derived runs locally and does not collect analytics.
Inspect and safely clean local Xcode, Simulator, and XCTest storage.
2026-11-09
스타
—
도구
—
가동 시간
—
derived
derived-mcp
Interface
Intended use
macOS app
Interactive scans, cleanup selection, scheduling, and history
CLI
Terminal workflows, shell scripts, and structured JSON output
MCP server
Structured access for Codex, Claude Code, Cursor, and other MCP clients
Install the macOS app
Homebrew (recommended)
brew tap adiaz0511/derived
brew trust adiaz0511/derived
brew install --cask derived
The trust command is required once for the third-party tap.
derived integrations install detects Codex, Claude Code, and Cursor on the Mac. It registers the MCP server and installs the skill for each detected client.
Update the tools and refresh their integrations with:
derived integrations update
The CLI checks for new versions at most once per day during interactive commands. Update notices never appear in JSON or MCP output.
Disk image
The latest Derived DMG also includes Derived Agent Tools for installation without Homebrew.
Open the DMG.
Open Derived Agent Tools.
Select Install for Codex.
Restart Codex.
When the app and DMG-installed tools are both present, Derived offers to update the tools after an app update. Without the app, download the latest DMG and run Derived Agent Tools again.
MCPB installation
Clients that support MCPB bundles can install Derived-MCP-VERSION-macOS-universal.mcpb from the latest release. The MCPB contains the MCP server, but it does not install the derived CLI or portable skill.
Use Derived with coding agents
Check which clients are configured:
derived --version
derived integrations status
Then start a new session in Codex, Claude Code, or Cursor and ask:
Use $derived-cleanup to scan my developer storage.
See Agent Integrations for client-specific commands, manual configuration, and uninstallation.
Use the CLI
The CLI provides aligned tables for interactive use and JSON for scripts and agents.
Command
Purpose
derived scan
Scan Xcode, Simulator, and XCTest storage and print a scan ID
derived list
List candidates from one category in a previous scan
derived prepare
Create an expiring cleanup plan for selected items or categories
derived delete
Execute a prepared plan with its exact confirmation phrase
derived integrations install
Configure the MCP server and skill for supported coding agents
derived integrations status
Report installed agent integrations
derived integrations update
Update Homebrew-managed tools and refresh their integrations
Start with a scan:
derived --version
derived scan
Use the scan ID printed by derived scan to inspect a category and prepare a plan:
Replace SCAN_ID with the UUID printed by the scan. Do not include angle brackets. The prepare command prints the exact confirmation phrase and complete derived delete command for that plan.
Use --json when another program will consume the output:
Reports verified reclaimable bytes separately from logical APFS clone sizes.
Groups cleanup candidates by category and recommendation status.
Cleanup and automation
Cleans individual candidates, complete categories, or cross-category selections.
Uses simctl to remove simulator devices and runtimes through supported system operations.
Schedules cleanup for Derived Data, Xcode logs, and Xcode caches.
Supports Launch at Login and maintains a local JSON Lines cleanup history.
Safety
Detects active development tools and protects active targets.
Requires an expiring cleanup plan and exact confirmation before deletion.
Revalidates every candidate immediately before cleanup.
Never selects archives or simulator runtimes automatically.
Safety model
Derived validates every cleanup target against a fixed allowlist. It rejects category roots, paths outside approved developer directories, malformed simulator identifiers, active targets, symbolic-link escapes, and candidates that changed after the plan was created.
Automatic cleanup waits until related development tools are closed and fails safely when process inspection is unavailable. XCTest APFS clone sizes are reported as logical sizes and excluded from verified reclaimable totals.
See Safety for the complete deletion model and approved paths.
Requirements
Run Derived
macOS 14.0 or later
Xcode for Simulator discovery and simctl-backed cleanup
The DMG contains prebuilt universal applications and command-line tools. Building from source is not required.
Derived is intentionally not sandboxed because it manages files under ~/Library/Developer and invokes xcrun simctl.
Build from source
Xcode 26.4 or later
Swift 6.2 toolchain
Clone the repository, open Derived.xcodeproj, select the Derived scheme, and build the macOS target.