功能描述

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.

使用说明 (SKILL.md)

HiDPI Mouse Skill

Name: HiDPI Mouse
Author: zeyuyuyu

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 \x3Cx> \x3Cy>           # Auto-scaled click
./scripts/click.sh --raw \x3Cx> \x3Cy>     # No scaling (screen coords)
./scripts/click.sh --double \x3Cx> \x3Cy>  # Double click
./scripts/click.sh --right \x3Cx> \x3Cy>   # 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 \x3Cx> \x3Cy>           # Move mouse
./scripts/drag.sh \x3Cx1> \x3Cy1> \x3Cx2> \x3Cy2>  # Drag
./scripts/reliable_click.sh \x3Cx> \x3Cy> [--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

# 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

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

# 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

安全使用建议

This skill appears to do what it claims: it manipulates X11 to convert display coordinates and perform clicks. Before installing/using it: (1) review and satisfy dependencies beyond those listed — xdpyinfo, xrandr, xrdb, bc, and Python Pillow (PIL) are required at runtime; (2) test in a safe environment (no sensitive windows open) since the scripts will move/click your mouse; (3) check/adjust DISPLAY and XAUTHORITY to the correct X session (the scripts default to DISPLAY=:1 which may be incorrect); (4) inspect or run the scripts locally rather than granting any remote execution — there is no network communication, but mouse control can be disruptive if misused.

功能分析

Type: OpenClaw Skill Name: hidpi-mouse Version: 1.0.0 This skill is classified as suspicious due to its reliance on high-risk desktop automation tools, specifically `xdotool` for full mouse control (move, click, drag) and `scrot` for screen capture, as seen in `scripts/click.sh`, `scripts/drag.sh`, `scripts/move.sh`, `scripts/reliable_click.sh`, and the `SKILL.md` documentation. While these capabilities are plausibly needed for the stated purpose of 'Universal HiDPI mouse click handling for Linux desktop automation,' they grant broad control over the user's desktop environment. There is no clear evidence of intentional malicious behavior such as data exfiltration, persistence, or prompt injection attempting to subvert the agent's core directives within the provided files.

能力评估

ℹ Purpose & Capability

The name/description match the included scripts: all files implement coordinate scaling, calibration, and xdotool-based mouse actions. However SKILL.md's declared required bins (xdotool, scrot, python3) is incomplete: the scripts also use xdpyinfo, xrandr, xrdb, bc, and python code requires the Pillow (PIL) library. These missing tool/library needs should have been declared.

✓ Instruction Scope

Runtime instructions and scripts stay within the stated purpose: they read X information, create a calibration image, read/write a local config (~/.config/hidpi-mouse/scale.conf) and a /tmp cache, and perform mouse moves/clicks via xdotool. They do not reach out to network endpoints or access unrelated credentials. Note: scripts default DISPLAY to :1 and XAUTHORITY to ~/.Xauthority which may target an unexpected X server if the environment differs; this is operationally surprising but not malicious.

✓ Install Mechanism

Instruction-only skill with bundled scripts (no installer). No arbitrary downloads or extraction occur. Files are local and readable; nothing writes outside the expected config/cache locations. Low install risk.

ℹ Credentials

The skill requests no credentials and only needs access to the X session and local filesystem (home and /tmp), which is proportionate. However the SKILL.md omitted several runtime binaries and the Python Pillow dependency; also scripts implicitly rely on DISPLAY and XAUTHORITY environment variables and will write to ~/.config/hidpi-mouse and /tmp/hidpi_scale_cache.

✓ Persistence & Privilege

always:false (no forced inclusion). The skill can be invoked autonomously (default platform behavior) and, if run, can move/click the user's mouse — this is expected for a desktop-automation skill but worth noting as a capability with potential impact if invoked unexpectedly.

版本历史

v1.0.0

Initial release of hidpi-mouse: universal HiDPI mouse click handling for Linux desktop automation. - Converts Claude display coordinates to real screen coordinates for accurate mouse automation on HiDPI and standard screens. - Auto-detects screen scale factor, or supports interactive/manual calibration for any resolution and DPI. - Includes a suite of handy scripts: click, double-click, right-click, drag, mouse move, and reliable click, all with scale correction. - Calibration workflow to ensure precision on all systems; configuration easily managed and reset. - Compatible with various Linux/X11 desktop environments and adaptable to different screen/DPI setups.

元数据

Slug hidpi-mouse

版本 1.0.0

许可证 —

累计安装 2

当前安装数 2

历史版本数 1

常见问题

HiDPI Mouse 是什么？

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. 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 1698 次。

如何安装 HiDPI Mouse？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install hidpi-mouse」即可一键安装，无需额外配置。

HiDPI Mouse 是免费的吗？

是的，HiDPI Mouse 完全免费（开源免费），可自由下载、安装和使用。

HiDPI Mouse 支持哪些平台？

HiDPI Mouse 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 HiDPI Mouse？

由 zeyuyuyu（@zeyuyuyu）开发并维护，当前版本 v1.0.0。

HiDPI Mouse