screenshot-rename

A Claude Code skill that turns a folder of timestamp-named screenshots into a folder of human-readable, searchable filenames — using parallel Haiku vision agents.

Documentation: pages.tojo.team/cardinale/screenshot-rename — full homepage with the workflow, gotchas, and use-case worked examples.

CleanShot 2026-04-15 at 09.14.07.png
   ↓
CleanShot - Shamel Studio Affiliate Referral Code Modal - 2026-04-15 at 09.14.07.png

Built for CleanShot-style screenshot folders, but works on any directory of .png / .gif / .mp4 / .pdf files named only by timestamp.

Highlights

• Parallel — describes ~200 files in 3 minutes using 10 concurrent Haiku subagents.
• Safe — pre-builds the full rename plan in memory, validates uniqueness and target collisions, then renames atomically with file-count audit. Designed after losing 4 files to a mv overwrite during prototyping.
• Handles video/PDF — extracts the first frame so vision agents can describe them.
• Resizes for the vision tool — Retina screenshots exceed Read's image cap; pipeline downsamples to 1568px max.

Installation

This is a Claude Code skill. Drop the screenshot-rename/ directory into ~/.claude/skills/:

git clone https://gitea.tojo.team/cardinale/screenshot-rename.git ~/.claude/skills/screenshot-rename

In your next Claude Code session, ask:

rename all the cleanshot files in ~/Documents/Screenshots/ based on their content

The skill will activate automatically.

Usage from the command line

You can also drive the pipeline directly:

# 1. Prep — extract frames, resize, build batches
python3 pipeline.py prep --src "/path/to/folder" --batch-size 19

# 2. (In a Claude Code session, dispatch one Haiku subagent per
#     /tmp/screenshot-rename/full-batch-NN file using the prompt template
#     in SKILL.md.)

# 3. Plan — aggregate descriptions, validate, build rename map
python3 pipeline.py plan --src "/path/to/folder"

# 4. Execute — apply the plan, audit file count
python3 pipeline.py execute --src "/path/to/folder"

The dispatch step (#2) currently requires a Claude Code session. See Roadmap.

Documentation

• Homepage with worked examples: docs/index.html
• Full skill spec: SKILL.md
• Pipeline source: pipeline.py

The gotchas this skill encodes

This skill exists because every one of these caused real damage during development:

1. The macOS Read tool has an image-size cap. Resize first.
2. Vision can't read .mp4 or multi-page .pdf directly. Extract a frame.
3. Bash regex [[ =~ ]] does NOT populate BASH_REMATCH in zsh. Targets become empty. Loops collide on the same filename. Files vanish. Use Python for any filename mutation.
4. mv silently overwrites. Use mv -n or os.rename with explicit pre-existence check.
5. Pre-build the entire rename plan in memory and validate uniqueness before any mv.
6. Audit len(os.listdir(DEST)) before and after. Equal count == proof no overwrites.
7. iCloud-synced files in Time Machine local snapshots are file-provider stubs, not bytes. External backups (Backblaze, Time Machine to physical disk) are the real recovery source.
8. Bash run_in_background may exit early on while read loops. Run renames foreground via Python.
9. Haiku occasionally returns the resized .jpg filename instead of the original .png. Validator must try alt extensions.
10. Always preserve the original .mp4 / .pdf extension — describe via the extracted frame, rename the source.

The full discussion is in SKILL.md.

Roadmap

• Direct Anthropic API mode (no Claude Code session required) — needs ANTHROPIC_API_KEY
• Custom prompt templates per-folder
• Optional preservation of dots in technical strings (v2.1 currently becomes V21)
• Dry-run flag on execute

License

MIT — see LICENSE.