admin/SuperCharged-Claude-Code-Upgrade
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add image paste support for Claude Code CLI with Z.AI vision MCP

Browse Source 
Add clipboard image helper scripts to enable easy image paste functionality
in Claude Code CLI using the Z.AI vision MCP server.

Features:
- clippaste-image: Simple clipboard image extractor (Wayland/X11)
- clipimage-paste: Advanced handler with JSON/base64/watch modes
- IMAGE-PASTE-README.md: Complete documentation

Integration:
- Works with Ctrl+V in Claude Code CLI
- Automatic Wayland (wl-paste) and X11 (xclip) detection
- Z.AI MCP server provides 8 vision analysis tools

Usage:
  clippaste-image                    # Paste to temp file
  clippaste-image ~/screenshot.png   # Paste to specific file
  clipimage-paste --json             # Get JSON with metadata
  clipimage-paste --watch            # Watch for new images

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
uroma
2026-01-23 19:36:15 +00:00
Unverified
parent 61c0632e0f
commit 0a9110dea1
3 changed files with 544 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

302
bin/IMAGE-PASTE-README.md Normal file
View File

@@ -0,0 +1,302 @@
# 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)