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

```bash
# 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

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

## Usage

### Basic Paste

```bash
# 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

```bash
# 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

```bash
# 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

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

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

## Screenshot Tools

### Linux

```bash
# 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

```bash
# 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)

```bash
# 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:**
```bash
# 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:**
```bash
# 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

```bash
# 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](https://github.com/anthropics/claude-code/issues/12644)
- [Cross-Platform Guide](https://harishgarg.com/pasting-images-in-claude-code-complete-cross-platform-guide)
- [Ctrl+V Fix](https://www.arsturn.com/blog/claude-code-paste-image-guide)