cache-management

name	cache-management
description	Manage the monorepo-task-runner content-hash cache. Covers how caching works, cache key computation, listing, clearing, and cache-related debugging.

cache-management skill

Use this skill when the user wants to:

• Understand why a task did or did not use the cache
• List or inspect cache entries
• Clear all or specific task caches
• Tune input glob patterns to improve cache hit rate

How caching works

For each task:

1. Collect all files matching the inputs glob patterns (sorted by path)
2. Hash each file: SHA-256(filePath + ":" + fileContent)
3. Combine into a cache key: SHA-256(taskName + command + join(fileHashes))
4. Truncate to 16 hex characters: e.g. a3f2b1c4e2d1f890
5. Check .mtr-cache/<taskName>/<key>/meta.json
   • Hit: skip task, restore output files, mark status "cached"
   • Miss: run task, save outputs + meta.json on success

The cache key changes whenever any input file changes (content or path).

Cache directory layout

.mtr-cache/
  lint/
    a3f2b1c4e2d1f890/
      meta.json          { ts, durationMs, exitCode, command }
    b81d220e1f4a3c9d/
      meta.json
  build/
    5c1a8e90f7b2d041/
      meta.json
      outputs/
        packages/server/dist/mtr.js
        packages/web/dist/index.html

Listing cache entries

mtr cache ls

Or via web UI: Cache tab.

Output columns: TASK, KEY, SIZE, CREATED, COMMAND

Clearing cache

# Clear everything
mtr cache clear

# Clear one task only
mtr cache clear build
mtr cache clear lint

# Or via HTTP API
curl -X DELETE http://localhost:3300/api/cache
curl -X DELETE http://localhost:3300/api/cache/build

When a task is not being cached

Common reasons:

1. No inputs defined - cache key will be constant for the same command, so it will hit after the first run. If inputs are left empty, any file change will not affect the key.
2. Input glob too narrow - the file that changed is not covered by the glob pattern.
3. --force flag was used - bypasses cache entirely.
4. Task failed - failed runs are not written to cache.
5. Outputs list missing - task runs but output files are not restored on cache hit (they are simply re-run).

Debugging cache misses

Check what files are covered by your inputs:

# List files matching a glob (requires glob CLI or node)
node -e "
const {glob} = require('glob');
glob('packages/*/src/**/*.ts').then(files => {
  console.log(files.sort().join('\n'));
});
"

Check the cache key for a specific task:

# Not a direct command, but the cache key appears in mtr status output
mtr status
# Look at the CACHE column for the key

Best practices

• Define inputs as tightly as possible (exclude generated files, node_modules, dist)
• Define outputs for tasks that produce files used by downstream tasks (build, codegen)
• Do not include large binary files in inputs - they increase hash computation time
• Run mtr cache clear build when you want to force a rebuild after a dependency install

Cache API

GET  /api/cache
DELETE /api/cache
DELETE /api/cache/:taskName

GET response:

[
  {
    "taskName": "lint",
    "key": "a3f2b1c4",
    "ts": 1742482200000,
    "sizeBytes": 4096,
    "command": "pnpm -r lint"
  }
]