hidpi-mouse

What This Skill Does

The hidpi-mouse skill provides a robust bridge between the coordinate system Claude uses when viewing your desktop and the actual pixel-grid of your Linux display. Because modern HiDPI (Retina) displays often use scaling factors (like 200% or 150%) to make text readable, a direct mapping from a screenshot to screen coordinates often results in misaligned clicks. This skill handles that translation layer automatically. It calculates the necessary ratio to ensure that when Claude identifies a button or UI element in its viewer, your mouse actually travels to that specific point on your hardware.

Installation

To install this skill, use the command: clawhub install openclaw/skills/skills/zeyuyuyu/hidpi-mouse. Once installed, it is highly recommended to perform an initial calibration to ensure accuracy. Run ./scripts/calibrate.sh to trigger the interactive setup, which will guide you through mapping a reference image to your screen's layout. This process creates a cache file that persists your settings for future automation tasks, ensuring precision across restarts.

Use Cases

• Cross-Platform Consistency: Ensure that an automation script written on a 1080p monitor works perfectly when moved to a 4K HiDPI setup.
• Complex GUI Interaction: Reliably interact with legacy applications that do not expose accessibility hooks, requiring coordinate-based mouse input.
• Precision Desktop Automation: Perform repetitive tasks like clicking specific menu items, resizing windows, or interacting with dashboard elements that occupy fixed spatial coordinates.

Example Prompts

1. "Click on the submit button at coordinates 850, 420 using the hidpi-mouse skill."
2. "Double click the system settings icon located at 1200, 300."
3. "Run a calibration test to ensure my current scale factor is correctly identifying the top-left corner of the workspace."

Tips & Limitations

• Always Calibrate First: Scaling isn't always a perfect integer; monitor sub-pixel layouts can vary. A manual calibration is always safer than relying on auto-detection.
• Multi-Monitor Awareness: By default, this tool targets the primary display. If you have a multi-monitor setup, ensure your primary display is configured correctly in your Linux system settings before calibrating.
• Cache TTL: If you change your screen resolution or DPI settings, remember to run ./scripts/calibrate.sh reset to clear the old cache and re-detect the new display parameters.
• Manual Overrides: If the auto-detection fails, use the ./scripts/calibrate.sh set <value> command to manually inject your known scale factor, which takes highest priority in the configuration hierarchy.