Image Processing

Smart image processor with automatic single-file and batch operation detection, modern format support, and social media presets.

Quick Start

Process images with optimal defaults:

cd ~/.claude/scripts/media-tools bun run image photo.jpg --Format webp --Quality 85

Intelligent Behavior

Automatically detects input type and adjusts processing:

Input Behavior

Single file (photo.jpg ) Process that file

Directory (./photos/ ) Process all images in directory

Glob pattern (*.png ) Process matching files

Multiple files Process each file

CLI Options

Option Default Options Description

Resolution original

original, 3840, 2560, 1920, 1280, 800, 640, custom Target width in pixels

Ratio original

original, 16:9, 9:16, 3:2, 1:1, 4:5, 4:3, 21:9 Aspect ratio (crops to fit)

Format webp

original, webp, jpg, png, avif Output format

Quality 85

95, 85, 75, 65, 55, 45 Quality level (1-100)

Output same

same, subfolder, custom Output location

Features

Format Support:

• WebP - Best compression/quality ratio (recommended)

• AVIF - Next-gen format, excellent compression

• JPG - Universal compatibility

• PNG - Lossless, supports transparency

Smart Processing:

• Preserves original files (creates new output)

• Strips metadata for smaller files

• Maintains aspect ratio or crops to specified ratio

• Handles batch operations efficiently

Supported Input Formats: jpg, jpeg, png, gif, webp, tiff, avif, bmp, heic

Usage Examples

Single file - resize and convert

bun run image photo.jpg --Resolution 1920 --Ratio 16:9 --Format webp

Single file - compress only

bun run image photo.jpg --Format webp --Quality 75

Batch - entire folder

bun run image ./photos/ --Resolution 1280 --Format webp --Output subfolder

Shows preview before processing:

Found 24 images to process:

• photo1.jpg (2.4 MB)
• photo2.png (1.8 MB)
• ... and 22 more

Settings:

• Resolution: 1280 (original → 1280px width)
• Ratio: original (keep aspect ratio)
• Format: webp
• Quality: 85%
• Output: ./photos/processed/

Proceed? [Yes/No]

Batch - specific files

bun run image "*.png" --Format webp --Quality 85

Instagram post (1:1 ratio)

bun run image ./uploads/ --Resolution 1280 --Ratio 1:1 --Format jpg

Instagram story (9:16 ratio)

bun run image ./content/ --Resolution 1080 --Ratio 9:16 --Format jpg --Quality 90

Social Media Presets

Platform Resolution Ratio Format Quality Use Case

Web hero 1920 16:9 webp 85 Hero images

Thumbnail 640 16:9 webp 75 Grid thumbnails

Instagram post 1280 1:1 jpg 85 Feed posts

Instagram story 1080 9:16 jpg 85 Stories/Reels

Twitter/X 1280 16:9 jpg 85 Tweets with images

LinkedIn 1920 1.91:1 jpg 85 Posts

OG image 1200 1.91:1 jpg 85 Social sharing

4K wallpaper 3840 16:9 png 95 Desktop backgrounds

Processing Modes

With resize and crop (when ratio specified)

magick input.jpg
-resize 1920x1080^
-gravity center
-extent 1920x1080
-quality 85
-strip
output.webp

Compress only (original dimensions)

magick input.jpg
-quality 85
-strip
output.webp

Resize without crop (original ratio)

magick input.jpg
-resize 1920x
-quality 85
-strip
output.webp

Aspect Ratio Calculations

When a ratio is specified, height is calculated automatically:

Ratio Calculation Example (width=1920)

16:9 height = width × 9/16 1080px

9:16 height = width × 16/9 3413px

3:2 height = width × 2/3 1280px

1:1 height = width 1920px

4:5 height = width × 5/4 2400px

4:3 height = width × 3/4 1440px

21:9 height = width × 9/21 823px

Processing Results

After batch processing, shows detailed report:

✓ Processed 24 images

Summary:

• Total input: 45.2 MB
• Total output: 12.8 MB
• Compression: 72% smaller
• Time: 1.2s

Output: ./processed/

Best Practices

• Use WebP for web - 30% smaller than JPG with same quality

• Keep originals - Tool never modifies source files

• Quality 85 - Sweet spot for most use cases

• Add dimensions - Prevent layout shifts on web

• Test compression - Start with Quality 85, adjust if needed

• Batch wisely - Process similar images together

• Use ratios for social - Consistent sizing across platforms

Requirements

• ImageMagick 7+ - Uses magick command

• Install: brew install imagemagick

Related Files

• Command: plugins/media-tools/commands/image.md

• Media Processor: plugins/media-tools/skills/media-processor/

• Video Processing: plugins/media-tools/skills/video-processing/