Hi everyone,
over time Home Assistant installations tend to accumulate a lot of files: camera snapshots, temporary exports, backups, media files, logs, etc.
On systems with limited storage (e.g. Raspberry Pi, SSDs, NAS mounts), this can quietly become a real problem.
I built Retention Cleaner to solve exactly this use case in a safe and transparent way.
What it does
Retention Cleaner automatically identifies files older than a configured retention period and can remove them on demand.
Typical use cases:
Camera snapshots older than X days
Temporary exports or generated files under /media
Regular cleanup tasks without shell scripts or cron jobs
Safety first (very important)
File deletion is risky, so the integration is intentionally conservative:
Dry-run mode by default – nothing is deleted until you explicitly allow it
Hard path restrictions (only allowed directories, no wildcards)
Delete limits per run to avoid accidents
Sensors show what would be deleted before anything happens
You always see what will be deleted before it actually is.
How it integrates into Home Assistant
The integration exposes:
Sensors (files found, files eligible for deletion, last run, etc.)
Buttons for scan and cleanup
A device that can be used in dashboards and automations
This makes it easy to:
Monitor cleanup status
Trigger cleanups manually
Combine it with notifications or automations
Availability
HACS default repository PR is already submitted
Home Assistant brands PR is merged (icon + branding ready)
Until the HACS PR is merged, the integration can be installed as a custom repository.
GitHub repository:
