Storage Management

Use the interactive cleaner to review and remove XcodeBuildMCP-managed workspace storage when isolated build artifacts, logs, result bundles, or temporary state start taking too much disk space.

The normal cleanup path is interactive:

xcodebuildmcp purge

This opens a guided cleaner that shows projects, workspaces, and direct child folders. It keeps the prompt compact, avoids dumping long file lists, and asks for confirmation before deleting anything.

When to use it#

Use the cleaner when:

• your disk is filling up after many builds or test runs;
• you work across many branches, worktrees, or cloned copies of the same app;
• an agent has created lots of per-workspace build state;
• you want to inspect XcodeBuildMCP-managed storage before removing anything.

If you only need regular build, test, launch, or UI automation commands, you do not need this guide.

Interactive cleanup flow#

Run the command with no mode in a TTY:

xcodebuildmcp purge

The flow starts with the biggest projects and lets you drill down:

1. Pick a project group.
2. Pick one workspace, multiple workspaces, or the whole group.
3. Pick folders in one workspace, or delete all folders for selected workspaces.
4. Review the compact deletion summary.
5. Confirm or cancel.

DerivedData is shown as a folder choice, but it remains explicit. The cleaner calls it out before confirmation because deleting DerivedData can reclaim a lot of space but also makes later Xcode builds slower until caches are rebuilt.

What XcodeBuildMCP stores#

The locks directory can appear in reports, but purge does not delete it as a storage class.

Scriptable report mode#

Use report mode when you want details for a script, CI diagnostic, or issue report.

xcodebuildmcp purge --report

For machine-readable output:

xcodebuildmcp purge --report --json

A bare report covers all known workspaces so you can see where space is going. Reports include total usage, workspace usage, family usage, and storage-class usage for the selected scope.

Scriptable dry-run mode#

Dry-run mode builds the deletion plan without removing files.

xcodebuildmcp purge --dry-run --scope current --classes logs,resultBundles,stateTransients

Without an explicit scope, dry-run and delete target the current workspace. This keeps cleanup narrow by default.

To include DerivedData, name it directly:

xcodebuildmcp purge --dry-run --scope current --classes derivedData --older-than 7d

--older-than accepts day values such as 1d, 7d, 14d, or 30d. The age check uses the newest file or directory inside a candidate, so a directory with fresh contents is not selected just because the directory itself looks old.

Scriptable delete mode#

Use non-interactive delete mode only when you already know the scope and classes you want to remove.

xcodebuildmcp purge --delete \
  --scope current \
  --classes logs,resultBundles,stateTransients \
  --confirm delete-xcodebuildmcp-storage

For DerivedData cleanup, keep the selection explicit:

xcodebuildmcp purge --delete \
  --scope current \
  --classes derivedData \
  --older-than 14d \
  --confirm delete-xcodebuildmcp-storage

During deletion, XcodeBuildMCP revalidates every candidate under the workspace filesystem lock. If a path changed since planning, moved outside the expected workspace folder, contains a symbolic link, belongs to an active helper process, or no longer matches the managed artifact pattern, it is skipped instead of deleted.

Scope options#

Unknown workspace keys appear in reports, but broad all and family purge scopes skip them. Use explicit workspace scope if you need to clean one.

Managing DerivedData intentionally#

By default, builds use isolated DerivedData under XcodeBuildMCP-managed workspace storage. This avoids cross-project and cross-worktree build conflicts, especially when multiple agents build at the same time.

If you intentionally want to manage DerivedData elsewhere, set sessionDefaults.derivedDataPath in your project config. That moves Xcode's build products to the path you provide, so you are then responsible for its cleanup policy.

schemaVersion: 1
sessionDefaults:
  derivedDataPath: ./.derivedData

See Session Defaults for the full config model.