Auto-Renaming Screenshots with Claude Code

Table of Contents

The Problem

I take a lot of screenshots. CleanShot X is my tool of choice — it’s fast, the annotations are good, and it gets out of the way. But every screenshot it produces lands on the Desktop named something like:

CleanShot 2026-04-10 at 13.11.27.png

That is not a useful filename. Six months later when I’m looking for a screenshot of a specific thing, that name tells me nothing. The Desktop fills up, the Screenshots folder becomes a graveyard of datestamps, and finding anything means opening files one by one.

Renaming them manually is one of those tasks that takes ten seconds per file, feels trivial, and adds up to a meaningful amount of time and friction over a week of working.

The Fix

Claude Code can look at an image and describe what’s in it. That’s the entire insight this is built on.

The pipeline is a shell script and an Automator Folder Action:

  1. A screenshot lands on the Desktop
  2. Automator detects the new file and calls rename-screenshot.sh
  3. The script sends the image to Claude Code with a prompt asking for a 5–8 word description
  4. Claude looks at the image and returns something like “ServiceNow Incident Queue Filtered by Priority”
  5. The script renames the file and moves it to ~/Pictures/Screenshots/

The result:

2026-04-10_13.11.27 - ServiceNow Incident Queue Filtered by Priority.png
2026-04-10_14.02.45 - Jira Sprint Board Showing Blocked Tickets.png
2026-04-10_15.30.12 - Slack Thread AI Governance Policy Discussion.png

Searchable, self-describing, sorted by date. The Desktop stays clean automatically.

How the Script Works

The script parses the timestamp out of the CleanShot filename format and uses it as a prefix. If the filename doesn’t match that pattern (e.g. a macOS default screenshot), it falls back to the file’s modification time. It then calls claude -p with the image path and a tightly worded prompt that instructs Claude to output only the description — nothing else, no punctuation except hyphens.

The description is sanitised (special characters stripped) and combined with the timestamp prefix to form the final filename.

The Automator Folder Action is the trigger. It watches ~/Desktop and fires the script whenever a new PNG appears. End to end, the rename happens within 5–15 seconds of the screenshot being taken.

Requirements

  • macOS
  • Claude Code CLI — npm install -g @anthropic-ai/claude-code
  • A free Anthropic account

That’s it. No Python, no additional dependencies.

Download

screenshot-rename-pipeline.zip — contains rename-screenshot.sh and README.md with step-by-step Automator setup instructions.

The README walks through installing the script, creating the Folder Action in Automator, and verifying everything is working. Takes about 10 minutes to set up and then you never think about it again.

You can also run it manually to process existing screenshots:

# Rename a specific file
rename-screenshot.sh ~/Desktop/CleanShot\ 2026-04-10\ at\ 13.11.27.png

# Process all unprocessed screenshots on the Desktop
rename-screenshot.sh

Part of an ongoing effort to stop spending time on things that should just happen automatically.