| 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
./scripts/click.sh 500 300
./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 Coords
The 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>
./scripts/click.sh --raw <x> <y>
./scripts/click.sh --double <x> <y>
./scripts/click.sh --right <x> <y>
calibrate.sh - Setup & Configuration
./scripts/calibrate.sh
./scripts/calibrate.sh info
./scripts/calibrate.sh test
./scripts/calibrate.sh set 2.08
./scripts/calibrate.sh reset
detect-scale.sh - Get scale factor
./scripts/detect-scale.sh
Other scripts
./scripts/move.sh <x> <y>
./scripts/drag.sh <x1> <y1> <x2> <y2>
./scripts/reliable_click.sh <x> <y> [--window "Name" --relative]
🎯 Calibration (Recommended for New Systems)
For best accuracy on your specific system:
./scripts/calibrate.sh
This 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
./scripts/calibrate.sh
./scripts/calibrate.sh set 2.1
Check current configuration
./scripts/calibrate.sh info
Reset 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
--raw if you already have screen coordinates
- Check
calibrate.sh info to see current settings
📝 Example Workflow
scrot /tmp/screen.png
./scripts/click.sh 500 300
./scripts/calibrate.sh
Tested on: Ubuntu/Debian with X11, various resolutions and DPI settings