screenshot_gc
Reclaim disk space from cached screenshots by applying retention caps on count, total bytes, or age. Dry run by default; pass confirm=true to delete.
Instructions
Reclaim disk space from cached screenshots by retention policy. By DEFAULT this is a dry run: it returns the captures that WOULD be deleted (candidates) plus a count/size of leftover orphan files, and deletes nothing. To actually delete, pass BOTH dryRun:false AND confirm:true. Retention caps (all optional): maxCount (keep newest N), maxTotalBytes (keep newest under a byte budget), maxAgeMs (delete older than). When you pass none, the cache's env defaults apply (newest 200 / 256 MiB). Scope to a single tag with tag (other tags are never touched); includeOrphans (default true) also reclaims leftover on-disk files with no index entry. The newest capture is always kept by the count/byte caps. Only ever touches files inside the screenshot cache — never any other path.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Limit deletion to captures under this tag (case-insensitive). Other tags are never touched. | |
| dryRun | No | Default true: only LIST what would be deleted, delete nothing. Set false (with confirm:true) to actually delete. | |
| confirm | No | Safety gate: deletion happens ONLY when dryRun:false AND confirm:true. Otherwise the call is forced to a dry run. | |
| include | No | Optional response-shape opt-in. `['envelope']` returns the self-documenting envelope (`_version` / `data` / `as_of` / `confidence`). `['raw']` forces raw shape (overrides DESKTOP_TOUCH_ENVELOPE=1 server default). Default behaviour is raw shape (compat with existing clients). | |
| maxAgeMs | No | Delete captures older than this many milliseconds (opt-in; can clear even the newest). | |
| maxCount | No | Keep only the newest N captures; delete the rest. The single newest is always kept. | |
| maxTotalBytes | No | Keep the newest captures under this total byte budget; delete older ones beyond it. The newest is always kept. | |
| includeOrphans | No | Default true: also reclaim leftover on-disk image files that are not tracked in the cache index (e.g. files left behind by a crash). |