
image-sanitizer
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-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add MussaCharles/claude-code-image-sanitizer.
Contents
Discovered from sourceCommands 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:
- Find corrupted sessions - Scan for sessions with oversized image data
- Fix all corrupted sessions - Automatically repair all found issues
- List all sessions - Show all Claude Code sessions with status
- Show help - Display all available repair commands
Commands Reference
Run these commands using the repair script at ${CLAUDE_PLUGIN_ROOT}/scripts/repair-session.sh:
| Action | Command |
|---|---|
| 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
- Scans
.jsonlconversation files in~/.claude/projects/for oversized base64 image data - Creates a backup of the original file before making changes
- Replaces image content with a text placeholder
- Removes
toolUseResultto prevent render crashes
After Repair
After running the repair tool:
- Restart Claude Code to reload the fixed session
- Use
/resumeto continue from where you left off - 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
--findonly 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):
| Variable | Current Value | Default | Description |
|---|---|---|---|
CLAUDE_IMAGE_MAX_DIMENSION | (check env) | 1200 | Maximum pixels for any dimension |
CLAUDE_IMAGE_MAX_SIZE_MB | (check env) | 4 | Maximum file size in MB |
CLAUDE_IMAGE_QUALITY | (check env) | 85 | JPEG compression quality (1-100) |
CLAUDE_IMAGE_DEBUG | (check env) | 0 | Debug logging (0=off, 1=on) |
CLAUDE_FULLPAGE_ACTION | (check env) | block | Action for fullPage screenshots (block/warn) |
System Check
-
ImageMagick: Check if
magickorconvertcommand is available- Run:
which magick || which convert - If found, report version:
magick --versionorconvert --version
- Run:
-
jq: Check if
jqis available (required for JSON parsing)- Run:
which jq - If found, report version:
jq --version
- Run:
Anthropic Limits Reference
| Scenario | Max Dimension | Max Size |
|---|---|---|
| Single image | 8000 x 8000 px | 5 MB |
| Multi-image (>20 images) | 2000 x 2000 px | 5 MB |
| Recommended (safe) | 1200 px | < 4 MB |
Troubleshooting Tips
If images are still causing issues:
- Lower
CLAUDE_IMAGE_MAX_DIMENSIONto 1000 - Lower
CLAUDE_IMAGE_QUALITYto 60-70 - Enable debug logging with
CLAUDE_IMAGE_DEBUG=1and runclaude --verbose
Hooks 2
Sponsors
Details
- Marketplace
- MussaCharles/claude-code-image-sanitizer
- Source
- plugin
- Author
- Mussa Charles
- Category
- Community