- name
- hidpi-mouse
- description
- Universal HiDPI mouse click handling for Linux desktop automation. Auto-detects scale factor or allows calibration for any screen resolution/DPI. Converts Claude display coordinates to xdotool screen coordinates.
- metadata
- {"os": ["linux"], "requires": {"bins": ["xdotool", "scrot", "python3"]}}
- user-invocable
- false
HiDPI Mouse Skill
Universal mouse coordinate handling for desktop automation across different screen configurations.
🚀 Quick Start
# Click at Claude display coordinates (auto-scales)
./scripts/click.sh 500 300
# First time? Run calibration for best accuracy
./scripts/calibrate.sh📐 How It Works
When Claude displays a screenshot, it scales it down. This skill converts coordinates:
Claude Display Coords → Scale Factor → xdotool Screen CoordsThe scale factor depends on:
- Screen resolution (1080p, 1440p, 4K, etc.)
- DPI settings (96, 144, 192, etc.)
- Claude's display viewport
🔧 Scripts
click.sh - Click at coordinates
./scripts/click.sh <x> <y> # Auto-scaled click
./scripts/click.sh --raw <x> <y> # No scaling (screen coords)
./scripts/click.sh --double <x> <y> # Double click
./scripts/click.sh --right <x> <y> # Right clickcalibrate.sh - Setup & Configuration
./scripts/calibrate.sh # Interactive calibration
./scripts/calibrate.sh info # Show current config
./scripts/calibrate.sh test # Test current scale
./scripts/calibrate.sh set 2.08 # Manually set scale
./scripts/calibrate.sh reset # Reset to auto-detectdetect-scale.sh - Get scale factor
./scripts/detect-scale.sh # Returns scale (e.g., 2.08)Other scripts
./scripts/move.sh <x> <y> # Move mouse
./scripts/drag.sh <x1> <y1> <x2> <y2> # Drag
./scripts/reliable_click.sh <x> <y> [--window "Name" --relative]🎯 Calibration (Recommended for New Systems)
For best accuracy on your specific system:
./scripts/calibrate.shThis will:
- Create a calibration image with markers at known positions
- Ask you where the markers appear in Claude's display
- Calculate and save the exact scale factor
📊 Common Scale Factors
| Screen | DPI | Typical Scale |
|---|---|---|
| 1920×1080 | 96 | 1.0 - 1.2 |
| 2560×1440 | 96 | 1.3 - 1.5 |
| 3024×1772 | 192 | 2.08 |
| 3840×2160 | 192 | 2.0 - 2.5 |
🔍 Troubleshooting
Clicks are offset
# Run calibration
./scripts/calibrate.sh
# Or manually adjust
./scripts/calibrate.sh set 2.1 # Try different valuesCheck current configuration
./scripts/calibrate.sh infoReset everything
./scripts/calibrate.sh reset
rm -f /tmp/hidpi_scale_cache📁 Configuration Files
~/.config/hidpi-mouse/scale.conf- User-set scale (highest priority)/tmp/hidpi_scale_cache- Auto-detected scale cache (1 hour TTL)
🌐 Universal Compatibility
This skill auto-adapts to:
- ✅ Different screen resolutions (1080p to 4K+)
- ✅ Different DPI settings (96, 120, 144, 192, etc.)
- ✅ HiDPI/Retina displays
- ✅ Multi-monitor setups (primary display)
💡 Usage Tips
- Always calibrate on a new system for 100% accuracy
- Re-calibrate if you change display settings
- Use
--rawif you already have screen coordinates - Check
calibrate.sh infoto see current settings
📝 Example Workflow
# 1. Take screenshot
scrot /tmp/screen.png
# 2. View in Claude, identify button at display coords (500, 300)
# 3. Click it
./scripts/click.sh 500 300
# 4. If off-target, calibrate
./scripts/calibrate.sh*Tested on: Ubuntu/Debian with X11, various resolutions and DPI settings*