How to Automate Bulk Image Optimization with Claude Code

I spend a lot of time building websites and landing pages for clients in Vancouver. One pattern that comes up constantly: the client hands over a folder of images — product photos, team headshots, blog headers — and every single file is a 4MB JPEG straight from their phone or a photographer's camera. Loading those images as-is destroys page speed. Compressing them one by one in Photoshop or an online tool takes forever.

So I built an automated bulk image optimization workflow with Claude Code. It handles compression, resizing, format conversion, filename sanitization, and basic alt text generation. I run it once at the start of a project, and the images are ready to deploy. The whole process takes about five minutes for a typical batch of 200–300 images.

Here's how the workflow works, what it does, and how you can build something similar if you're dealing with the same problem.

What the Workflow Actually Does

Before I get into the technical setup, it's worth laying out what "bulk image optimization" means in this context. I'm not talking about applying Instagram filters or doing creative retouching. This is purely about making images web-ready: smaller file sizes, correct dimensions, modern formats, and clean filenames.

The workflow has five main steps:

• Compression — reduces file size by 50–70% without visible quality loss, using configurable JPEG and PNG compression settings
• Resizing — scales images down to a maximum width (usually 1920px or 2400px) so you're not serving 6000px originals on a 1400px screen
• Format conversion — outputs both WebP and fallback JPEG versions for better performance across browsers
• Filename sanitization — strips spaces, special characters, and uppercase letters so filenames are URL-safe and consistent
• Alt text generation — creates basic descriptive alt text from the filename, which you can refine manually later

The result is a parallel folder structure with optimized images ready to drop into a website, along with a CSV file mapping original filenames to new filenames and suggested alt text.

The Tech Stack Behind It

The workflow runs as a Node.js script that Claude Code helps me build and customize for each project. The core image processing is handled by the Sharp library, which is fast, reliable, and well-documented. Sharp does the heavy lifting for compression, resizing, and format conversion.

The script takes a source folder path and an output folder path as arguments. It scans the source folder recursively, identifies all image files (JPEG, PNG, GIF, WebP), and processes them in parallel batches to speed things up. On my M2 MacBook Pro, it processes about 100 images per minute, depending on source file sizes.

Here's the basic structure of the script Claude Code generates:

const sharp = require('sharp');
const fs = require('fs').promises;
const path = require('path');

async function optimizeImage(inputPath, outputPath) {
  const image = sharp(inputPath);
  const metadata = await image.metadata();
  
  // Resize if width exceeds max
  if (metadata.width > 1920) {
    image.resize(1920, null, { withoutEnlargement: true });
  }
  
  // Output WebP version
  await image.webp({ quality: 85 }).toFile(
    outputPath.replace(/\.\w+$/, '.webp')
  );
  
  // Output JPEG fallback
  await image.jpeg({ quality: 82, progressive: true }).toFile(
    outputPath.replace(/\.\w+$/, '.jpg')
  );
}

That's the core logic. The full script includes error handling, batch processing, filename sanitization, and CSV output, but this is the part that does the actual optimization work.

Configuring Quality Settings

The most important decision in any image optimization workflow is the quality threshold. Too aggressive and you get visible artifacts. Too conservative and you don't save enough file size to justify the effort.

I've settled on these defaults after testing dozens of configurations across different image types:

• JPEG quality: 82 — preserves detail in photos while cutting file size by about 60% compared to the original
• WebP quality: 85 — WebP compression is more efficient than JPEG, so you can go slightly higher and still get smaller files
• PNG compression: level 9 — lossless compression, so there's no quality tradeoff; level 9 is slowest but produces the smallest files
• Maximum width: 1920px — covers most desktop screens and high-DPI mobile displays without serving unnecessarily large files

These settings work well for general website content. If you're working with e-commerce product images that need to support zoom views, you might bump the max width to 2400px and the quality to 88. If you're optimizing hero images for a marketing site, you can drop quality to 78 and most people won't notice the difference.

The key insight: you don't need one universal setting. Claude Code can generate variations of the script with different quality profiles for different image types. I keep three versions saved: one for product photos, one for blog content, and one for background images.

Handling Filenames and Alt Text

This is the part that saves the most manual work after the optimization itself. Most clients hand over images with filenames like "IMG_7342.jpg" or "DSC00891 - Copy (2).png". Those filenames are useless for SEO, impossible to search, and break when you try to use them in URLs.

The workflow includes a filename sanitization step that:

• Converts to lowercase
• Replaces spaces and underscores with hyphens
• Removes special characters except hyphens and periods
• Strips common camera prefixes like "IMG_" and "DSC"
• Appends a short hash if duplicate names are detected

So "Product Photo - Final v2 (1).JPG" becomes "product-photo-final-v2.jpg". Much better.

For alt text generation, the script takes the sanitized filename, replaces hyphens with spaces, and adds basic context based on the folder structure. If the file is in a folder called "team-photos", the alt text becomes "Team photo: [filename]". If it's in "products/outdoor-gear", it becomes "Outdoor gear product: [filename]".

This isn't perfect alt text — you still need a human to review and add specific details — but it's a huge improvement over leaving alt attributes empty or using the original filename as-is.

Running the Workflow

Once the script is set up, running it is straightforward. I keep the script in a "tools" folder in my project repo, and I run it from the command line whenever I get a new batch of images from a client:

node optimize-images.js ./source-images ./public/images

The script processes all images in the source folder, writes optimized versions to the output folder (maintaining the original folder structure), and generates a CSV file mapping original names to new names with suggested alt text. The CSV goes to the client or content team so they can review the alt text and make it more descriptive where needed.

Total time for a typical batch of 250 images: about 4 minutes. Manual time saved compared to doing this in Photoshop or an online tool: at least 2 hours.

Real Results from a Recent Project

I recently rebuilt a product site for a Vancouver-based outdoor gear retailer. They had about 340 product images, all shot professionally but delivered as uncompressed TIFFs and high-res JPEGs. Average file size: 6.2 MB. Total size of the image folder: 2.1 GB.

After running the optimization workflow:

• Average file size dropped to 180 KB (97% reduction)
• Total folder size: 61 MB
• Page load time for product pages went from 8.4 seconds to 1.9 seconds
• Lighthouse performance score improved from 42 to 94

The images still look sharp on desktop and mobile. The client didn't notice any quality difference. Their customers got a much faster site. That's the entire point of doing this.

When to Use This vs. a Service Like Cloudinary

A fair question: why not just use an image CDN like Cloudinary or Imgix that handles optimization automatically?

Those services are great if you need dynamic resizing, face detection, or real-time transformations. But they add cost and complexity, and for most small business sites, they're overkill. If your image library is relatively static — you upload a batch of product photos once and they don't change much — it's simpler and cheaper to optimize once at build time and serve the optimized files directly.

I use Cloudinary when a client needs to let non-technical staff upload images regularly through a CMS and can't be expected to optimize them first. But for projects where I'm handling the image pipeline or training a technical client on deployment, the Claude Code workflow is faster and gives more control.

Getting Started If You Want to Build This

If you want to set up something similar, here's where I'd start:

• Install Node.js if you don't have it already (it's free and takes about 2 minutes)
• Install the Sharp library in your project: npm install sharp
• Ask Claude Code to generate a basic image optimization script with your preferred quality settings
• Test it on a small batch of 10–20 images and compare the output quality to the originals
• Adjust quality settings if needed, then run it on your full image library

The first time you do this, budget about an hour to get the script working and test different settings. After that, it's a 5-minute task every time you get new images.

If you want help setting this up for your specific workflow — or if you want me to build a custom version that integrates with your CMS or deployment pipeline — I'm available for consulting. This kind of workflow automation is exactly what I do for clients in Vancouver and beyond.

And if you're curious about other ways Claude Code can speed up repetitive web development tasks, the WordPress automation guide and the Google Sheets reporting workflow are good places to start. The common thread is the same: take any task you're doing manually more than once, and automate it so you never have to do it again.