Omapoint

Independent pointing-device controls for Omarchy.

Omapoint is a local-first Linux control panel and radial action ring for supported pointing devices. It uses Solaar for hardware access and adds an Omarchy Quattro shell surface for configuration and actions. Device settings and action definitions stay on your machine.

Omapoint currently supports the Logitech MX Master 4. Logitech and MX Master are trademarks of Logitech Europe S.A. or its affiliates. Omapoint is an independent project and is not affiliated with, endorsed by, or sponsored by Logitech.

Not affiliated with or endorsed by 37signals or the Omarchy project. Omapoint does not use Omarchy or 37signals logos and does not claim official status.

Features

• A six-section Quickshell control panel for radial actions, button bindings, pointer and wheel behavior, haptics, device diagnostics, and maintenance.
• A draggable radial editor whose slots can be reordered or replaced.
• Application and Omarchy web-app discovery using the same visibility rules as the Omarchy launcher.
• A reviewed allowlist of Omarchy audio, launcher, bar, idle, night-light, notification, touchpad, and touchscreen actions.
• Custom actions represented as argument arrays, never shell command strings.
• Device capabilities probed through exclusive Solaar access instead of a hard-coded approximation.
• Transactional install, update, repair, migration, and uninstall operations with compare-before-restore ownership.

Requirements

• Omarchy Quattro with the third-party Shell plugin API.

• A currently supported pointing device. The initial release supports the Logitech MX Master 4.

• solaar, installed through Omarchy:

  omarchy pkg add solaar

Do not run another HID++ manager, such as logiops or Mouser, alongside Solaar.

Install

Omapoint uses Omarchy's native plugin checkout and a visible first-run setup inside the plugin. Omarchy deliberately does not run plugin hooks or sudo, so the initial clone is safe to review and the companion install remains an explicit user action.

Add and enable Omapoint:

omarchy plugin add https://github.com/spencerbull/omapoint.git --enable

Omapoint appears in the Omarchy bar. Select its pointer icon and open Setup & updates:

1. If needed, choose Install dependencies…. Package installation opens in a terminal so Omarchy can show and request any required authorization.
2. Choose Finish setup… with the device awake. The terminal shows progress and remains open on failure.

The setup validates the exact clean plugin checkout before changing live state. It installs the canonical CLI and launcher, one managed Solaar listener when needed, and a semantically owned section in ~/.config/solaar/rules.yaml. Existing unrelated rules and device settings are preserved. Until setup is complete, Omapoint disables device mutations and acts only as its setup surface.

For development or recovery, cloning the repository and running ./scripts/omapoint install --source "$PWD" remains supported. That mode owns an immutable plugin link instead of the native Omarchy checkout.

Migrating an earlier preview

If Pointstead or omarchy-mx-master is already installed, do not remove it first. Run the explicit migration from this repository:

./scripts/omapoint migrate --source "$PWD"

Migration verifies the owned legacy install and changes only its public-facing identity while preserving the existing config, device binding, Solaar service, rule bytes, release state, and rollback data. The pointstead and omarchy-mx-master executables remain compatibility aliases when required by the migrated install and its existing Solaar rules.

Use

Open Omapoint from Super+Space, or run:

omapoint ui

The Haptic Sense button is reserved for the radial ring by default. Other controls start in passthrough mode, so installing Omapoint does not replace the normal middle, back, forward, gesture, or SmartShift behavior.

In the Radial Ring section:

1. Add applications, web apps, Omarchy actions, or custom argument arrays.
2. Drag slots around the ring to reorder them.
3. Press Haptic Sense, move the pointer into a wedge, and release.
4. Press and release inside the dead zone to cancel.

Button Bindings can assign a single action or a five-way gesture (click, up, down, left, right) to supported controls. Pointer & Wheel and Haptics expose only settings reported by the connected device.

Operations

All commands return a stable JSON envelope.

omapoint status
omapoint doctor
omapoint doctor --repair
omapoint update --check
omapoint update --apply
omapoint uninstall

The Setup & updates page provides the same lifecycle for normal use. Update checks are read-only. For a native checkout, Review & update… opens Omarchy's interactive plugin updater so the upstream diff remains visible, then transactionally synchronizes the companion to that exact commit. A release-managed recovery install uses Omapoint's validated public-main updater. If plugin and companion versions differ, device mutations remain disabled until synchronization completes.

In development/recovery installs that own the plugin symlink, update --apply briefly restarts Omarchy Shell after switching the immutable release. Native Omarchy-checkout updates use Omarchy's own reload and do not perform that extra restart. Omapoint refuses a required restart while the session is locked.

uninstall restores only settings and files that still match Omapoint-owned values. It keeps the user configuration. Use omapoint uninstall --purge to remove that configuration as well. For a native checkout, use Uninstall companion… first, then remove Omapoint through Setup › Plugins. Removing the plugin through Omarchy alone is not a complete uninstall because Omarchy does not manage the companion service, CLI, rules, or ownership state.

status never starts a second Solaar client beside the persistent listener. It reports the last exclusively verified cache with explicit provenance and staleness, plus a bounded BlueZ transport observation that is not treated as authoritative device identity. If a mutation says the device is unavailable, move it once and retry that operation.

Privacy and security

Omapoint does not require an account, cloud service, or telemetry endpoint. It runs unsandboxed inside the long-lived Omarchy Shell process and can launch the actions you configure. Review custom action argument arrays before saving them and install only from a repository you trust.

The installer needs user-level access to XDG config/data paths, the Omarchy plugin directory, Solaar rules, and the user systemd manager. Package installation and any system-level Solaar permissions remain explicit Omarchy or distribution setup steps.

Development

Run the complete verification set without creating a virtual environment in the plugin tree:

verify_env=$(mktemp -d /tmp/omapoint-verify.XXXXXX)
UV_PROJECT_ENVIRONMENT="$verify_env" uv run --locked pytest -q
UV_PROJECT_ENVIRONMENT="$verify_env" uv run --locked ruff check .
UV_PROJECT_ENVIRONMENT="$verify_env" uv run --locked ruff format --check .
bash tests/run-qml-smoke
omarchy plugin validate .
git diff --check

The ownership model, event flow, failure behavior, and update contract are documented in docs/ARCHITECTURE.md.

License

Omapoint is available under the MIT License. Portions of the desktop application catalog are derived from Omarchy's MIT-licensed launcher; see THIRD_PARTY_NOTICES.