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

Feature	What it does
Prevention	Hooks auto-resize MCP screenshots before they corrupt your session
Recovery	Repair tool fixes already corrupted sessions without losing your work

---

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.

Alternative: Standalone Hooks

If you prefer not to use plugins, you can install hooks directly:

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

See Standalone Hooks Documentation for detailed instructions.

---

Features

Once installed, the plugin works automatically:

Feature	Description
Screenshot Resize	MCP screenshots (Playwright, Puppeteer, Chrome DevTools) auto-resized
Read Tool Resize	Image files resized before being read
fullPage Blocking	Prevents fullPage screenshots that would exceed limits
Session Repair	Fix corrupted sessions via /sanitizer-repair
Status Check	Check configuration via /sanitizer-status

---

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

Scenario	Max Dimension	Max Size
Single image	8000 × 8000 px	5 MB
Multi-image (>20)	2000 × 2000 px	5 MB
Default (safe)	1200 px	< 4 MB

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?

Option	Command	When to use
Lower dimension	export CLAUDE_IMAGE_MAX_DIMENSION=1000	Sessions with many images
More compression	export CLAUDE_IMAGE_QUALITY=60	Reduce file size

---

Uninstall

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

Standalone hooks users: See Uninstallation for CLI commands.

---

Documentation

Document	Description
Plugin README	Plugin-specific details, development guide
Standalone Hooks	Detailed hooks installation and configuration
Contributing	How to contribute

---

Testing

./scripts/test.sh              # Run all tests
./scripts/test.sh plugin       # Plugin structure tests
./scripts/test.sh resize       # Image resize tests
./scripts/test.sh repair       # Session repair tests

---

Acknowledgments

• Session repair approach inspired by community workaround by @jhilgert
• Development assisted by Claude Code

---

License

MIT License. See LICENSE.