Image Sanitizer

Image Sanitizer Plugin

A Claude Code plugin that auto-resizes oversized screenshots to prevent API dimension errors and session corruption.

Features

• PreToolUse Hook: Blocks fullPage screenshots that would exceed API limits
• PostToolUse Hook: Automatically resizes captured screenshots using ImageMagick
• Read Hook: Resizes image files before they're read by the Read tool
• Session Repair Tool: Fix corrupted sessions caused by oversized images
• Slash Commands:
  • /sanitizer-status - Check configuration and system status
  • /sanitizer-repair - Repair corrupted sessions

Installation

Via Marketplace (Recommended)

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

From Local Path

# Clone the repository
git clone https://github.com/MussaCharles/claude-code-image-sanitizer.git

# In Claude Code
/plugin marketplace add ./claude-code-image-sanitizer
/plugin install image-sanitizer@image-sanitizer-marketplace

Prerequisites

The plugin requires these tools to be installed:

# macOS
brew install jq imagemagick

# Linux/WSL
sudo apt install jq imagemagick

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)

Usage

Once installed, the plugin works automatically:

1. Screenshots: Any MCP screenshot tool (Playwright, Puppeteer, Chrome DevTools) will have images automatically resized if they exceed limits
2. Read Tool: Image files read by Claude will be resized before being sent to the API
3. Status Check: Use /sanitizer-status to check your configuration
4. Session Repair: Use /sanitizer-repair to fix corrupted sessions

Session Repair

If you encounter these errors from drag & drop or pasted images:

• "image dimensions exceed max allowed size"
• "At least one of the image dimensions exceed max allowed size: 8000 pixels."

Use the /sanitizer-repair command to fix corrupted sessions:

# In Claude Code
/sanitizer-repair

Common operations:

• Find corrupted sessions: Scan for issues without modifying anything
• Fix all corrupted sessions: Automatically repair all found issues
• List sessions: Show all Claude Code sessions with status

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

Supported Tools

The hooks intercept these screenshot tools:

• mcp__playwright__browser_take_screenshot
• mcp__puppeteer__puppeteer_screenshot
• mcp__chrome-devtools__take_screenshot
• Any tool with "screenshot" in the name

Anthropic Image Limits

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

Debug Logging

To see hook activity:

export CLAUDE_IMAGE_DEBUG=1
claude

# View debug logs (written to file for reliable access)
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 (e.g., take a screenshot), then try tail -f 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

Plugin Structure

plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
├── hooks/
│   └── hooks.json           # Hook definitions
├── scripts/
│   ├── resize-images.sh     # PreToolUse hook
│   ├── post-screenshot-resize.sh  # PostToolUse hook
│   ├── pre-read-resize.sh   # Read tool hook
│   └── repair-session.sh    # Session repair tool
├── commands/
│   ├── sanitizer-status.md  # /sanitizer-status command
│   └── sanitizer-repair.md  # /sanitizer-repair command
└── README.md

Development

For local development and testing, you can install the plugin from a local path without publishing to a remote repository.

Note: Plugins are installed globally once installed, the plugin works in all your Claude Code sessions, regardless of which project you're in.

Local Installation

You can add a local marketplace from any directory just provide the correct path (relative or absolute).

Option A: Using Relative Path

# 1. Clone the repository
git clone https://github.com/MussaCharles/claude-code-image-sanitizer.git

# 2. Switch to your development branch (if needed)
cd claude-code-image-sanitizer
git checkout your-branch

# 3. Go to parent directory and start Claude Code
cd ..
claude

# 4. Add the marketplace using relative path (in Claude Code)
/plugin marketplace add ./claude-code-image-sanitizer

# 5. Install the plugin
/plugin install image-sanitizer@image-sanitizer-marketplace

Option B: Using Absolute Path (Recommended)

You don't need to be in any specific directory. From any Claude Code session:

# In Claude Code (from any project directory)
/plugin marketplace add /absolute/path/to/claude-code-image-sanitizer

# Install the plugin
/plugin install image-sanitizer@image-sanitizer-marketplace

Tip: The official docs show cd .. to use a relative path, but that's just one approach. Using an absolute path is simpler — you can run it from anywhere.

Select "Install now" and restart Claude Code.

Development Workflow

1. Make changes to hook scripts in plugin/scripts/
2. Uninstall the plugin: /plugin uninstall image-sanitizer@image-sanitizer-marketplace
3. Reinstall to pick up changes: /plugin install image-sanitizer@image-sanitizer-marketplace
4. Restart Claude Code if needed

Running Tests

# Run all tests including plugin structure tests
./scripts/test.sh

# Run only plugin tests
./scripts/test.sh plugin

Note on Branch Testing

The plugin marketplace system does not support branch references (e.g., repo#branch). To test a specific branch:

1. Clone the repository locally
2. Checkout the desired branch
3. Go to the parent directory: cd ..
4. Start Claude Code: claude
5. Add the marketplace using the relative path

Switching from Local to Remote

After testing, replace your local marketplace with the official GitHub version:

# 1. Uninstall the plugin
/plugin uninstall image-sanitizer@image-sanitizer-marketplace

# 2. Remove local marketplace
/plugin marketplace remove image-sanitizer-marketplace

# 3. Add GitHub marketplace
/plugin marketplace add MussaCharles/claude-code-image-sanitizer

# 4. Install from GitHub
/plugin install image-sanitizer@image-sanitizer-marketplace

Restart Claude Code to complete the switch.

Uninstall

# In Claude Code
/plugin uninstall image-sanitizer@image-sanitizer-marketplace

License

MIT License - see LICENSE

Links

• Main Repository
• Session Repair Tool
• Standalone Hooks Documentation