SuperCharged-Claude-Code-Upgrade/bin/IMAGE-PASTE-README.md

Image Paste Support for Claude Code CLI

This directory contains helper scripts for pasting images from the clipboard into Claude Code CLI, using the Z.AI vision MCP server for analysis.

Features

• Automatic clipboard detection - Works with both Wayland (wl-paste) and X11 (xclip)
• Multiple output formats - File paths, JSON, base64 encoding
• Watch mode - Monitor clipboard for new images
• Cross-platform - Linux, macOS, WSL support

Installation

System Requirements

# Debian/Ubuntu
sudo apt install wl-clipboard  # Wayland
sudo apt install xclip         # X11 (alternative)

# macOS
brew install wl-clipboard

# Arch Linux
sudo pacman -S wl-clipboard

# Fedora/RHEL
sudo dnf install wl-clipboard

Install to System Path

cd /tmp/SuperCharged-Claude-Code-Upgrade/bin
sudo cp clippaste-image clipimage-paste /usr/local/bin/

Usage

Basic Paste

# Paste clipboard image to temp file
clippaste-image

# Paste to specific location
clippaste-image ~/screenshot.png

# Output file path to stdout only (for scripts)
clippaste-image -

Advanced Options

# Get JSON output with metadata
clipimage-paste --json

# Get base64 encoded image
clipimage-paste --base64

# Show clipboard info without saving
clipimage-paste --info

# Watch for new images
clipimage-paste --watch

Integration with Claude Code CLI

Method 1: Direct Paste (Ctrl+V)

Claude Code CLI has built-in clipboard paste support:

1. Copy an image to your clipboard (screenshot, file manager, browser)
2. Press Ctrl+V in Claude Code CLI
3. Image is automatically analyzed using Z.AI vision MCP

Method 2: Script-Based

# In Claude Code CLI
> Please analyze this screenshot: $(clippaste-image)

> Read the text from this image: $(clippaste-image -)

> What does this error mean? $(clippaste-image)

Method 3: File Path

# Save clipboard to file
clippaste-image /tmp/my-screenshot.png

# In Claude Code CLI
> Analyze /tmp/my-screenshot.png

Screenshot Tools

Linux

# GNOME (Wayland/X11)
gnome-screenshot -a -c                    # Select area, copy to clipboard
gnome-screenshot -w -c                    # Window, copy to clipboard

# KDE Plasma
spectacle -b -r                           # Region, copy to clipboard

# ImageMagick
import -window root /tmp/screen.png       # Full screenshot
import /tmp/area.png                      # Select area

# grim (Wayland)
grim -g "$(slurp)" - | wl-copy            # Select area, copy to clipboard

macOS

# Full screenshot to clipboard
Cmd+Ctrl+Shift+3

# Select area to clipboard
Cmd+Ctrl+Shift+4

# Via command line
screencapture -c -i                       # Interactive selection
screencapture -c -w                       # Capture window

Windows (WSL)

# Windows PowerShell (from WSL)
powershell.exe -c "Get-Clipboard -Format Image" > /tmp/image.png

# Or use Windows screenshot tools:
# Win+Shift+S - Snipping Tool (copies to clipboard)

Z.AI Vision MCP Capabilities

With image paste enabled, you can ask Claude to:

UI/UX Analysis

• "What design pattern is this interface using?"
• "Analyze the layout and suggest improvements"
• "Extract the color scheme from this screenshot"

Text Extraction (OCR)

• "Read all the text from this screenshot"
• "Extract the error message from this image"
• "Transcribe the code from this screenshot"

Error Diagnosis

• "What's causing this error?"
• "How do I fix this issue shown in the screenshot?"
• "Explain this error message"

Code Generation

• "Convert this UI mockup to React code"
• "Generate HTML/CSS for this design"
• "Create a Tauri app from this wireframe"

Data Visualization

• "What insights from this chart?"
• "Summarize the data in this graph"
• "Extract the values from this table"

Image Comparison

• "Do these two screenshots match?"
• "What changed between these two UI states?"

Troubleshooting

"No image found in clipboard"

Cause: Clipboard is empty or doesn't contain image data

Solutions:

• Take a screenshot first (see Screenshot Tools section)
• Copy an image from file manager or browser
• Verify clipboard has image: clipimage-paste --info

"wl-paste: unable to connect to display"

Cause: Wayland compositor not accessible

Solutions:

# Check Wayland display
echo $WAYLAND_DISPLAY

# Try X11 backend
export WAYLAND_DISPLAY=""
clippaste-image

"xclip: unable to open display"

Cause: X11 display not set or accessible

Solutions:

# Check X11 display
echo $DISPLAY

# For WSL, set Windows X11 server
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0

Image is pasted as file path, not image

Cause: File path pasted instead of image data

Solution: Use Ctrl+V (not Ctrl+Shift+V) for direct image paste in Claude Code CLI

Environment Variables

# Override default temp directory
export CLIPIMAGE_TEMP_DIR="/tmp/clipboard"

# Set default output format
export CLIPIMAGE_FORMAT="png"  # or jpg, webp

# Enable verbose logging
export CLIPIMAGE_DEBUG=1

Scripts Reference

clippaste-image

Simple clipboard image extractor.

Option	Description
(none)	Save to /tmp/clipboard-image.png
path	Save to specified path
-	Output path to stdout only

clipimage-paste

Advanced clipboard image handler with multiple output formats.

Option	Description
--json	Output JSON with metadata
--base64	Output base64 encoded
--info	Show clipboard info only
--watch	Watch for new images
-o PATH	Set output path

Technical Details

Clipboard Systems

System	Tool	Priority
Wayland	wl-paste	1st
X11	xclip	2nd (fallback)

Supported Image Formats

• PNG (preferred)
• JPEG
• WebP
• BMP
• GIF (static)

MCP Server Integration

The Z.AI MCP server (@z_ai/mcp-server) provides 8 vision tools:

1. analyze_image - General image analysis
2. extract_text_from_screenshot - OCR text extraction
3. diagnose_error_screenshot - Error diagnosis
4. understand_technical_diagram - Diagram analysis
5. analyze_data_visualization - Chart/graph analysis
6. ui_diff_check - UI comparison
7. ui_to_artifact - UI to code conversion
8. analyze_video - Video analysis

License

MIT License - Part of SuperCharged-Claude-Code-Upgrade

Credits

• Z.AI MCP Server: https://github.com/ZAI-China/mcp-server
• wl-clipboard: https://github.com/bugaevc/wl-clipboard
• Claude Code: https://claude.com/claude-code

Related Links

• Clipboard Paste Issues
• Cross-Platform Guide
• Ctrl+V Fix