Cachemiss

cachemiss

The cache was supposed to make CI fast, so why did that run miss? cachemiss takes the cache key template exactly as it appears in your workflow, together with what actually happened on each run, and works out which misses were inevitable and which ones nobody can explain:

• Hashed inputs — the glob patterns pulled out of the template's hashFiles('...') / hashFiles("...") segments, in order of appearance, duplicates removed
• Outcome counts — how many runs hit exactly, fell back to a restore key, or missed outright, plus the hit rate (hits over total runs, rounded to four decimal places)
• A cause per non-hit run — a partial run is exact_key_miss_restore_hit; a miss whose changed files touch a hashed input is hashed_input_changed, with the matching files listed; anything else is unexplained_miss
• Cause tallies — counts per cause, most frequent first (ties broken alphabetically), feeding the report's most_common_cause and overall diagnosis; an all-hit history diagnoses as cache_healthy with a null most common cause
• Changed hashed files — the sorted union of every hashed input that changed on a miss run, so you can see at a glance which lockfile or manifest keeps busting the cache

Glob matching follows three rules: a file matches a pattern when it equals the pattern exactly; when a pattern starts with **/, a file matches when it is the remainder of the pattern or ends with / plus that remainder; and a pattern containing * matches segment by segment (splitting on /), where * covers exactly one segment and segment counts must be equal. Matching is case-sensitive.

Everything is computed locally from the inputs you supply: no network, no log scraping, no configuration. Invalid input — an empty key template, a run without an outcome, an outcome outside hit / partial / miss, a non-string changed file — is rejected with an error naming the offending path, and no partial report is produced.

CLI

npx @reneturcios/cachemiss analyze --input args.jsonnpx @reneturcios/cachemiss --version

args.json contains the full arguments object:

{  "key_template": "${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}",  "runs": [    { "run_id": "run-201", "outcome": "hit" },    {      "run_id": "run-202",      "outcome": "miss",      "changed_files": ["apps/web/package-lock.json", "src/index.ts"]    },    { "run_id": "run-203", "outcome": "partial" }  ],  "restore_keys": ["linux-node-"]}

changed_files is optional per run, and restore_keys is optional overall (it is echoed into the report). The report is printed as JSON.

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/cachemiss mcp

MCP client config:

{  "mcpServers": {    "cachemiss": {      "command": "npx",      "args": ["-y", "@reneturcios/cachemiss", "mcp"]    }  }}

Tools

• analyze_cache_miss — Diagnose CI cache misses from a key template and per-run outcomes.

  • key_template (string, required, non-empty) — the cache key as written in the workflow
  • runs (array, required, at least one) — runs as {run_id, outcome, changed_files?} objects, where outcome is one of hit, partial, miss
  • restore_keys (array of strings, optional) — the restore-key prefixes configured in the workflow

  Returns {run_count, hits, partials, misses, hit_rate, hashed_inputs, restore_keys, cause_counts, misses_detail, changed_hashed_files, most_common_cause, diagnosis}.

Docker

docker run -i ghcr.io/cloudcorprecords/cachemissdocker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/cachemiss analyze --input /w/args.json

Development

npm installnpm run build   # tsc -> dist/npm test        # tsx --test test/*.test.ts (pure local, no network)npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios