cleanup-screenshots

name

cleanup-screenshots

description

Find screenshots shared/accumulated during this Claude Code session and, with the user's approval, move them to the Trash (no permanent delete — recoverable). Use before ending a session, when asked to tidy the Desktop/screenshots folder, or when the screenshot-janitor Stop hook suggests cleanup. Triggers include "clean up screenshots", "delete screenshots", "tidy my desktop", "remove the screenshots".

Screenshot Janitor — Cleanup

Cleans up screenshots that piled up during this session safely: never rm; files are moved to the Trash and can be restored. Session scope comes from the started_at timestamp recorded by the SessionStart hook (only screenshots created during this session).

Helper scripts live next to this plugin. Resolve their location like this (works whether or not CLAUDE_PLUGIN_ROOT is set in skill context):

SCRIPTS="$(cat "$HOME/.claude/screenshot-janitor/scripts-path" 2>/dev/null)"
[ -z "$SCRIPTS" ] && SCRIPTS="${CLAUDE_PLUGIN_ROOT}/scripts"

Flow

1. Find candidates

bash "$SCRIPTS/find.sh"

Interpret the output:

• NO_SESSION → no session record. Ask the user whether to scan all screenshots; if yes, run bash "$SCRIPTS/scan.sh" 0.
• SESSION_META:<path> → remember this path; you will write the handled marker into its directory in step 5.
• Following TSV lines are candidates: <mtime_epoch>\t<size_bytes>\t<path>.
• If there are no TSV lines: say "No screenshots to clean up for this session 👍" and stop.

2. Show a clear list

Present the candidates as a numbered, human-readable table. Convert bytes to MB/KB and the mtime epoch to a readable time. Example:

Found 3 screenshots from this session:

  1.  Screenshot 2026-06-07 at 04.44.07.png   3.6 MB   04:44
  2.  Screenshot 2026-06-07 at 04.44.17.png   3.4 MB   04:44
  3.  Screenshot 2026-06-07 at 15.49.25.png   5 KB     15:49

Total ~7.0 MB.

3. Ask for approval

Offer clear options and wait for the answer:

• All → move every candidate to the Trash.
• Some → "tell me the numbers, e.g. 1,3" → only those.
• Cancel → do nothing.

NEVER move files without approval.

4. Move to Trash

For the approved files (not permanent deletion!):

bash "$SCRIPTS/trash.sh" "/full/path/Screenshot ....png" "/another/file.png"

trash.sh is cross-platform (macOS Trash / Linux gio trash / trash-cli). Always double-quote paths (they contain spaces). Never use rm.

5. Mark handled and report

After a successful cleanup, mark the session so it won't remind again (use the SESSION_META path from step 1):

touch "$(dirname '<SESSION_META path>')/handled"

Then give a short summary: how many files, how much space freed, and that they went to the Trash ("you can restore from Trash if needed"). Mention any skipped files.

Notes

• Configuration: create ~/.claude/screenshot-janitor/config.sh to override SCAN_DIRS, NAME_PATTERNS, or MIN_AGE_SECONDS (don't edit plugin files).
• This skill also works standalone; it does not require the Stop hook.
• Respond in the user's configured language.