| 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:
- Run
tuist cache-run list --json to find cache runs on each branch.
- Run
tuist cache-run show <id> --json for both base and head cache runs.
- Compare duration, status, and cache hit rates.
- 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:
- A "root cause" target has a direct change (source file modified, build setting changed, etc.)
- All targets that depend on the root cause target also get invalidated because their
dependencies hash changes.
- 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:
- Check
git diff between the base and head commits to see which files changed.
- Map changed files to their Tuist targets/modules.
- Targets with direct source changes are likely root causes.
- 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:
- Overall verdict: Cache hit rate improved, regressed, or stable.
- Cache hit rate: Base rate vs head rate with delta.
- Duration: Absolute and percentage change.
- Root cause targets: Which targets had direct changes.
- Cascade impact: How many targets were invalidated due to dependency cascading.
- 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
