image-sanitizer

Claude Code Image Sanitizer

Auto-resize oversized images and repair corrupted sessions in Claude Code.

The Problem

When using MCP screenshot tools (Chrome DevTools, Playwright, Puppeteer) or dragging/pasting large images into Claude Code, oversized images can corrupt your session with 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."

Once this happens, your entire session becomes unusable — every subsequent message fails. The only fix is /clear, which loses all your context.

This is a known issue affecting many users.

The Solution

Quick Start

Prerequisites

# macOS
brew install jq imagemagick

# Linux/WSL
sudo apt install jq imagemagick

Install the Plugin

# In Claude Code, run:
/plugin marketplace add MussaCharles/claude-code-image-sanitizer
/plugin install image-sanitizer@image-sanitizer-marketplace

Restart Claude Code: done! The plugin is now active.

git clone https://github.com/MussaCharles/claude-code-image-sanitizer.git
cd claude-code-image-sanitizer
./install.sh --global

Features

Once installed, the plugin works automatically:

Session Repair Tool

For drag & drop / pasted images that can't be intercepted by hooks.

If you see "image dimensions exceed max allowed size" errors, run:

/sanitizer-repair

After repair, restart Claude Code and use /resume to continue your session.

Standalone hooks users: See Session Repair for CLI commands.

Configuration

Set environment variables before starting Claude Code:

export CLAUDE_IMAGE_MAX_DIMENSION=1200   # Max pixels (default: 1200)
export CLAUDE_IMAGE_MAX_SIZE_MB=4        # Max file size in MB (default: 4)
export CLAUDE_IMAGE_QUALITY=85           # JPEG quality (default: 85)
export CLAUDE_IMAGE_DEBUG=1              # Enable debug logging
export CLAUDE_FULLPAGE_ACTION=warn       # Allow fullPage with warning (default: block)

Anthropic's Image Limits

Source: Anthropic Vision Documentation

Troubleshooting

Debug logging:

export CLAUDE_IMAGE_DEBUG=1
claude

# View logs in another terminal
tail -f /tmp/cc-image-sanitizer-debug.log

Note: The log file is created when the first hook runs. If you see No such file or directory, trigger a screenshot tool first, then try again.

Logs show tool names, image dimensions, and resize operations:

[2025-12-08 10:30:45] [cc-image-sanitizer] PostToolUse: mcp__playwright__browser_take_screenshot
[2025-12-08 10:30:45] [cc-image-sanitizer] Image: 1920x1080, 245678 bytes
[2025-12-08 10:30:45] [cc-image-sanitizer] Exceeds max dimension (1200)
[2025-12-08 10:30:46] [cc-image-sanitizer] Resized: 1920x1080 → 1200x675, 245678 → 98234 bytes

Still getting errors?

Uninstall

/plugin uninstall image-sanitizer@image-sanitizer-marketplace

Standalone hooks users: See Uninstallation for CLI commands.

Documentation

Testing