From 94d335522d56a8b8e9478b85eb920bfed5ed8869 Mon Sep 17 00:00:00 2001 From: Cameron Cooke Date: Fri, 10 Jul 2026 10:04:10 +0100 Subject: [PATCH] docs: Add storage management guide Document the interactive purge flow as the primary cleanup path and explain the workspace-scoped storage tradeoff for parallel agents and worktrees. Include scriptable report, dry-run, and delete examples for advanced use. Co-Authored-By: OpenAI Codex --- app/docs/_content/cli.mdx | 1 + app/docs/_content/index.ts | 2 + app/docs/_content/storage-management.mdx | 152 +++++++++++++++++++++++ app/docs/_data/routes.ts | 9 ++ 4 files changed, 164 insertions(+) create mode 100644 app/docs/_content/storage-management.mdx diff --git a/app/docs/_content/cli.mdx b/app/docs/_content/cli.mdx index 86eefcc..a33c341 100644 --- a/app/docs/_content/cli.mdx +++ b/app/docs/_content/cli.mdx @@ -28,6 +28,7 @@ xcodebuildmcp simulator build --help | `setup` | Interactive wizard to create or update `.xcodebuildmcp/config.yaml`. | | `init` | Install the MCP or CLI agent skill (Claude Code, Cursor, Codex). | | `upgrade` | Self-update the CLI using the package manager it was installed with. | +| `purge` | Report and clean XcodeBuildMCP-managed workspace storage. See [Storage Management](/docs/storage-management). | | `simulator` | Build, install, launch, test, log capture on simulators. | | `device` | Install, launch, test on physical Apple devices. | | `macos` | Build, run, test macOS targets. | diff --git a/app/docs/_content/index.ts b/app/docs/_content/index.ts index 8a0b049..fe0adb0 100644 --- a/app/docs/_content/index.ts +++ b/app/docs/_content/index.ts @@ -5,6 +5,7 @@ import InstallationPage from "./installation.mdx" import SetupPage from "./setup.mdx" import ClientsPage from "./clients.mdx" import CLIPage from "./cli.mdx" +import StorageManagementPage from "./storage-management.mdx" import MCPModePage from "./mcp-mode.mdx" import WorkflowsPage from "./workflows.mdx" import ToolsPage from "./tools.mdx" @@ -42,6 +43,7 @@ export const PAGE_COMPONENTS: Record = { setup: SetupPage, clients: ClientsPage, cli: CLIPage, + "storage-management": StorageManagementPage, "mcp-mode": MCPModePage, workflows: WorkflowsPage, tools: ToolsPage, diff --git a/app/docs/_content/storage-management.mdx b/app/docs/_content/storage-management.mdx new file mode 100644 index 0000000..91cd86b --- /dev/null +++ b/app/docs/_content/storage-management.mdx @@ -0,0 +1,152 @@ +import Link from "next/link" +import { PageHeader } from "../_components/page-header" + + + + + XcodeBuildMCP gives each workspace its own managed storage so parallel agents can safely build and test the same project from different worktrees, branches, or cloned checkouts. This avoids different sessions overwriting each other's DerivedData, result bundles, logs, and temporary runtime state. + + The tradeoff is disk usage. Safer parallel isolation can create multiple copies of build artifacts for the same app, so `xcodebuildmcp purge` exists to help you review and clean that storage deliberately. + + +The normal cleanup path is interactive: + +```shell +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. + + + `xcodebuildmcp purge` does not silently clean DerivedData in the background. Interactive cleanup asks before deleting. Destructive non-interactive cleanup requires `--delete`, explicit `--classes`, and the confirmation phrase shown by `--help`. + + + + XcodeBuildMCP already runs conservative lifecycle cleanup for managed logs and managed result bundles. That automatic sweep is narrow: it protects recent files and active helper processes, and it does not delete DerivedData. Use `xcodebuildmcp purge` when you want visibility, explicit cleanup, or DerivedData cleanup. + + +## 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: + +```shell +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 + +| Storage class | What it contains | Cleanup behavior | +|---------------|------------------|------------------| +| `derivedData` | Xcode build products, indexes, module caches, and intermediates for a workspace | Opt-in only. Select it explicitly. | +| `logs` | XcodeBuildMCP-managed build, daemon, and simulator helper logs | Safe default cleanup target. Recent or active logs are protected. | +| `resultBundles` | Managed `.xcresult` bundles and completion marker files | Safe default cleanup target. Active or incomplete bundles are protected. | +| `stateTransients` | Stale daemon, OSLog, and Xcode IDE bridge temporary state | Cleaned only when it is safe to identify as stale. | + +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. + +```shell +xcodebuildmcp purge --report +``` + +For machine-readable output: + +```shell +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. + +```shell +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: + +```shell +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. + +```shell +xcodebuildmcp purge --delete \ + --scope current \ + --classes logs,resultBundles,stateTransients \ + --confirm delete-xcodebuildmcp-storage +``` + +For DerivedData cleanup, keep the selection explicit: + +```shell +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 + +| Scope | Meaning | +|-------|---------| +| `--scope current` | Current workspace. Best default for manual cleanup. | +| `--scope workspace --workspace-key ` | One explicit workspace key. | +| `--scope family --family ` | All recognized workspaces with the same project basename prefix. | +| `--scope all` | Every recognized workspace on the machine. Use with care. | + +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. + +```yaml +schemaVersion: 1 +sessionDefaults: + derivedDataPath: ./.derivedData +``` + +See Session Defaults for the full config model. diff --git a/app/docs/_data/routes.ts b/app/docs/_data/routes.ts index 71554a4..01864b2 100644 --- a/app/docs/_data/routes.ts +++ b/app/docs/_data/routes.ts @@ -6,6 +6,7 @@ export type DocSlug = | "setup" | "clients" | "cli" + | "storage-management" | "mcp-mode" | "workflows" | "tools" @@ -78,6 +79,7 @@ export const PAGES_ORDER: DocSlug[] = [ "migration-v2", "privacy", "troubleshooting", + "storage-management", "changelog", "contributing", "architecture", @@ -128,6 +130,12 @@ export const PAGE_META: Record = { group: "Usage", description: "Direct terminal access to every XcodeBuildMCP tool.", }, + "storage-management": { + slug: "storage-management", + title: "Storage Management", + group: "Guides", + description: "Review and clean XcodeBuildMCP-managed workspace storage.", + }, "mcp-mode": { slug: "mcp-mode", title: "MCP Server Mode", @@ -356,6 +364,7 @@ export const SIDEBAR_GROUPS: SidebarGroup[] = [ { slug: "migration-v2" }, { slug: "privacy" }, { slug: "troubleshooting" }, + { slug: "storage-management" }, { slug: "changelog" }, ], },