Auto-resize oversized screenshots to prevent Claude API dimension errors and session corruption

version
1.0.0
GitHub stars
26

Install

/plugin install image-sanitizer@image-sanitizer-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add MussaCharles/claude-code-image-sanitizer.

Contents

Discovered from source

Commands 2

Session Repair Tool

This tool fixes corrupted Claude Code sessions caused by oversized images (>8000px or >5MB) stuck in conversation context.

Quick Actions

Ask the user which action they want to perform:

  1. Find corrupted sessions - Scan for sessions with oversized image data
  2. Fix all corrupted sessions - Automatically repair all found issues
  3. List all sessions - Show all Claude Code sessions with status
  4. Show help - Display all available repair commands

Commands Reference

Run these commands using the repair script at ${CLAUDE_PLUGIN_ROOT}/scripts/repair-session.sh:

ActionCommand
Find corrupted${CLAUDE_PLUGIN_ROOT}/scripts/repair-session.sh --find
Fix all${CLAUDE_PLUGIN_ROOT}/scripts/repair-session.sh --fix-all
Fix specific${CLAUDE_PLUGIN_ROOT}/scripts/repair-session.sh --fix <file.jsonl>
List sessions${CLAUDE_PLUGIN_ROOT}/scripts/repair-session.sh --list
Delete corrupted${CLAUDE_PLUGIN_ROOT}/scripts/repair-session.sh --delete-corrupted
List backups${CLAUDE_PLUGIN_ROOT}/scripts/repair-session.sh --list-backups
Restore backup${CLAUDE_PLUGIN_ROOT}/scripts/repair-session.sh --restore <timestamp>
Help${CLAUDE_PLUGIN_ROOT}/scripts/repair-session.sh --help

How It Works

  1. Scans .jsonl conversation files in ~/.claude/projects/ for oversized base64 image data
  2. Creates a backup of the original file before making changes
  3. Replaces image content with a text placeholder
  4. Removes toolUseResult to prevent render crashes

After Repair

After running the repair tool:

  1. Restart Claude Code to reload the fixed session
  2. Use /resume to continue from where you left off
  3. Your conversation context is preserved (only oversized images are removed)

When to Use This Tool

Use when you see these errors:

  • "image dimensions exceed max allowed size"
  • "At least one of the image dimensions exceed max allowed size: 8000 pixels."
  • "Image was too large. Double press esc to go back and try again with a smaller image."
  • Session becomes unresponsive after pasting/dragging a large image

Important Notes

  • Backups are automatic: The tool always creates a backup before modifying files
  • Safe to run: Running --find only scans, it doesn't modify anything
  • Interactive mode: Running without arguments starts interactive mode with a menu

Image Sanitizer Status

Check the current image sanitizer configuration and system status.

Current Configuration

Report the following environment variable settings (show defaults if not set):

VariableCurrent ValueDefaultDescription
CLAUDE_IMAGE_MAX_DIMENSION(check env)1200Maximum pixels for any dimension
CLAUDE_IMAGE_MAX_SIZE_MB(check env)4Maximum file size in MB
CLAUDE_IMAGE_QUALITY(check env)85JPEG compression quality (1-100)
CLAUDE_IMAGE_DEBUG(check env)0Debug logging (0=off, 1=on)
CLAUDE_FULLPAGE_ACTION(check env)blockAction for fullPage screenshots (block/warn)

System Check

  1. ImageMagick: Check if magick or convert command is available

    • Run: which magick || which convert
    • If found, report version: magick --version or convert --version
  2. jq: Check if jq is available (required for JSON parsing)

    • Run: which jq
    • If found, report version: jq --version

Anthropic Limits Reference

ScenarioMax DimensionMax Size
Single image8000 x 8000 px5 MB
Multi-image (>20 images)2000 x 2000 px5 MB
Recommended (safe)1200 px< 4 MB

Troubleshooting Tips

If images are still causing issues:

  • Lower CLAUDE_IMAGE_MAX_DIMENSION to 1000
  • Lower CLAUDE_IMAGE_QUALITY to 60-70
  • Enable debug logging with CLAUDE_IMAGE_DEBUG=1 and run claude --verbose

Sponsors

Details

Marketplace
MussaCharles/claude-code-image-sanitizer
Source
plugin
Author
Mussa Charles
Category
Community