# MouseHerdr: a guide for AI agents

> MouseHerdr is a free, open-source (MIT) macOS menu bar app that puts your Herdr AI coding agents one thumb-tap away: tap the Logitech MX Master 4 thumb pad, or press the scroll wheel on almost any other mouse, for an agent wheel, then answer, approve or jump to any agent. It also remaps the buttons and drags and snaps windows, without Logi Options+.

MouseHerdr is a free, open-source (MIT) macOS menu bar app for the Logitech MX Master 4. When its user taps the mouse’s haptic thumb pad, a wheel of their Herdr AI coding agents appears around the pointer; from that wheel they read an agent’s question, answer it, approve or refuse a command, or jump to the agent in the Herdr app. It also remaps the mouse buttons, adds haptic feedback, and drags and snaps windows. It needs macOS 13 or later and [Herdr](https://herdr.dev/) for the agent features; the MX Master 4 must be connected over Bluetooth. Almost any other mouse works too, for the basics: pressing its scroll wheel opens the agent wheel. It is downloaded from [GitHub releases](https://github.com/royosherove/mouse-herdr/releases); mouseherdr.dev hosts no binaries.

## Installing it for someone

Download the latest release:

1. Download [MouseHerdr.zip](https://github.com/royosherove/mouse-herdr/releases/latest/download/MouseHerdr.zip) and unzip it.
2. Quit any running MouseHerdr, then drag **MouseHerdr.app** to **Applications**. Replace the older copy if you are updating; your assignments remain saved.
3. Open MouseHerdr from Applications. macOS may ask you to confirm opening an app downloaded from the internet.
4. Grant **Accessibility** and **Input Monitoring** (see below), then quit and reopen MouseHerdr.

New releases are **Developer ID signed and notarized by Apple**, with the notarization ticket included in the app. Releases published before signing was enabled remain ad-hoc signed; check their release notes. When upgrading from one of those releases or a source build, you may need to remove and re-add the Applications copy in Accessibility and Input Monitoring because its signing identity has changed.

Or build it from source: the [README’s prompt for coding agents](https://github.com/royosherove/mouse-herdr#building-from-source-for-agents) checks the toolchain, builds with local signing, runs the tests, installs the app and walks the user through the permissions.

For the agent wheel, the user also needs the [Herdr desktop app](https://github.com/herdrdev/herdr-app#install), whose installer also installs herdr-core (the `hc` command MouseHerdr uses).

## Reading mouseherdr.dev

In a browser, the home page is an interactive wheel: each wedge opens one section in a speech bubble, and “Read it as one page” shows them all. The HTML already has every section in reading order and needs no JavaScript. These plain-text versions are easier to read:

- [The home page as Markdown](https://mouseherdr.dev/index.md)
- [About MouseHerdr](https://mouseherdr.dev/about.md)
- [Site index for language models](https://mouseherdr.dev/llms.txt)
- [The full text of the site in one file](https://mouseherdr.dev/llms-full.txt)
- [About the author, Roy Osherove](https://mouseherdr.dev/about-roy.md)

## Links

- [MouseHerdr on GitHub](https://github.com/royosherove/mouse-herdr): Source, README and issues.
- [Releases](https://github.com/royosherove/mouse-herdr/releases): Every published build with its MouseHerdr.zip and SHA-256 checksum.
- [Download the latest MouseHerdr.zip](https://github.com/royosherove/mouse-herdr/releases/latest/download/MouseHerdr.zip): Direct link to the latest release asset.
- [Source files](https://github.com/royosherove/mouse-herdr/tree/main/Sources/MouseHerdr): The Swift sources described above.
- [The trailer on YouTube](https://www.youtube.com/watch?v=76AmPMwFGJI): MouseHerdr: Control Herdr Agents from your Mouse in One Thumb Tap.
- [Herdr](https://herdr.dev/): Where your agents run; needed for the agent features.
- [herdr-core on GitHub](https://github.com/herdrdev/herdr-core): The hc command MouseHerdr uses to read and answer agents.
- [Herdr desktop app on GitHub](https://github.com/herdrdev/herdr-app): The window MouseHerdr jumps to.
- [The README’s prompt for coding agents](https://github.com/royosherove/mouse-herdr#building-from-source-for-agents): build, test and install from source.
