compare-cache-runs
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.
- Installs
- 274
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/tuist/agent-skills --skill compare-cache-runs- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads compare-cache-runs automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Compare Cache Runs
Quick Start
You'll typically receive two cache run identifiers. Follow these steps:
- Run
tuist cache-run list --jsonto find cache runs on each branch. - Run
tuist cache-run show <id> --jsonfor 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
dependencieshash 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 diffbetween 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_argumentsfield 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
FAQ
What does the compare-cache-runs skill do?
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.
How do I install compare-cache-runs?
Run npx skills add https://github.com/tuist/agent-skills --skill compare-cache-runs in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/compare-cache-runs/ (personal) or .claude/skills/compare-cache-runs/ (project).
Which AI agents can use compare-cache-runs?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is compare-cache-runs safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains compare-cache-runs?
It is published by tuist in tuist/agent-skills. It has 274 recorded installs.
More from tuist/agent-skills
using-tuist-generated-projects
tuist/agent-skills
Guides day-to-day work in Tuist-generated Xcode workspaces, including generation, build and test commands, and buildable folders. Use when working in a Tuist-generated project or when users mention tuist generate, xcodebuild test, or generated workspaces.
debug-generated-project
tuist/agent-skills
Debugs issues users encounter with Tuist-generated projects by reproducing the scenario locally, building Tuist from source when needed, and triaging whether it is a bug, misconfiguration, or something that needs team input. Use when users report generation failures, build errors after generation, or unexpected project behavior.
fix-flaky-tests
tuist/agent-skills
Fixes flaky tests by analyzing failure patterns from Tuist test insights, identifying root causes, and applying targeted corrections. Can be invoked with a specific test case URL (e.g. https://tuist.dev/{account}/{project}/tests/test-cases/{id}) or without arguments to discover and fix all flaky tests in the project.
migrating-to-tuist-generated-projects
tuist/agent-skills
Migrates existing Xcode projects to Tuist generated workspaces with build and run validation, external dependency mapping, and migration checklists. Use when adopting Tuist for an existing app or converting a hand-edited Xcode project to generated projects.
compare-builds
tuist/agent-skills
Open the skill to read its SKILL.md instructions.
analyze-selective-testing
tuist/agent-skills
Analyzes Xcode selective testing effectiveness for a test run, showing which test targets were skipped or ran, and diagnosing regressions in test selection. Can compare two test runs to identify what changed.
Popular data & databases skills
supabase-postgres-best-practices
supabase/agent-skills
Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.
prisma-client-api
prisma/skills
Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
prisma-database-setup
prisma/skills
Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.
prisma-cli
prisma/skills
Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.
prisma-postgres
prisma/skills
Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.
prisma-driver-adapter-implementation
prisma/skills
Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.