compare-cache-runs

name	compare-cache-runs
description	Compares two `tuist cache` runs to identify cache hit rate changes and root-cause analysis of cache invalidation. Can be invoked with cache run IDs, dashboard URLs, or branch names.

Compare Cache Runs

Quick Start

You'll typically receive two cache run identifiers. Follow these steps:

1. Run tuist cache-run list --json to find cache runs on each branch.
2. Run tuist cache-run show <id> --json for both base and head cache runs.
3. Compare duration, status, and cache hit rates.
4. Summarize cache changes with root cause analysis.

Step 1: Resolve Cache Runs

If base/head are cache run IDs or dashboard URLs

Fetch each directly:

tuist cache-run show <base-id> --json
tuist cache-run show <head-id> --json

If base/head are branch names

List recent cache runs on each branch:

tuist cache-run list --git-branch <base-branch> --json --page-size 1
tuist cache-run list --git-branch <head-branch> --json --page-size 1

Then fetch full details with tuist cache-run show <id> --json.

Defaults

• If no base is provided, use the project's default branch (usually main).
• If no head is provided, detect the current git branch.

Step 2: Compare Top-Level Metrics

After fetching both cache runs, compare:

Metric	What to check
duration	Flag if head is >10% slower
status	Flag if base succeeded but head failed
cacheable_targets	Note if target count changed
local_cache_target_hits	Compare local hit counts
remote_cache_target_hits	Compare remote hit counts
is_ci	Note if one is CI and the other local

Compute cache hit rates:

• Base: (local_hits + remote_hits) / cacheable_targets * 100
• Head: same formula
• Delta: head_rate - base_rate

Step 3: Analyze Cache Invalidation

If cache hit rate dropped, the key question is: which target(s) caused the invalidation cascade?

Cache invalidation in tuist cache works the same way as in tuist generate:

1. A "root cause" target has a direct change (source file modified, build setting changed, etc.)
2. All targets that depend on the root cause target also get invalidated because their dependencies hash changes.
3. This cascade can invalidate many targets from a single root change.

Identifying root cause targets

Without the module cache target detail endpoint (available via MCP), use these heuristics:

1. Check git diff between the base and head commits to see which files changed.
2. Map changed files to their Tuist targets/modules.
3. Targets with direct source changes are likely root causes.
4. Targets that only changed due to dependency hash cascading are secondary invalidations.

Common root causes of cache invalidation

Cause	Description
Source changes	Files in the target's source directory were modified
Resource changes	Assets, XIBs, storyboards, or other resources changed
Build settings	Target or project build settings were modified
Dependency changes	An external dependency version changed
Info.plist changes	The target's Info.plist was modified
Entitlements changes	The entitlements file was modified
Deployment target	The minimum deployment target changed
Headers	Public or project headers changed
Project settings	Shared project-level settings changed

Step 4: Assess Impact

Categorize the cache invalidation:

• Expected: Source files were intentionally changed, causing expected cache misses.
• Unexpected: No source changes but cache was invalidated (build settings, Xcode version, etc.).
• Cascade: A small change invalidated many downstream targets.

For tuist cache specifically, also consider:

• Cache warming strategy: Was the cache run warming from scratch or incrementally?
• The command_arguments field can reveal if different flags were used.

Summary Format

Produce a summary with:

1. Overall verdict: Cache hit rate improved, regressed, or stable.
2. Cache hit rate: Base rate vs head rate with delta.
3. Duration: Absolute and percentage change.
4. Root cause targets: Which targets had direct changes.
5. Cascade impact: How many targets were invalidated due to dependency cascading.
6. Recommendations: How to minimize cache invalidation.

Example:

Cache Run Comparison: base (run-123 on main) vs head (run-456 on feature-x)

Duration: 95.2s -> 142.8s (+50%) -- REGRESSION
Cache hit rate: 88% (44/50) -> 60% (30/50) (-28%) -- REGRESSION
Status: success -> success

Root cause: CoreModule had source changes (5 files modified).
This cascaded to 14 downstream targets that depend on CoreModule.

Cache invalidation breakdown:
- Direct changes: CoreModule (sources changed)
- Cascade: UIKit, Networking, Analytics, + 11 others (dependency hash changed)

Recommendations:
- Consider splitting CoreModule into smaller, more focused modules
- Use interface/implementation module pattern for frequently-changed modules
- Run `tuist cache` on the feature branch after rebasing to warm caches

Done Checklist

• Resolved both base and head cache runs
• Compared duration and cache hit rates
• Identified root cause targets for cache invalidation
• Analyzed cascade impact
• Provided actionable recommendations for reducing cache misses