> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowdeck.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Disk Cleanup

> Reclaim disk space used by FlowDeck, Xcode, and the Simulator from a dedicated window

FlowDeck is one of the heaviest disk consumers on a developer's machine. **Tools → Disk Cleanup** shows where that space went, with a plain-language reason for every item, and lets you reclaim exactly what you select.

## Open Disk Cleanup

Go to **Tools → Disk Cleanup**, or search "Disk Cleanup" in Open Quickly (**⌘K**). This opens a dedicated scan-and-select window, the same shape as **Simulators & Runtimes**.

Nothing scans, warns, or deletes until you open this window and ask. There is no background scanning or scheduled pruning.

## What it scans

Disk Cleanup groups everything it finds into ten categories:

* **Orphaned build data** — FlowDeck's own DerivedData for projects that no longer exist.
* **Sessions & attachments** — chat history and attachments for worktrees that were deleted, plus data left behind by older builds of FlowDeck.
* **FlowDeck logs** — rotated log segments older than 30 days.
* **Worktrees** — agent worktrees whose branch is merged and whose working copy is clean.
* **Xcode DerivedData** — build output for workspaces that no longer exist.
* **Documentation Cache** — superseded Xcode documentation cache versions.
* **Developer downloads & caches** — simulator/platform downloads and the Swift Package Manager cache.
* **Device Support symbols** — superseded per-OS-build debug symbols.
* **Archives & installers** — superseded, non-distributed `.xcarchive` builds and Xcode installers already installed.
* **Simulators & Runtimes** — simulators unused for 90+ days and runtimes no longer needed.

## Selecting what to reclaim

Every row shows a size and a reason, e.g. "Built for MyApp, which no longer exists." Rows are grouped by category in the sidebar, which also shows the size found so far.

Only regenerable items — things that rebuild automatically the next time they're needed — are ticked by default. Destructive items (worktrees, Device Support, simulators) and items that need a second look (archives, installers) always start unticked, so nothing you can't get back is ever preselected.

Click **Reclaim** to review a summary of what you selected, grouped by risk, before anything happens.

## Where reclaimed space goes

Everything that can go to the Trash does — it stays recoverable until you empty it. Two categories can't be trashed and are labelled **Permanent** in the window:

* **Simulators and runtimes** are removed through the same path as `flowdeck simulator delete`, since there's no supported way to move a CoreSimulator device to the Trash.
* **Worktrees** are removed through git directly, so the branch itself always survives — only the working copy on disk is removed, and only after Disk Cleanup has confirmed it's merged, pushed, and has no uncommitted changes.

The header shows both the total size of everything found and the volume's free space; because of how APFS clones and snapshots share storage, reclaiming a given amount of candidate size doesn't always free that same amount of real disk space. After a reclaim, Disk Cleanup reports the actual measured free-space change alongside the summed candidate size.

## Safety

Disk Cleanup re-checks every item immediately before deleting it — if a file changed size, was already deleted, or its worktree is now in active use (open in FlowDeck, or has a live agent session, build, or test), that item is skipped rather than deleted. A skip or a failure on one item never stops the rest of the run.

Disk Cleanup is a window you drive yourself — the AI agent has no access to the scanner or the ability to delete anything through it.