---
name: ctxfr-cache
description: Inspect, validate, rebuild, or clear the ctxfr hash cache. Use when the user asks about ctxfr cache status, cache validation, hash cache repair, cache rebuilds, or the equivalent of /ctxfr-cache.
---

# ctxfr Cache

Map the user's request to one of these subcommands: `status` (default), `validate`, `rebuild`, or `clear`.

If `ctxfr` is not found, tell the user: `The ctxfr binary is not installed. Run cmake --build build && cmake --install build from the ctxfr repo.`

## Status

Run `ctxfr cache status`. Use the database path in that output for any deeper inspection.

```text
=== CACHE STATUS ===
Store:      sqlite
DB:         <path from ctxfr cache status>
Hash tool:  <cache hashTool; should be builtin-xxh3>
Algorithm match: <yes if hashTool is builtin-xxh3>
Specs cached: <N>
Files cached: <total coveredFiles across all specs>
Oldest snapshot: <earliest snapshotAt>
Newest snapshot: <latest snapshotAt>
```

If `hashTool` is not `builtin-xxh3`, warn that the cache should be rebuilt.

## Validate

Run `ctxfr cache validate`, then perform deeper checks:

- Confirm each cached spec path still exists.
- Confirm each cached covered file still exists.
- Run `ctxfr specs` and flag specs missing from the cache.
- Run `ctxfr specs --coverage` and compare current coverage with cached `coveredFiles`.
- When `hashTool` is `builtin-xxh3`, run `ctxfr hash <file>` for cached files and compare hashes.

Verdict: `healthy`, `needs rebuild`, or `missing`.

## Rebuild

Run `ctxfr cache rebuild`. Report the output and note that rebuilding snapshots current files as the new baseline.

## Clear

Run `ctxfr cache clear` and report the result.