Add image paste support for Claude Code CLI with Z.AI vision MCP
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
302
bin/IMAGE-PASTE-README.md
Normal file
302
bin/IMAGE-PASTE-README.md
Normal 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)
|
||||
163
bin/clipimage-paste
Executable file
163
bin/clipimage-paste
Executable file
@@ -0,0 +1,163 @@
|
||||
#!/bin/bash
|
||||
# clipimage-paste - Advanced clipboard image handler for Claude Code
|
||||
# Provides multiple output formats and clipboard inspection
|
||||
#
|
||||
# Usage:
|
||||
# clipimage-paste # Paste to temp file, output path
|
||||
# clipimage-paste --json # Output JSON with metadata
|
||||
# clipimage-paste --base64 # Output base64 encoded
|
||||
# clipimage-paste --info # Show clipboard image info only
|
||||
# clipimage-paste --watch # Watch for new images
|
||||
|
||||
set -e
|
||||
|
||||
ACTION="paste"
|
||||
OUTPUT_PATH="/tmp/clipboard-image-$(date +%s).png"
|
||||
|
||||
# Parse arguments
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case $1 in
|
||||
--json)
|
||||
ACTION="json"
|
||||
shift
|
||||
;;
|
||||
--base64)
|
||||
ACTION="base64"
|
||||
shift
|
||||
;;
|
||||
--info)
|
||||
ACTION="info"
|
||||
shift
|
||||
;;
|
||||
--watch)
|
||||
ACTION="watch"
|
||||
shift
|
||||
;;
|
||||
-o|--output)
|
||||
OUTPUT_PATH="$2"
|
||||
shift 2
|
||||
;;
|
||||
-h|--help)
|
||||
echo "Usage: clipimage-paste [OPTIONS]"
|
||||
echo ""
|
||||
echo "Options:"
|
||||
echo " -o, --output PATH Output file path"
|
||||
echo " --json Output as JSON"
|
||||
echo " --base64 Output as base64"
|
||||
echo " --info Show clipboard info only"
|
||||
echo " --watch Watch for new images"
|
||||
echo " -h, --help Show this help"
|
||||
echo ""
|
||||
echo "Examples:"
|
||||
echo " clipimage-paste # Save to temp file"
|
||||
echo " clipimage-paste -o shot.png # Save to specific file"
|
||||
echo " clipimage-paste --json # Get JSON output"
|
||||
echo " clipimage-paste --base64 | pbcopy # Copy base64 to clipboard"
|
||||
exit 0
|
||||
;;
|
||||
*)
|
||||
echo "Unknown option: $1" >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Function to get image from clipboard
|
||||
get_clipboard_image() {
|
||||
local output_file="$1"
|
||||
|
||||
# Try Wayland first
|
||||
if command -v wl-paste &> /dev/null; then
|
||||
if wl-paste --type image/png > "$output_file" 2>/dev/null && [[ -s "$output_file" ]]; then
|
||||
return 0
|
||||
fi
|
||||
fi
|
||||
|
||||
# Fallback to X11
|
||||
if command -v xclip &> /dev/null; then
|
||||
if xclip -selection clipboard -t image/png -o > "$output_file" 2>/dev/null && [[ -s "$output_file" ]]; then
|
||||
return 0
|
||||
fi
|
||||
fi
|
||||
|
||||
return 1
|
||||
}
|
||||
|
||||
# Function to get image info
|
||||
get_image_info() {
|
||||
local file="$1"
|
||||
local size_bytes=$(stat -c%s "$file" 2>/dev/null || stat -f%z "$file" 2>/dev/null || echo "0")
|
||||
local size_human=$(du -h "$file" 2>/dev/null | cut -f1 || echo "unknown")
|
||||
local dimensions=$(identify -format "%wx%h" "$file" 2>/dev/null || echo "unknown")
|
||||
local mime=$(file --mime-type -b "$file" 2>/dev/null || echo "image/png")
|
||||
|
||||
cat <<EOF
|
||||
{
|
||||
"path": "$file",
|
||||
"size_bytes": $size_bytes,
|
||||
"size_human": "$size_human",
|
||||
"dimensions": "$dimensions",
|
||||
"mime_type": "$mime",
|
||||
"timestamp": "$(date -Iseconds)"
|
||||
}
|
||||
EOF
|
||||
}
|
||||
|
||||
# Handle different actions
|
||||
case "$ACTION" in
|
||||
paste)
|
||||
if get_clipboard_image "$OUTPUT_PATH"; then
|
||||
echo "$OUTPUT_PATH"
|
||||
else
|
||||
echo "No image in clipboard" >&2
|
||||
exit 1
|
||||
fi
|
||||
;;
|
||||
|
||||
json)
|
||||
if get_clipboard_image "$OUTPUT_PATH"; then
|
||||
get_image_info "$OUTPUT_PATH"
|
||||
rm -f "$OUTPUT_PATH" # Cleanup temp file
|
||||
else
|
||||
echo '{"error": "No image in clipboard"}' >&2
|
||||
exit 1
|
||||
fi
|
||||
;;
|
||||
|
||||
base64)
|
||||
if get_clipboard_image "$OUTPUT_PATH"; then
|
||||
base64 "$OUTPUT_PATH"
|
||||
rm -f "$OUTPUT_PATH"
|
||||
else
|
||||
echo "No image in clipboard" >&2
|
||||
exit 1
|
||||
fi
|
||||
;;
|
||||
|
||||
info)
|
||||
if get_clipboard_image "$OUTPUT_PATH"; then
|
||||
get_image_info "$OUTPUT_PATH"
|
||||
rm -f "$OUTPUT_PATH"
|
||||
else
|
||||
echo '{"error": "No image in clipboard"}' >&2
|
||||
exit 1
|
||||
fi
|
||||
;;
|
||||
|
||||
watch)
|
||||
echo "Watching clipboard for images... Press Ctrl+C to stop"
|
||||
last_hash=""
|
||||
while true; do
|
||||
if get_clipboard_image "$OUTPUT_PATH"; then
|
||||
current_hash=$(md5sum "$OUTPUT_PATH" | cut -d' ' -f1)
|
||||
if [[ "$current_hash" != "$last_hash" ]]; then
|
||||
echo "[$(date '+%H:%M:%S')] New image: $OUTPUT_PATH"
|
||||
get_image_info "$OUTPUT_PATH"
|
||||
last_hash="$current_hash"
|
||||
fi
|
||||
rm -f "$OUTPUT_PATH"
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
;;
|
||||
esac
|
||||
79
bin/clippaste-image
Executable file
79
bin/clippaste-image
Executable file
@@ -0,0 +1,79 @@
|
||||
#!/bin/bash
|
||||
# clippaste-image - Paste clipboard image to temp file for Claude Code
|
||||
# Usage: clippaste-image [output-path]
|
||||
#
|
||||
# This script extracts image data from the clipboard and saves it to a file.
|
||||
# Works with both Wayland (wl-paste) and X11 (xclip).
|
||||
#
|
||||
# Examples:
|
||||
# clippaste-image # Saves to /tmp/clipboard-image.png
|
||||
# clippaste-image ~/screenshot.png # Saves to specified path
|
||||
# clippaste-image - # Outputs file path to stdout only
|
||||
#
|
||||
# Claude Code Integration:
|
||||
# Simply press Ctrl+V in Claude Code CLI, or use this script directly.
|
||||
|
||||
set -e
|
||||
|
||||
OUTPUT_PATH="${1:-/tmp/clipboard-image.png}"
|
||||
STDOUT_ONLY=false
|
||||
|
||||
if [[ "$OUTPUT_PATH" == "-" ]]; then
|
||||
OUTPUT_PATH="/tmp/clipboard-image-$(date +%s).png"
|
||||
STDOUT_ONLY=true
|
||||
fi
|
||||
|
||||
# Create temp directory if needed
|
||||
mkdir -p "$(dirname "$OUTPUT_PATH")"
|
||||
|
||||
# Try Wayland first (wl-paste)
|
||||
if command -v wl-paste &> /dev/null; then
|
||||
# Check if Wayland display is available
|
||||
if [[ -n "$WAYLAND_DISPLAY" ]] || wl-paste --type text &> /dev/null; then
|
||||
# Try to get image from clipboard
|
||||
if wl-paste --type image/png > "$OUTPUT_PATH" 2>/dev/null; then
|
||||
# Verify we got actual image data (not empty)
|
||||
if [[ -s "$OUTPUT_PATH" ]]; then
|
||||
if [[ "$STDOUT_ONLY" == true ]]; then
|
||||
echo "$OUTPUT_PATH"
|
||||
else
|
||||
echo "✓ Image saved to: $OUTPUT_PATH"
|
||||
echo " Size: $(du -h "$OUTPUT_PATH" | cut -f1)"
|
||||
fi
|
||||
exit 0
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Fallback to X11 (xclip)
|
||||
if command -v xclip &> /dev/null; then
|
||||
if [[ -n "$DISPLAY" ]]; then
|
||||
# Try to get image from X11 clipboard
|
||||
if xclip -selection clipboard -t image/png -o > "$OUTPUT_PATH" 2>/dev/null; then
|
||||
if [[ -s "$OUTPUT_PATH" ]]; then
|
||||
if [[ "$STDOUT_ONLY" == true ]]; then
|
||||
echo "$OUTPUT_PATH"
|
||||
else
|
||||
echo "✓ Image saved to: $OUTPUT_PATH"
|
||||
echo " Size: $(du -h "$OUTPUT_PATH" | cut -f1)"
|
||||
fi
|
||||
exit 0
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# No image found in clipboard
|
||||
if [[ "$STDOUT_ONLY" == true ]]; then
|
||||
exit 1
|
||||
else
|
||||
echo "✗ No image found in clipboard" >&2
|
||||
echo ""
|
||||
echo "Tips:"
|
||||
echo " - Take a screenshot first (gnome-screenshot -a -c)"
|
||||
echo " - Copy an image from your file manager or browser"
|
||||
echo " - On Wayland: ensure wl-paste can access your compositor"
|
||||
echo " - On X11: ensure xclip can access the X server"
|
||||
exit 1
|
||||
fi
|
||||
Reference in New Issue
Block a user