[0xdhrv]

TinyHand's current shortcuts let launchers toggle the pointer, but they cannot reliably read its state, select a pointer, or update live preferences. This adds a versioned --ctl JSON interface that sends requests to the running app and returns its acknowledged native state. It is intended to support a Raycast integration and other local automation clients.

The bridge reuses the existing overlay, preferences, settings window, and custom-hand creator. It supports status/style discovery, idempotent on/off, toggle, clear, pointer/laser selection, toolbar pins, sound controls, and validated settings batches. All settings in a batch are validated before writing and refreshed through one native preferences notification.

The transport is a private Unix domain socket with same-user peer checks, directory/socket permissions, an exclusive server lock, allowlisted operations, size limits, and short deadlines. It opens no network port and does not require Accessibility permission for the client. TinyHand still requires its own Accessibility permission. The bundled CLI does not auto-launch the app or replay failed mutations.

Included:

• TinyHandControlVersion bundle marker and documented protocol, including startup, errors, and uncertain timeout outcomes.
• Native handler regression tests using in-memory dependencies, plus a real Unix socket round trip.
• A test step in the existing universal-build CI workflow.

Validation:

• bash scripts/test-control.sh — 27 checks passed.
• swift build -c release --arch arm64 --arch x86_64 (with an isolated scratch directory) — passed.
• git diff --cached --check — passed before commit.

This is a draft for feedback on the proposed external-control surface and IPC approach. Live Accessibility/input interception, rendering, multiple displays, full-screen apps, and the supported macOS runtime matrix still need manual validation. No Raycast extension files or generated binaries are included.

[nilbuild]

Thanks but I ended up going with a simpler version. TinyHand now has tinyhand:// links:

• tinyhand://on
• tinyhand://off
• tinyhand://toggle
• tinyhand://clear
• tinyhand://style/<id> (e.g. tinyhand://style/robot, tinyhand://style/laser)
• tinyhand://sound/on, tinyhand://sound/off, tinyhand://sound/toggle

There's also ~/Library/Application Support/TinyHand/state.json, which Raycast can read for the current state and the list of hands.