{ "markdown": "
\n \"Derived\n

Derived

\n

A native macOS menu-bar application for inspecting and removing storage created by Xcode, Simulator, and XCTest.

\n

\n \"macOS\n \"Swift\n \"CLI\n \"MIT\n

\n
\n\n> [!CAUTION]\n> Derived permanently deletes selected developer data instead of moving it to the Trash. Review the cleanup plan before confirming deletion.\n\n## Overview\n\nDerived 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.\n\nUse Derived through the macOS app, the `derived` CLI, or the local `derived-mcp` server. All three interfaces use the same scanner, path validation, and cleanup workflow. Derived runs locally and does not collect analytics.\n\n| Interface | Intended use |\n|---|---|\n| macOS app | Interactive scans, cleanup selection, scheduling, and history |\n| CLI | Terminal workflows, shell scripts, and structured JSON output |\n| MCP server | Structured access for Codex, Claude Code, Cursor, and other MCP clients |\n\n## Install the macOS app\n\n### Homebrew (recommended)\n\n```sh\nbrew tap adiaz0511/derived\nbrew trust adiaz0511/derived\nbrew install --cask derived\n```\n\nThe trust command is required once for the third-party tap.\n\nUpdate the app with:\n\n```sh\nbrew update\nbrew upgrade --cask derived\n```\n\n### Disk image\n\n1. Download the DMG from the [latest GitHub release](https://github.com/adiaz0511/Derived/releases/latest).\n2. Open the disk image.\n3. Drag `Derived.app` to Applications.\n4. Open Derived from Applications.\n\n## Install the CLI and MCP server\n\nThe agent tools include the `derived` CLI, the `derived-mcp` server, and the `derived-cleanup` skill. The macOS app is not required.\n\n### Homebrew (recommended)\n\n```sh\nbrew tap adiaz0511/derived\nbrew trust adiaz0511/derived\nbrew install --cask derived-tools\nderived integrations install\n```\n\n`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.\n\nUpdate the tools and refresh their integrations with:\n\n```sh\nderived integrations update\n```\n\nThe CLI checks for new versions at most once per day during interactive commands. Update notices never appear in JSON or MCP output.\n\n### Disk image\n\nThe [latest Derived DMG](https://github.com/adiaz0511/Derived/releases/latest) also includes **Derived Agent Tools** for installation without Homebrew.\n\n1. Open the DMG.\n2. Open **Derived Agent Tools**.\n3. Select **Install for Codex**.\n4. Restart Codex.\n\nWhen 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.\n\n### MCPB installation\n\nClients 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.\n\n## Use Derived with coding agents\n\nCheck which clients are configured:\n\n```sh\nderived --version\nderived integrations status\n```\n\nThen start a new session in Codex, Claude Code, or Cursor and ask:\n\n```text\nUse $derived-cleanup to scan my developer storage.\n```\n\nSee [Agent Integrations](docs/AGENT_INTEGRATIONS.md) for client-specific commands, manual configuration, and uninstallation.\n\n## Use the CLI\n\nThe CLI provides aligned tables for interactive use and JSON for scripts and agents.\n\n| Command | Purpose |\n|---|---|\n| `derived scan` | Scan Xcode, Simulator, and XCTest storage and print a scan ID |\n| `derived list` | List candidates from one category in a previous scan |\n| `derived prepare` | Create an expiring cleanup plan for selected items or categories |\n| `derived delete` | Execute a prepared plan with its exact confirmation phrase |\n| `derived integrations install` | Configure the MCP server and skill for supported coding agents |\n| `derived integrations status` | Report installed agent integrations |\n| `derived integrations update` | Update Homebrew-managed tools and refresh their integrations |\n\nStart with a scan:\n\n```sh\nderived --version\nderived scan\n```\n\nUse the scan ID printed by `derived scan` to inspect a category and prepare a plan:\n\n```sh\nderived list --scan SCAN_ID --category derivedData --limit 20\nderived prepare --scan SCAN_ID --category previewData\n```\n\nReplace `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.\n\nUse `--json` when another program will consume the output:\n\n```sh\nderived scan --json\nderived list --scan SCAN_ID --category derivedData --limit 20 --json\n```\n\nScan IDs expire after 30 minutes. Cleanup plans expire after 10 minutes and can be executed once.\n\n## Features\n\n### Storage discovery\n\n- Scans Derived Data, SwiftUI previews, XCTest devices, simulators, runtimes, Device Support, logs, caches, archives, and temporary data.\n- Reports verified reclaimable bytes separately from logical APFS clone sizes.\n- Groups cleanup candidates by category and recommendation status.\n\n### Cleanup and automation\n\n- Cleans individual candidates, complete categories, or cross-category selections.\n- Uses `simctl` to remove simulator devices and runtimes through supported system operations.\n- Schedules cleanup for Derived Data, Xcode logs, and Xcode caches.\n- Supports Launch at Login and maintains a local JSON Lines cleanup history.\n\n### Safety\n\n- Detects active development tools and protects active targets.\n- Requires an expiring cleanup plan and exact confirmation before deletion.\n- Revalidates every candidate immediately before cleanup.\n- Never selects archives or simulator runtimes automatically.\n\n## Safety model\n\nDerived 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.\n\nAutomatic 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.\n\nSee [Safety](docs/SAFETY.md) for the complete deletion model and approved paths.\n\n## Requirements\n\n### Run Derived\n\n- macOS 14.0 or later\n- Xcode for Simulator discovery and `simctl`-backed cleanup\n\nThe DMG contains prebuilt universal applications and command-line tools. Building from source is not required.\n\nDerived is intentionally not sandboxed because it manages files under `~/Library/Developer` and invokes `xcrun simctl`.\n\n### Build from source\n\n- Xcode 26.4 or later\n- Swift 6.2 toolchain\n\nClone the repository, open `Derived.xcodeproj`, select the `Derived` scheme, and build the macOS target.\n\nCommand-line build:\n\n```sh\nxcodebuild \\\n -project Derived.xcodeproj \\\n -scheme Derived \\\n -configuration Debug \\\n -derivedDataPath /tmp/DerivedBuild \\\n CODE_SIGNING_ALLOWED=NO \\\n build\n```\n\nRun the application tests:\n\n```sh\nxcodebuild \\\n -project Derived.xcodeproj \\\n -scheme Derived \\\n -configuration Debug \\\n -destination 'platform=macOS' \\\n -derivedDataPath /tmp/DerivedTests \\\n CODE_SIGNING_ALLOWED=NO \\\n test\n```\n\nBuild and test the CLI and MCP server:\n\n```sh\nswift test\nscripts/test-agent-protocol.sh\nswift build -c release\n```\n\nLaunch at Login requires a signed application installed in a stable location. It may not work from an unsigned development build.\n\n## Project structure\n\n- `Derived/App`: application lifecycle, menu-bar item, and panel management\n- `Derived/Features`: SwiftUI presentation grouped by feature\n- `Derived/Models`: cleanup, scan, automation, and reporting models\n- `Derived/Services`: scanning, validation, process inspection, deletion, and persistence\n- `Derived/Shared`: shared formatting and design constants\n- `Derived/AgentIntegration`: shared CLI and MCP models, state, and safety workflow\n- `DerivedTests`: safety and behavior tests\n- `DerivedCLITests`: CLI argument, version, and human-readable output tests\n- `DerivedCoreTests`: agent integration and destructive-operation safeguards\n- `Tools`: native CLI and MCP executables\n- `Integrations`: portable agent skills and packaging metadata\n\n## Privacy\n\nDerived operates locally. It does not include analytics, advertising, accounts, or network services. See [Privacy](PRIVACY.md).\n\n## Contributing\n\nContributions are welcome. Read [Contributing](CONTRIBUTING.md) before changing scanner, validation, or deletion behavior.\n\nMaintainers should follow [Releasing Derived](docs/RELEASING.md) for signing, notarization, DMG generation, and MCP publication.\n\n## License\n\nDerived is available under the [MIT License](LICENSE).\n", "bytes": 9285, "sha": "2ff0ce2c7c045f6e3da7090737bb3e8e6f398649103b0063683a530adaad99d1", "repo_slug": "adiaz0511/derived", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_adiaz0511_derived_abdd21d2/readme" }