Documentation

Overview

Roomy runs a two-phase scan: it walks your chosen filesystem root for project artifacts, then checks fixed-path developer system caches (Xcode DerivedData, global npm/pip caches, Homebrew, Docker, and more). Findings are grouped by project root or by system cache category.

• Phase 1 reports progress during project traversal with folders scanned, artifacts found, and recoverable bytes.
• Phase 2 runs when any system-cache category is enabled in Settings, regardless of scan root.
• Results include per-ecosystem byte totals, system cache totals, and project-level artifact lists.
• Project rows are sorted by staleness (months since modification), then by name. System cache groups are pinned at the top of the list.

Scan scope

Default scan locations for project artifacts are controlled by settings:

• Home folder (~/)
• Custom path
• Entire Mac (root path /)

System caches are scanned separately from your project path. When enabled in Settings → System caches, Roomy probes known developer cache locations on your Mac (for example ~/Library/Developer/Xcode/DerivedData or ~/.npm) even if your scan root is a single projects folder.

Detected artifact folders

The scanner matches directories by last path component using built-in rules.

• Node/npm: node_modules, .pnpm-store, .next, .nuxt, .svelte-kit, .turbo, .parcel-cache, dist
• Python: .venv, venv, __pycache__, .mypy_cache, .pytest_cache, .ruff_cache, .tox
• Rust/Java/Swift/Go/Ruby rules include: target, build, .gradle, vendor, Pods, .build

Some folder names are reclassified by project markers. Example: target is treated as Rust when Cargo.toml exists nearby, and as Java when Gradle/Maven files are present.

System caches

Each category below can be toggled in Settings → System caches. Findings appear as pinned groups at the top of the project list.

• Xcode & iOS tooling — DerivedData build caches, iOS Device Support symbols, Xcode Archives, and iOS Simulator data (via simctl).
• Global package caches — npm, pip, yarn, pnpm, NuGet, Poetry, and uv download caches (paths resolved via CLI when available).
• Global CLI packages — globally installed npm and yarn node_modules trees.
• Python / Conda — Conda unused packages and tarballs (conda clean --dry-run), dormant conda environments, pyenv version directories, and pip packages in project venvs not listed in requirements.txt.
• Homebrew — download cache and log directories when Homebrew is installed.
• Docker — unused images, dangling volumes, and build cache (via docker CLI; skipped gracefully if Docker is not running).

The conda base environment is never offered for deletion. Xcode Archives and Docker volumes with data mounts use the highest safety tier.

Safety tiers

System and project artifacts are labeled to guide bulk selection and deletion review:

• Safe — Regenerable caches (DerivedData, package download caches, Homebrew cache). Eligible for bulk dormant selection when tier is safe.
• Review — May affect tooling until reinstalled (global CLI packages, dormant conda envs, Device Support, simulators).
• Irreversible — Cannot be recreated automatically (Xcode Archives, Docker volumes with user data). Never included in bulk dormant selection; extra confirmation in review.

Supported ecosystems and frameworks

This list is based on scanner rules and settings keys currently present in code.

• Node.js / npm: detects node_modules, plus framework/build caches for Next.js (.next), Nuxt (.nuxt), SvelteKit (.svelte-kit), Turborepo (.turbo), and Parcel (.parcel-cache).
• Python: detects virtual env and cache folders including .venv, venv, __pycache__, .mypy_cache, .pytest_cache, .ruff_cache, and .tox.
• Rust: detects target and classifies it as Rust when Cargo.toml is present in the project root.
• Java / Kotlin: detects .gradle and classifies target/build as Java when Maven/Gradle markers are present.
• Swift / Xcode: detects Pods and SwiftPM .build.
• Go / Ruby: detects vendor, classified as Go when go.mod exists, otherwise Ruby.
• .NET / NuGet: global NuGet package store and HTTP caches under system cache scanning.
• General: fallback category for supported artifact names that do not match ecosystem-specific markers.

If a language or framework is not listed above, it is not explicitly recognized by name in the current release.

Activity classification

Project activity uses filesystem modification time, with configurable thresholds.

• Active: modified within the current month
• Recent: 1 month or more, but below inactive threshold
• Inactive: at or above inactive threshold
• Dormant: at or above dormant threshold

Default thresholds in settings are: inactive after 6 months, dormant after 2 years.

Exclusions and patterns

Exclusions support project paths, direct paths, and glob-like patterns.

• Path/project exclusions are normalized to absolute prefixes and applied recursively.
• Pattern exclusions are matched via fnmatch semantics.
• Tilde paths such as ~/work/project are expanded against the current user home directory.

Deletion behavior

Deletion is performed per path on a background thread with per-path failure reporting.

• Filesystem artifacts use Move-to-Trash (FileManager.trashItem) or permanent delete (FileManager.removeItem) depending on settings.
• Docker items are removed via docker rmi, docker volume rm, or docker builder prune — not sent to Trash.
• Conda cleanup uses conda clean and conda env remove subprocesses — not sent to Trash.
• Pip orphan cleanup runs pip uninstall in the scoped virtual environment.
• There is also an optional "empty trash" action implemented via Finder AppleScript (disabled when the selection is Docker-only).

Data persistence

Roomy persists settings, exclusions, and the last scan locally.

• Settings are stored in UserDefaults under a versioned key.
• Exclusions are stored as encoded entries in UserDefaults.
• Last scan summary is persisted in UserDefaults (v2 schema), with large aggregates written to Application Support under com.azbouki.Roomy. Legacy v1 snapshots decode with defaults.

Roadmap (planned)

These are planned improvements not yet shipped.

• Better exclusion glob support (including true recursive ** semantics).
• Improved download distribution flow (universal + architecture-specific guidance).
• Public changelog cadence for each release.
• Deeper pip orphan analysis (import-graph based detection).