HiDPI Mouse

---

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 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             # Auto-scaled click
./scripts/click.sh --raw       # No scaling (screen coords)
./scripts/click.sh --double    # Double click
./scripts/click.sh --right     # Right click

calibrate.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-detect

detect-scale.sh - Get scale factor

./scripts/detect-scale.sh           # Returns scale (e.g., 2.08)

Other scripts

./scripts/move.sh             # Move mouse
./scripts/drag.sh      # Drag
./scripts/reliable_click.sh   [--window "Name" --relative]

🎯 Calibration (Recommended for New Systems)

For best accuracy on your specific system:

./scripts/calibrate.sh

This will: 1. Create a calibration image with markers at known positions 2. Ask you where the markers appear in Claude's display 3. 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 values

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

1. Always calibrate on a new system for 100% accuracy 2. Re-calibrate if you change display settings 3. Use --raw if you already have screen coordinates 4. Check calibrate.sh info to 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*